AI Agent Skills 技能系统

Skills（技能）是一种强大的可复用指令包，让 AI 助手能够动态加载专业能力，以更好地完成特定任务。无论是创建符合公司品牌规范的文档、按照组织特定工作流分析数据，还是自动化个人任务，Skills 都能让 AI 以可重复的方式完成这些工作。

支持平台

本文档涵盖两大主流 AI 助手平台的 Skills 功能：

Claude - Anthropic 的 AI 助手（Claude Code、Claude.ai、Claude API）
Codex CLI - OpenAI 的命令行 AI 编程助手

概述

什么是 Skills

Skills（技能）是包含指令、脚本和资源的文件夹，AI 助手可以动态加载这些内容来提升特定任务的执行能力。每个 Skill 都是一个自包含的包，包含：

名称（name） - 技能的唯一标识符
描述（description） - 说明技能的功能和使用场景
指令正文 - 详细的操作指南、示例和参考资料

当你激活一个 Skill 时，AI 助手会加载其中的指令，按照预定义的方式完成任务。这让 AI 能够以可重复、一致的方式处理专业任务。

Skills 的价值

价值	说明
可复用性	一次创建，多次使用，避免重复编写相同的提示词
一致性	确保 AI 每次都按照相同的标准和流程执行任务
专业化	针对特定领域或任务进行深度优化
可分享	团队成员可以共享技能，统一工作标准
可维护	集中管理和更新指令，便于迭代改进

Skills vs 普通提示词

特性	普通提示词	Skills
复用性	需要每次重新输入	保存后可随时调用
复杂度	适合简单任务	可包含复杂的多步骤指令
维护性	分散在各处	集中管理，易于更新
协作性	难以分享	可导出、分享给团队
上下文	单次对话	可包含参考资料和示例

何时使用 Skills

如果你发现自己经常向 AI 输入相同或类似的提示词，或者需要 AI 按照特定的格式、流程完成任务，那么创建一个 Skill 会是更好的选择。

适用场景

Skills 适用于各种专业任务场景：

🎨 创意与设计

按照品牌规范创建设计稿
生成符合风格指南的文案
音乐创作和艺术指导

💻 开发与技术

代码生成和重构
测试 Web 应用
MCP 服务器生成
代码审查和优化

🏢 企业与沟通

按照公司模板撰写文档
品牌传播和营销内容
会议纪要和报告生成

📄 文档处理

PDF 文本和表格提取
Word/Excel/PPT 文档创建
表单填写和数据处理

平台支持

Claude 平台

Claude 的 Skills 功能已在多个平台上正式可用，包括 Claude Code、Claude.ai 和 Claude API。

Claude Code 安装 Skills

你可以通过插件市场安装官方技能包：

注册技能仓库：

bash

/plugin marketplace add anthropics/skills

安装技能包：

选择 Browse and install plugins
选择 anthropic-agent-skills
选择 document-skills 或 example-skills
选择 Install now

或者直接通过命令安装：

bash

/plugin install document-skills@anthropic-agent-skills
/plugin install example-skills@anthropic-agent-skills

使用技能：

安装插件后，只需在对话中提及技能名称即可。例如，安装 document-skills 后，你可以这样使用：

使用 PDF 技能从 `path/to/some-file.pdf` 中提取表单字段

在 Claude.ai 中使用

Claude.ai 的付费用户可以直接使用所有示例技能。

要使用自定义技能或上传新技能，请参考官方指南：Using skills in Claude（英文）

通过 Claude API 使用

你可以通过 Claude API 使用 Anthropic 的预置技能，也可以上传自定义技能。

详细信息请参考：Skills API Quickstart（英文）

Codex CLI 平台

实验性功能

Codex CLI 的 Skills 功能目前是实验性的，可能会有破坏性更改。如果你依赖此功能，请预期在未来可能会有变动。使用风险自负！

Codex 可以自动发现你保存在磁盘上的可复用技能。技能是一个小型包，包含名称、简短描述，以及一个可选的指令正文。Codex 仅将名称、描述和文件路径注入到运行时上下文中；正文内容保留在磁盘上。

Codex CLI 安装 Skills

Skills 功能默认禁用，需要手动启用。

