大模型世界新宠，从Claude走向开源，OpenAI 入局，Agent Skills 10000字教程

大家好，我是 Ai 学习的老章

今天聊一个我觉得被严重低估的东西——Agent Skills（智能体技能）

如果你一直关注 AI Agent 领域，可能听说过 MCP（Model Context Protocol），那玩意儿去年炒得火热。但今天我要说的是，Skills 可能比 MCP 更值得关注。Simon Willison（那个老牌技术博主）直接说：Skills 可能比 MCP 更重要（Claude Skills are awesome, maybe a bigger deal than MCP）。

为什么这么说？往下看你就明白了。

一、什么是 Agent Skills？

简单来说，Skill 就是一个教 AI 怎么干活的「技能手册」。

你可以把它理解成：

• 以前用 prompt 告诉 AI "你要这样做、那样做"
• 现在把这些指令打包成一个「技能包」，AI 自己翻阅、自己执行

它本质上是一个文件夹，里面装着：

Skill 技能包目录结构

Skill 技能包目录结构

• **SKILL.md**（必须）：告诉 AI 这个技能是干嘛的、怎么用，包含 YAML 元数据 + Markdown 指令
• **scripts/**（可选）：可执行的脚本，Python、Bash、JavaScript 都行
• **references/**（可选）：参考文档，技术细节、领域知识
• **assets/**（可选）：模板、图片、配置文件等静态资源

就这么简单！没有复杂的协议规范，没有 SDK 依赖，纯 Markdown + YAML，人能读、AI 也能读。

一个最简 Skill 长什么样？

---
name: code-reviewer
description: Review code for security issues and best practices. Use when user asks for code review.
---

# Code Review Skill

## Instructions
1. 检查常见安全漏洞（SQL 注入、XSS、命令注入等）
2. 评估性能问题和代码异味
3. 检查代码风格一致性
4. 给出具体的改进建议和代码示例

## Output Format
每个问题按以下格式输出：
- **Severity**: Critical / High / Medium / Low
- **Location**: 文件名:行号
- **Issue**: 问题描述
- **Fix**: 修复建议

## Examples
输入: "Review this Python function for security issues"
输出: 按格式给出安全审查报告

这就是一个完整的 Skill！丢进 Claude 或 Codex 的技能目录，AI 下次遇到代码审查任务就会自动调用。

二、Skills 凭什么比 MCP 厉害？

MCP（Model Context Protocol）去年很火，几乎成了"AI 接入外部工具"的代名词。但用过的人都知道，MCP 的槽点也不少。

MCP 的三大问题：

而 Skills 呢？

Skills 渐进式披露架构

Skills 渐进式披露架构

Skills 采用渐进式披露（Progressive Disclosure）机制，Token 效率极高：

这意味着：你可以装 20+ 个技能包，AI 启动时每个只占 100 tokens 左右（总共 2000 tokens），真正执行时才加载完整指令。

Simon Willison 这段话我觉得特别到位：

"Skills are Markdown with a tiny bit of YAML metadata and some optional scripts in whatever you can make executable in the environment. They feel a lot closer to the spirit of LLMs—throw in some text and let the model figure it out."

翻译一下就是：Skills 就是 Markdown 加上一点点 YAML 元数据，再配几个可执行脚本。这玩意儿更接近 LLM 的精神——丢点文本进去，让模型自己搞定。

相比 MCP 那套复杂的协议规范，Skills 简直是降维打击。

三、Agent Skills 规范详解

Agent Skills 是一个开放格式，由 Anthropic 主导维护，已被 OpenAI Codex、Claude 等产品采用。官方网站是 agentskills.io[1]。

3.1 目录结构

一个完整的 Skill 目录结构如下：

my-skill/
├── SKILL.md          # 必须：指令 + 元数据
├── scripts/          # 可选：可执行脚本
│   └── helper.py
├── references/       # 可选：参考文档
│   └── REFERENCE.md
└── assets/           # 可选：模板、资源
    └── template.json

3.2 SKILL.md 文件格式

SKILL.md 是唯一必须的文件，采用 YAML Frontmatter + Markdown Body 的格式：

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files.
license: Apache-2.0
compatibility: Requires Python 3.9+, pdfplumber, pypdf packages
metadata:
  author: anthropic
  version: "1.2.0"
allowed-tools: Bash(python:*) Read Write
---

# PDF Processing Skill

## Overview
This skill enables comprehensive PDF manipulation...

## Instructions
1. 文本提取：使用 pdfplumber 提取文本内容
2. 表格处理：识别并提取表格数据为 DataFrame
3. 表单填充：使用 pypdf 填充 PDF 表单字段
4. 文档合并：将多个 PDF 合并为一个文档

## Examples
...

3.3 Frontmatter 字段详解

name 字段的正确示例：

name: pdf-processing    # ✅ 正确
name: data-analysis     # ✅ 正确
name: code-review       # ✅ 正确

错误示例：

name: PDF-Processing    # ❌ 不能大写
name: -pdf              # ❌ 不能以连字符开头
name: pdf--processing   # ❌ 不能连续连字符

description 字段的最佳实践：

好的描述应该同时说明做什么和什么时候用：

# ✅ 好的描述
description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

# ❌ 差的描述
description: Helps with PDFs.

3.4 可选目录详解

scripts/ 目录：

• 存放可执行脚本（Python、Bash、JavaScript 等）
• 脚本应当自包含或清晰说明依赖
• 包含友好的错误信息处理

references/ 目录：

• 存放额外的文档，AI 按需读取
• 推荐的文件：REFERENCE.md（技术参考）、FORMS.md（表单模板）
• 保持单个文件聚焦，小文件意味着更少的 context 占用

assets/ 目录：

• 存放静态资源：模板、图片、配置文件
• 避免放大型二进制文件

3.5 编写最佳实践

1. 保持 SKILL.md 在 500 行以内：详细的参考资料移到 references/
2. 文件引用用相对路径：从 skill 根目录算起，如 references/REFERENCE.md
3. 避免深层嵌套引用：保持文件引用一层深度
4. 使用 skills-ref 工具验证：

# 安装验证工具
npm install -g @agentskills/skills-ref

# 验证技能包
skills-ref validate ./my-skill

四、Skills 在各平台的使用方式

目前 Skills 主要在以下平台支持：

4.1 Claude.ai 网页版

1. 进入 Settings > Capabilities[2]
2. 开启 Skills 开关
3. 可以启用官方 Skills 或上传自定义 Skills

用户可用性：

• Pro、Max、Team、Enterprise 用户可用
• Free 用户不可用

4.2 Claude Code CLI

Claude Code 从以下位置加载 Skills（按优先级从高到低）：

安装官方技能：

# 注册官方技能市场
/plugin marketplace add anthropics/skills

# 安装文档技能包
/plugin install document-skills@anthropic-agent-skills

# 安装示例技能包
/plugin install example-skills@anthropic-agent-skills

# 安装单个技能
$skill-installer linear
$skill-installer notion-spec-to-implementation

使用技能：

有两种触发方式：

1. 显式调用：使用 /skills 命令或 $ 前缀提及技能名
2. 隐式调用：AI 根据任务自动选择合适的技能

# 显式调用
$pdf "Extract all tables from report.pdf"

# 隐式调用（AI 自动选择）
"Help me extract the form fields from invoice.pdf"

4.3 Claude API

通过 /v1/skills 端点使用：

from anthropic import Anthropic

client = Anthropic()

# 上传自定义技能
with open("my-skill/SKILL.md", "rb") as f:
    skill = client.beta.skills.create(
        display_title="My Custom Skill",
        files=[{"path": "SKILL.md", "content": f.read()}]
    )

# 在会话中使用技能
container = client.beta.messages.create_container(
    skills={skill.id: "latest"}  # 或指定具体版本号
)

response = client.beta.messages.create(
    container_id=container.id,
    messages=[{
        "role": "user",
        "content": "Use the skill to process my document"
    }]
)
print(response.content)

版本管理：

• 开发阶段使用 "latest" 便于迭代
• 生产环境 pin 到具体版本号保证稳定

4.4 OpenAI Codex

Codex 完全采用了 Agent Skills 规范[3]，使用方式类似：

# 使用内置的技能创建器
$skill-creator

# 使用安装器
$skill-installer create-plan

# 从其他仓库安装
$skill-installer https://github.com/xxx/xxx

五、官方 Skills 一览

Anthropic 官方在 anthropics/skills[4] 仓库提供了一批开箱即用的技能：

5.1 文档处理技能

这些技能支撑了 Claude 的文档创建功能：

⚠️ 注意：文档技能是 source-available（可查看源码）但非开源（Apache 2.0），供开发者参考。

5.2 创意设计技能

5.3 开发技术技能

5.4 企业沟通技能

5.5 技能创建工具

六、社区生态资源

Skills 的社区也在快速发展：

6.1 精选技能集合

obra/superpowers[19]

• 20+ 实战验证的技能
• 包含 TDD、调试、协作模式
• 提供 /brainstorm、/write-plan、/execute-plan 等命令
• 安装方式：/plugin marketplace add obra/superpowers-marketplace

awesome-claude-skills[20]

• 完整的 Claude Skills 资源整理
• 官方文档、社区教程、工具汇总
• 持续更新中

6.2 社区单独技能

6.3 工具

**Skill_Seekers[25]**：把文档网站自动转换成 Claude Skill

七、Skills vs MCP vs Subagents：什么时候用什么？

这三个概念容易混淆，我给你划个重点：

Skills vs MCP vs Subagents 对比

Skills vs MCP vs Subagents 对比

一句话总结：

• Skills = 教 AI 怎么做（可移植的专业知识）
• MCP = 给 AI 连接数据（外部数据源和 API）
• Subagents = 让 AI 分身干活（独立运行的子任务）

详细对比表：

组合使用示例：竞品分析 Agent

1. 用 MCP 连接：Google Drive（内部资料）、GitHub（竞品仓库）、Web Search（实时信息）
2. 用 Skill 教会：竞品分析框架、内部 Drive 目录结构、报告格式规范
3. 用 Subagent 分工：
   - market-researcher：收集市场数据
   - technical-analyst：分析技术架构
   - 两者并行工作，最后合并结果

八、手把手创建你的第一个 Skill

方法一：使用 skill-creator（推荐）

最简单的方式是让 Claude 帮你创建：

请使用 skill-creator 帮我创建一个技能，用于 [描述你的场景]

Claude 会交互式引导你：

1. 这个技能解决什么问题？
2. 需要哪些输入参数？
3. 输出格式是什么？
4. 有什么特殊规则？

最后自动生成完整的 Skill 目录结构。

方法二：手动创建

Step 1：创建目录结构

mkdir -p my-skill/scripts
cd my-skill

Step 2：编写 SKILL.md

---
name: weekly-report-generator
description: Generate a structured weekly report with accomplishments, blockers, and next steps. Use when user asks for weekly report or status update.
---

# Weekly Report Generator

## Overview
This skill creates consistent, professional weekly status reports.

## Instructions
1. 收集以下信息：
   - 本周完成的工作（accomplishments）
   - 遇到的阻塞问题（blockers）
   - 下周计划（next steps）
   - 报告周期（如 2026-01-01 ~ 2026-01-07）

2. 格式要求：
   - 使用 Markdown 格式
   - 每个部分用 bullet points
   - 重点成果加粗
   - 阻塞问题标注优先级

3. 输出结构：
   ```markdown
   # Weekly Report: [Period]
   
   ## ✅ Accomplishments
   - **[重点成果]**: 描述
   - [普通成果]: 描述
   
   ## 🚧 Blockers
   - [P0/P1/P2] 问题描述 | 影响 | 期望解决方式
   
   ## 📌 Next Week
   - 计划1
   - 计划2

Example

Input: "生成一份本周周报，我完成了 Agent Skills 技术调研、修复了 3 个 bug，遇到的问题是测试环境不稳定"

Output: 按上述格式的完整周报

**Step 3：验证并安装**

```bash
# 验证格式
skills-ref validate ./my-skill

# 安装到 Claude Code
cp -r my-skill ~/.codex/skills/

Step 4：测试

帮我生成本周周报，我完成了...

如果 AI 没有调用技能，可以显式触发：

使用 weekly-report-generator 技能生成本周周报...

九、安全注意事项

⚠️ Skills 可以执行任意代码，这意味着：

1. 只安装受信任来源的技能
   • 优先使用官方 anthropics/skills[26]
   • 检查社区技能的 scripts/ 目录
2. 审查 SKILL.md 和所有脚本
   • 安装前先看代码
   • 留意可疑的网络请求和文件操作
3. 敏感数据处理
   • 不要在 SKILL.md 或 assets 中硬编码密钥
   • 使用环境变量或安全存储
4. 企业部署考虑
   • 目前 Claude.ai 还不支持集中式管理
   • 建议用 Git 仓库管理团队技能
   • 建立技能审批流程

已知安全研究：

Weaponizing Claude Code Skills[27] 这篇文章分析了 Skills 可能的安全风险，值得一读。

十、常见问题 FAQ

Q: Skills 对 Token 消耗影响大吗？A: 非常小。由于渐进式披露机制，每个技能元数据扫描只占 ~100 tokens，激活后加载完整指令 <5000 tokens，关联资源按需加载。

Q: Claude Skills 和 Agent Skills 是一回事吗？A: 是的，同一个东西的不同叫法。

Q: 免费用户能用 Skills 吗？A: 不能。Skills 仅对 Pro、Max、Team、Enterprise 用户开放。

Q: Skills 和 MCP 能一起用吗？A: 完全可以！两者互补。用 MCP 连接数据，用 Skills 教 AI 处理数据。mcp-builder 技能甚至可以帮你创建 MCP 服务器。

Q: 技能不触发怎么办？

• 检查 description 是否清晰描述了使用场景
• 显式提及技能名称
• 确保 YAML frontmatter 格式正确
• 重启 Claude 让新技能生效

Q: 如何更新技能？

• Git 仓库管理的技能：git pull
• 手动安装的：替换文件夹
• API 上传的：创建新版本

十一、我的总结

说实话，Skills 这玩意儿让我眼前一亮。

优点：

• 🎯 学习成本极低：Markdown 谁不会写
• 💡 Token 效率高：渐进式加载设计很聪明
• 🔄 跨平台互通：Claude、Codex、API 都能用
• 🌱 社区生态正在快速发展

局限：

• 依赖代码执行环境（需要 sandbox）
• 安全问题需要注意（可执行任意代码）
• 还在快速迭代中，API 细节可能变化
• 企业级管理功能还不完善

适合谁用：

• 经常重复写同样 prompt 的人 → 赶紧把它变成 Skill
• 想让 AI 遵循特定工作流的团队
• 对 AI Agent 感兴趣的开发者
• 做 AI 产品想对接 Claude/Codex 的人

核心洞察：

如果你发现自己在多个对话中反复输入相同的 prompt，那就是创建 Skill 的信号。

2025 年是 AI Agent 之年，Skills 给了我们一个极其简洁的方式来扩展 Agent 能力。如果你还在观望，不妨从官方的 skill-creator[28] 开始，花 30 分钟创建你的第一个 Skill。

官方：

• 规范文档：https://agentskills.io/specification
• 官方 Skills 仓库：https://github.com/anthropics/skills
• 技术博客：Equipping Agents for the Real World with Agent Skills[29]
• Skills Cookbook：https://github.com/anthropics/claude-cookbooks/tree/main/skills

社区：

• Awesome Claude Skills：https://github.com/travisvn/awesome-claude-skills
• Superpowers 技能库：https://github.com/obra/superpowers
• Simon Willison 解读：https://simonwillison.net/2025/Oct/16/claude-skills/

制作不易，如果这篇文章觉得对你有用，可否点个关注。给我个三连击：点赞、转发和在看。若可以再给我加个🌟，谢谢你看我的文章，我们下篇再见！

参考资料

[1]

agentskills.io: https://agentskills.io

[2]

Settings > Capabilities: https://claude.ai/settings/capabilities

[3]

Agent Skills 规范: https://agentskills.io

[4]

anthropics/skills: https://github.com/anthropics/skills

[5]

docx: https://github.com/anthropics/skills/tree/main/skills/docx

[6]

pdf: https://github.com/anthropics/skills/tree/main/skills/pdf

[7]

pptx: https://github.com/anthropics/skills/tree/main/skills/pptx

[8]

xlsx: https://github.com/anthropics/skills/tree/main/skills/xlsx

[9]

algorithmic-art: https://github.com/anthropics/skills/tree/main/skills/algorithmic-art

[10]

canvas-design: https://github.com/anthropics/skills/tree/main/skills/canvas-design

[11]

slack-gif-creator: https://github.com/anthropics/skills/tree/main/skills/slack-gif-creator

[12]

frontend-design: https://github.com/anthropics/skills/blob/main/skills/frontend-design

[13]

artifacts-builder: https://github.com/anthropics/skills/tree/main/skills/artifacts-builder

[14]

mcp-builder: https://github.com/anthropics/skills/tree/main/skills/mcp-builder

[15]

webapp-testing: https://github.com/anthropics/skills/tree/main/skills/webapp-testing

[16]

brand-guidelines: https://github.com/anthropics/skills/tree/main/skills/brand-guidelines

[17]

internal-comms: https://github.com/anthropics/skills/tree/main/skills/internal-comms

[18]

skill-creator: https://github.com/anthropics/skills/tree/main/skills/skill-creator

[19]

obra/superpowers: https://github.com/obra/superpowers

[20]

awesome-claude-skills: https://github.com/travisvn/awesome-claude-skills

[21]

ios-simulator-skill: https://github.com/conorluddy/ios-simulator-skill

[22]

playwright-skill: https://github.com/lackeyjb/playwright-skill

[23]

claude-d3js-skill: https://github.com/chrisvoncsefalvay/claude-d3js-skill

[24]

claude-scientific-skills: https://github.com/K-Dense-AI/claude-scientific-skills

[25]

Skill_Seekers: https://github.com/yusufkaraaslan/Skill_Seekers

[26]

anthropics/skills: https://github.com/anthropics/skills

[27]

Weaponizing Claude Code Skills: https://medium.com/@yossifqassim/weaponizing-claude-code-skills-from-5-5-to-remote-shell-a14af2d109c9

[28]

skill-creator: https://github.com/anthropics/skills/tree/main/skills/skill-creator

[29]

Equipping Agents for the Real World with Agent Skills: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills