Skills制作教程
一、什么是 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 长什么样？
代码语言：javascript
AI代码解释
---
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 的三大问题：
|
问题 |
具体表现 |
|---|---|
|
Token 开销巨大 |
GitHub 官方 MCP 光加载就吃掉几万 tokens，加几个 MCP 后 context window 直接爆满 |
|
协议复杂 |
hosts、clients、servers、resources、prompts、tools、sampling、roots、elicitation……还有三种传输方式（stdio、HTTP、SSE） |
|
开发门槛高 |
需要写服务端代码，实现各种接口 |
而 Skills 呢？
Skills 渐进式披露架构
Skills 渐进式披露架构
Skills 采用渐进式披露（Progressive Disclosure）机制，Token 效率极高：
|
阶段 |
Token 消耗 |
说明 |
|---|---|---|
|
元数据加载 |
~100 tokens |
AI 启动时只读取 name 和 description，判断技能是否相关 |
|
技能激活 |
< 5000 tokens |
用户任务匹配时，才加载完整的 SKILL.md 指令 |
|
资源按需加载 |
按需 |
脚本、参考文档只在需要时才读取 |
这意味着：你可以装 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 目录结构如下：
代码语言：javascript
AI代码解释
my-skill/
├── SKILL.md # 必须：指令 + 元数据
├── scripts/ # 可选：可执行脚本
│ └── helper.py
├── references/ # 可选：参考文档
│ └── REFERENCE.md
└── assets/ # 可选：模板、资源
└── template.json
3.2 SKILL.md 文件格式
SKILL.md 是唯一必须的文件，采用 YAML Frontmatter + Markdown Body 的格式：
代码语言：javascript
AI代码解释
---
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 |
✅ |
1-64 字符，小写字母 + 数字 + 连字符，不能以连字符开头/结尾，不能连续连字符 |
技能唯一标识，必须与目录名一致 |
|
description |
✅ |
1-1024 字符 |
描述技能功能和触发场景，这个字段决定了 AI 什么时候会选择这个技能 |
|
license |
❌ |
- |
许可证名称或引用 |
|
compatibility |
❌ |
1-500 字符 |
环境要求，如需要的软件包、网络访问等 |
|
metadata |
❌ |
任意键值对 |
扩展元数据，如作者、版本号 |
|
allowed-tools |
❌ |
空格分隔的工具列表 |
预批准的工具，实验性功能 |
name 字段的正确示例：
代码语言：javascript
AI代码解释
name: pdf-processing # ✅ 正确
name: data-analysis # ✅ 正确
name: code-review # ✅ 正确
错误示例：
代码语言：javascript
AI代码解释
name: PDF-Processing # ❌ 不能大写
name: -pdf # ❌ 不能以连字符开头
name: pdf--processing # ❌ 不能连续连字符
description 字段的最佳实践：
好的描述应该同时说明做什么和什么时候用：
代码语言：javascript
AI代码解释
# ✅ 好的描述
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 编写最佳实践
- 保持
SKILL.md在 500 行以内：详细的参考资料移到references/ - 文件引用用相对路径：从 skill 根目录算起，如
references/REFERENCE.md - 避免深层嵌套引用：保持文件引用一层深度
- 使用 skills-ref 工具验证：
代码语言：javascript
AI代码解释
# 安装验证工具
npm install -g @agentskills/skills-ref
# 验证技能包
skills-ref validate ./my-skill
四、Skills 在各平台的使用方式
目前 Skills 主要在以下平台支持：
4.1 Claude.ai 网页版
- 进入 Settings > Capabilities[2]
- 开启 Skills 开关
- 可以启用官方 Skills 或上传自定义 Skills
用户可用性：
- Pro、Max、Team、Enterprise 用户可用
- Free 用户不可用
4.2 Claude Code CLI
Claude Code 从以下位置加载 Skills（按优先级从高到低）：
|
作用域 |
路径 |
|---|---|
|
当前目录 |
$CWD/.codex/skills |
|
父目录 |
$CWD/../.codex/skills |
|
仓库根目录 |
$REPO_ROOT/.codex/skills |
|
用户目录 |
~/.codex/skills |
|
系统目录 |
/etc/codex/skills |
安装官方技能：
代码语言：javascript
AI代码解释
# 注册官方技能市场
/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
使用技能：
有两种触发方式：
- 显式调用：使用
/skills命令或$前缀提及技能名 - 隐式调用：AI 根据任务自动选择合适的技能
代码语言：javascript
AI代码解释
# 显式调用
$pdf "Extract all tables from report.pdf"
# 隐式调用（AI 自动选择）
"Help me extract the form fields from invoice.pdf"
4.3 Claude API
通过 /v1/skills 端点使用：
代码语言：javascript
AI代码解释
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]，使用方式类似：
代码语言：javascript
AI代码解释
# 使用内置的技能创建器
$skill-creator
# 使用安装器
$skill-installer create-plan
# 从其他仓库安装
$skill-installer https://github.com/xxx/xxx
五、官方 Skills 一览
Anthropic 官方在 anthropics/skills[4] 仓库提供了一批开箱即用的技能：
5.1 文档处理技能
这些技能支撑了 Claude 的文档创建功能：
|
技能 |
功能 |
|---|---|
|
docx[5] |
Word 文档创建、编辑，支持修订记录、批注、格式保留 |
|
pdf[6] |
PDF 全套操作：文本提取、表格识别、表单填充、文档合并 |
|
pptx[7] |
PowerPoint 演示文稿创建编辑，支持布局模板、图表、自动生成幻灯片 |
|
xlsx[8] |
Excel 电子表格操作，支持公式、格式化、数据分析和可视化 |
⚠️ 注意：文档技能是 source-available（可查看源码）但非开源（Apache 2.0），供开发者参考。
5.2 创意设计技能
|
技能 |
功能 |
|---|---|
|
algorithmic-art[9] |
使用 p5.js 创建生成艺术，支持随机种子、流场、粒子系统 |
|
canvas-design[10] |
设计精美的视觉艺术，输出 .png 和 .pdf 格式 |
|
slack-gif-creator[11] |
创建符合 Slack 大小限制（≤2MB）的动画 GIF |
5.3 开发技术技能
|
技能 |
功能 |
|---|---|
|
frontend-design[12] |
避免"AI 审美"，做出大胆设计决策，适合 React + Tailwind |
|
artifacts-builder[13] |
使用 React、Tailwind、shadcn/ui 构建复杂的 claude.ai HTML artifacts |
|
mcp-builder[14] |
教你如何创建高质量的 MCP 服务器 |
|
webapp-testing[15] |
使用 Playwright 测试本地 Web 应用 |
5.4 企业沟通技能
|
技能 |
功能 |
|---|---|
|
brand-guidelines[16] |
应用 Anthropic 官方品牌色彩和排版 |
|
internal-comms[17] |
撰写状态报告、新闻简报、FAQ 等内部沟通材料 |
5.5 技能创建工具
|
技能 |
功能 |
|---|---|
|
skill-creator[18] |
通过 Q&A 交互式引导创建新技能 |
六、社区生态资源
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 社区单独技能
|
技能 |
功能 |
|---|---|
|
ios-simulator-skill[21] |
iOS 模拟器操作 |
|
playwright-skill[22] |
Playwright 浏览器自动化 |
|
claude-d3js-skill[23] |
D3.js 数据可视化 |
|
claude-scientific-skills[24] |
科研论文处理 |
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 分身干活（独立运行的子任务）
详细对比表：
|
维度 |
Skills |
MCP |
Subagents |
|---|---|---|---|
|
核心功能 |
封装可重复的工作流程和专业知识 |
连接外部数据源和 API |
独立执行子任务，有自己的 context |
|
Token 效率 |
极高（~100 tokens 元数据） |
低（可能几万 tokens） |
中等 |
|
技术门槛 |
低（Markdown + YAML） |
高（需写服务端代码） |
中等 |
|
可移植性 |
跨平台（Claude、Codex 都能用） |
平台相关 |
平台相关 |
|
典型场景 |
代码审查流程、文档格式规范、数据分析方法 |
连接 Google Drive、Slack、数据库 |
代码审查（只读权限）、并行研究任务 |
组合使用示例：竞品分析 Agent
代码语言：javascript
AI代码解释
1. 用 MCP 连接：Google Drive（内部资料）、GitHub（竞品仓库）、Web Search（实时信息）
2. 用 Skill 教会：竞品分析框架、内部 Drive 目录结构、报告格式规范
3. 用 Subagent 分工：
- market-researcher：收集市场数据
- technical-analyst：分析技术架构
- 两者并行工作，最后合并结果
八、手把手创建你的第一个 Skill
方法一：使用 skill-creator（推荐）
最简单的方式是让 Claude 帮你创建：
代码语言：javascript
AI代码解释
请使用 skill-creator 帮我创建一个技能，用于 [描述你的场景]
Claude 会交互式引导你：
- 这个技能解决什么问题？
- 需要哪些输入参数？
- 输出格式是什么？
- 有什么特殊规则？
最后自动生成完整的 Skill 目录结构。
方法二：手动创建
Step 1：创建目录结构
代码语言：javascript
AI代码解释
mkdir -p my-skill/scripts
cd my-skill
Step 2：编写 SKILL.md
代码语言：javascript
AI代码解释
---
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: 按上述格式的完整周报
代码语言：javascript
AI代码解释
**Step 3：验证并安装**
```bash
# 验证格式
skills-ref validate ./my-skill
# 安装到 Claude Code
cp -r my-skill ~/.codex/skills/
Step 4：测试
代码语言：javascript
AI代码解释
帮我生成本周周报，我完成了...
如果 AI 没有调用技能，可以显式触发：
代码语言：javascript
AI代码解释
使用 weekly-report-generator 技能生成本周周报...
九、安全注意事项
⚠️ Skills 可以执行任意代码，这意味着：
- 只安装受信任来源的技能
- 优先使用官方 anthropics/skills[26]
- 检查社区技能的
scripts/目录
- 审查 SKILL.md 和所有脚本
- 安装前先看代码
- 留意可疑的网络请求和文件操作
- 敏感数据处理
- 不要在 SKILL.md 或 assets 中硬编码密钥
- 使用环境变量或安全存储
- 企业部署考虑
- 目前 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/
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
0
0- 0
已为社区贡献4条内容
所有评论(0)