方式一：在配置文件中启用（推荐）

在 ~/.codex/config.toml 中添加以下内容：

toml

[features]
skills = true

保存后重启 Codex 即可生效。

方式二：单次运行启用

使用命令行参数启动：

bash

codex --enable skills

技能存储位置

存储路径: ~/.codex/skills/**/SKILL.md（递归搜索）
隐藏条目（以 . 开头）和符号链接会被跳过
只有名为 SKILL.md 的文件才会被识别
排序规则: 按名称排序，然后按路径排序以保持稳定性

使用技能

方式一：在消息中提及

使用 $<skill-name> 语法来调用技能：

$pdf-processing 请帮我提取这个 PDF 中的表格数据

方式二：使用 /skills 命令

在 TUI（终端用户界面）中，使用 /skills 命令来浏览和插入技能。

加载机制

技能在 Codex 启动时加载一次
如果存在有效的技能，Codex 会在 AGENTS.md 之后追加一个 ## Skills 部分
每个技能显示为：- <name>: <description> (file: /absolute/path/to/SKILL.md)
磁盘上的文件永远不会被修改

验证与错误处理

无效的技能（缺少/无效的 YAML、空字段或超长字段）会在 TUI 中触发一个阻塞式、可关闭的启动模态框，列出每个路径和错误。

你可以关闭模态框继续使用（无效的技能会被忽略）
或者退出程序，修复 SKILL.md 文件后重启

创建自定义 Skill

文件结构

一个 Skill 就是一个包含 SKILL.md 文件的文件夹。基本结构如下：

~/.codex/skills/           # Codex CLI 技能目录
└── my-skill/              # 技能文件夹
    └── SKILL.md           # 技能定义文件

你也可以在技能文件夹中包含其他资源文件：

my-skill/
├── SKILL.md               # 主技能文件
├── templates/             # 模板文件
├── examples/              # 示例文件
└── REFERENCE.md           # 参考文档

SKILL.md 格式规范

技能文件采用 YAML frontmatter + Markdown 正文的格式：

markdown

---
name: my-skill-name
description: 清晰描述这个技能的功能和使用场景
---

# 我的技能名称

[在这里添加 AI 激活此技能时需要遵循的指令]

示例：
- 使用示例 1
- 使用示例 2

指南：
- 指南 1
- 指南 2

Frontmatter 字段说明

字段	必需	说明
`name`	✅	技能的唯一标识符，使用小写字母和连字符
`description`	✅	技能的完整描述，说明功能和使用场景

字段要求

name: 非空，建议使用 kebab-case 格式（如 pdf-processing）
description: 非空，清晰描述技能的功能和触发场景

正文内容可以包含：

详细的操作指令
使用示例
参考资料链接
注意事项和限制

平台差异对比

特性	Claude	Codex CLI
功能状态	正式功能	实验性功能
存储位置	云端/本地	`~/.codex/skills/`
文件名	SKILL.md	SKILL.md
调用方式	自动识别/手动	`$skill-name` 或 `/skills`
name 限制	无明确限制	≤100 字符
description 限制	无明确限制	≤500 字符
正文注入	可配置	不注入到上下文

Codex CLI 字段限制

在 Codex CLI 中：

name 字段不能超过 100 个字符
description 字段不能超过 500 个字符
字段内容会被清理为单行，避免使用换行符

实战示例

代码生成类示例

React 组件生成器

创建技能目录和文件：

bash

mkdir -p ~/.codex/skills/react-component

~/.codex/skills/react-component/SKILL.md:

markdown

---
name: react-component
description: 使用 TypeScript 生成 React 组件，遵循 hooks、props 类型定义和文件结构的最佳实践。在创建新的 React 组件或重构现有组件时使用。
---

# React 组件生成器

组件结构：
- 使用 TypeScript 函数式组件
- 在组件上方定义 props 接口
- 使用命名导出
- 为复杂的 props 添加 JSDoc 注释

文件命名：
- 组件文件：PascalCase 格式（如 `UserProfile.tsx`）
- 样式文件：相同名称加 `.module.css` 后缀
- 测试文件：相同名称加 `.test.tsx` 后缀

输出示例：
```tsx
interface UserCardProps {
  name: string;
  avatarUrl?: string;
  onClick?: () => void;
}

export function UserCard({ name, avatarUrl, onClick }: UserCardProps) {
  return (
    <div className={styles.card} onClick={onClick}>
      {avatarUrl && <img src={avatarUrl} alt={name} />}
      <span>{name}</span>
    </div>
  );
}
```

指南：
- 始终包含 prop 类型定义
- 使用语义化 HTML 元素
- 确保可访问性（aria 标签、键盘导航）
- 保持组件专注和单一职责

文档处理类示例

PDF 处理技能

bash

mkdir -p ~/.codex/skills/pdf-processing

~/.codex/skills/pdf-processing/SKILL.md:

markdown

---
name: pdf-processing
description: 从 PDF 文档中提取文本、表格和表单字段。在提到 PDF、表单或文档提取时使用。
---

# PDF 处理

功能：
- 从 PDF 页面提取纯文本
- 将表格解析为结构化数据
- 读取表单字段值
- 处理多页文档

推荐工具：
- 使用 pdfplumber 进行文本和表格提取
- 使用 PyPDF2 读取表单字段
- 使用 pdf2image 处理基于图像的 PDF（配合 OCR）

使用示例：
```python
import pdfplumber

def extract_tables(pdf_path):
    tables = []
    with pdfplumber.open(pdf_path) as pdf:
        for page in pdf.pages:
            page_tables = page.extract_tables()
            tables.extend(page_tables)
    return tables
```

指南：
- 始终优雅地处理编码问题
- 对于扫描的 PDF，建议使用 OCR 方法
- 尽可能保留表格结构
- 在可用时报告提取置信度

工作流自动化示例

Git 提交规范检查器

bash

mkdir -p ~/.codex/skills/git-commit

~/.codex/skills/git-commit/SKILL.md:

markdown

---
name: git-commit
description: 按照 Conventional Commits 规范生成和验证 Git 提交信息。在提交代码更改或审查提交历史时使用。
---

# Git 提交信息生成器

Conventional Commits 格式：
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]

提交类型：
- feat: 新功能
- fix: Bug 修复
- docs: 仅文档更改
- style: 代码风格（格式化、分号等）
- refactor: 代码重构
- perf: 性能优化
- test: 添加或更新测试
- chore: 维护任务

示例：
feat(auth): add OAuth2 login support
fix(api): handle null response in user endpoint

指南：
- 主题行保持在 72 个字符以内
- 使用祈使语气（"add" 而不是 "added"）
- 主题行末尾不加句号
- 用空行分隔主题和正文
- 在页脚引用相关 issue

最佳实践

命名规范

技能名称（name）

规则	示例
使用小写字母	✅ `pdf-processing` ❌ `PDF-Processing`
用连字符分隔单词	✅ `react-component` ❌ `react_component`
简洁明了	✅ `git-commit` ❌ `git-commit-message-generator-v2`
反映功能	✅ `code-review` ❌ `my-skill-1`

技能文件夹

建议文件夹名称与技能名称保持一致：

~/.codex/skills/
├── pdf-processing/      # 与 name: pdf-processing 一致
├── react-component/     # 与 name: react-component 一致
└── git-commit/          # 与 name: git-commit 一致

描述编写技巧

一个好的描述应该包含两部分：

功能说明 - 这个技能能做什么
触发场景 - 什么时候应该使用这个技能

描述模板

[功能说明]; 在 [触发场景] 时使用。

好的描述示例：

yaml

# ✅ 清晰的功能 + 明确的触发场景
description: 从 PDF 中提取文本和表格；在提到 PDF、表单或文档提取时使用。

# ✅ 具体的功能 + 多个触发场景
description: 使用 TypeScript 和最佳实践生成 React 组件；在创建新组件、重构 UI 或讨论 React 模式时使用。

避免的描述：

yaml

# ❌ 太模糊
description: 帮助处理 PDF。

# ❌ 没有触发场景
description: 一个处理文档的技能。

# ❌ 太长（Codex CLI 限制 500 字符）
description: 这是一个非常全面的技能，可以做很多事情，包括但不限于...

常见问题

Q: 技能没有被加载怎么办？

A: 检查以下几点：

文件名是否为 SKILL.md（区分大小写）
YAML frontmatter 格式是否正确（--- 包围）
name 和 description 字段是否都存在且非空
对于 Codex CLI，确认已启用 skills 功能

Q: 如何调试技能内容？

Claude: 在对话中询问 "What skills do you have access to?"
Codex CLI: 使用 /skills 命令查看已加载的技能列表

Q: 技能正文会被注入到上下文吗？

Claude: 根据配置，可能会注入
Codex CLI: 正文不会自动注入，仅在被调用时读取

Q: 可以在技能中引用其他文件吗？

A: 可以。在技能正文中引用同目录下的其他文件，AI 会在需要时读取这些文件。

Q: 如何更新已加载的技能？

修改 SKILL.md 文件后
Claude Code: 重新加载插件
Codex CLI: 重启 Codex

合作伙伴 Skills

Skills 是教会 AI 更好地使用特定软件的绝佳方式。一些官方合作伙伴已经提供了高质量的技能包：

合作伙伴	技能包	说明
Notion	Notion Skills for Claude（英文）	帮助 Claude 更好地操作 Notion 工作区

官方技能仓库

Anthropic 官方维护了一个技能示例仓库，包含创意设计、技术开发、企业沟通和文档处理等多个类别的技能：

仓库地址：anthropics/skills（英文）
包含 Claude 文档功能背后使用的 docx、pdf、pptx、xlsx 技能
大部分技能采用 Apache 2.0 开源协议

发现更多技能

Claude Code 插件市场 - 使用 /plugin marketplace 浏览可用技能
GitHub 搜索 - 搜索 "SKILL.md" 或 "claude skills" 发现社区技能
官方文档 - 关注 Anthropic 和 OpenAI 的更新公告

参考资源

安装指南

Claude Code 使用教程 - Claude Code 安装和入门指南
Codex CLI 使用教程 - Codex CLI 安装和入门指南

Claude 官方文档

What are skills?（英文） - Skills 功能介绍
Using skills in Claude（英文） - 在 Claude 中使用技能
How to create custom skills（英文） - 创建自定义技能指南
Skills API Quickstart（英文） - API 使用指南
Equipping agents for the real world with Agent Skills（英文） - 技术博客

Codex CLI 相关

Codex CLI Skills 技能功能 - 本站 Codex Skills 详细文档
Codex CLI 配置参考 - Codex 配置说明

AI Agent Skills 技能系统 ​

概述 ​

什么是 Skills ​

Skills 的价值 ​

Skills vs 普通提示词 ​

适用场景 ​

平台支持 ​

Claude 平台 ​

Claude Code 安装 Skills ​

在 Claude.ai 中使用 ​

通过 Claude API 使用 ​

Codex CLI 平台 ​

Codex CLI 安装 Skills ​

技能存储位置 ​

使用技能 ​

加载机制 ​

验证与错误处理 ​

创建自定义 Skill ​

文件结构 ​

SKILL.md 格式规范 ​

Frontmatter 字段说明 ​

平台差异对比 ​

实战示例 ​

代码生成类示例 ​

文档处理类示例 ​

工作流自动化示例 ​

最佳实践 ​

命名规范 ​

描述编写技巧 ​

常见问题 ​

合作伙伴 Skills ​

发现更多技能 ​

参考资源 ​

安装指南 ​

Claude 官方文档 ​

Codex CLI 相关 ​

相关文档 ​

AI Agent Skills 技能系统

概述

什么是 Skills

Skills 的价值

Skills vs 普通提示词

适用场景

平台支持

Claude 平台

Claude Code 安装 Skills

在 Claude.ai 中使用

通过 Claude API 使用

Codex CLI 平台

Codex CLI 安装 Skills

技能存储位置

使用技能

加载机制

验证与错误处理

创建自定义 Skill

文件结构

SKILL.md 格式规范

Frontmatter 字段说明

平台差异对比

实战示例

代码生成类示例

文档处理类示例

工作流自动化示例

最佳实践

命名规范

描述编写技巧

常见问题

合作伙伴 Skills

发现更多技能

参考资源

安装指南

Claude 官方文档

Codex CLI 相关

相关文档