Agent Skills 入门
原文发布于知乎：Agent Skills 入门
一、Skill 到底是什么？
Skill（Agent Skills）是 Anthropic 推出的一种“能力扩展”机制：本质上是一个文件夹，里面放着一份 SKILL.md 说明文件，外加可选的脚本、模板、参考资料等。Claude 在收到用户请求后，会根据 SKILL.md 顶部的 description 自动判断“这个 skill 跟当前任务相关吗”，相关就把里面的指令加载进来按部就班执行。
可以这样理解三层关系：
- Prompt：每次手动告诉 Claude 怎么做。
- MCP：给 Claude 接上外部工具（API、数据库、Notion 等）。
- Skill：把“如何把一件事做好”的工作流和最佳实践沉淀下来，让 Claude 每次自动复用。
官方文档里有一句精炼的概括：Skill 是一种模块化能力（modular capabilities），每个 skill 打包了说明、元数据、可选的脚本和模板，Claude 在判断相关时会自动调用。
Skill 的优点
- 跨产品通用：同一个 skill 在 Claude.ai、Claude Code、Claude API 三个产品里都能用，写一次到处跑。
- 渐进式披露（Progressive Disclosure）：所有 skill 的
name和简短description始终在 Claude 上下文里，但完整指令只有在被判定“相关”时才会加载，避免上下文被撑爆。 - 官方预置 + 自定义并存：Anthropic 已经开源了一批官方 skill（docx、pptx、xlsx、pdf、frontend-design、skill-creator 等），同时支持你写自己的。
- 开放标准：Skill 格式是开放的（见 agentskills.io），目标是让同一份 skill 能跨多个 AI 平台使用。
二、SKILL.md 的最小结构
一个 skill 在最简形态下，只需要一个文件夹和一个 SKILL.md，其中必须包含 YAML frontmatter（name 和 description）：
---
name: my-skill-name
description: 用一句话说清楚这个 skill 是做什么的，以及什么时候应该被触发
---
# My Skill 标题
这里写 Claude 在使用本 skill 时需要遵循的指令、步骤、注意事项。
可以包含代码示例、checklist、避坑指南等。文件夹结构通常长这样：
my-skill/
├── SKILL.md # 必需：指令 + frontmatter
├── references/ # 可选：参考文档（如 API 详细签名）
├── scripts/ # 可选：辅助脚本
├── assets/ # 可选：模板、图片等资源
└── evals/ # 推荐：评测用例关于 description 的提醒：这是 Claude 决定“要不要用这个 skill”的唯一线索，所以要明确写出触发条件和使用边界（什么时候该用、什么时候不该用）。官方建议把最关键的使用场景放在 description 开头。
三、一个简单的实战例子
下面是一个虚构但完整的小 skill，叫 git-commit-helper，作用是规范团队的 Git commit message。
文件结构
git-commit-helper/
└── SKILL.mdSKILL.md 内容
---
name: git-commit-helper
description: 当用户要写 Git commit message、生成提交说明、或在做 git commit 时使用。强制使用 Conventional Commits 规范（feat/fix/docs/refactor/test/chore），中文描述，附带影响范围。不要用于 PR 描述或 changelog 生成。
---
# Git Commit Message 规范助手
## 输出格式
<type>(<scope>): <简短中文描述，不超过 50 字>
<可选的详细说明，每行不超过 72 字>
<可选的 footer，如 BREAKING CHANGE 或 Closes #123>
## type 取值
| type | 含义 |
| -------- | ---------------------------- |
| feat | 新功能 |
| fix | bug 修复 |
| docs | 仅文档变更 |
| refactor | 重构（非 feat 也非 fix） |
| perf | 性能优化 |
| test | 测试相关 |
| chore | 构建过程或辅助工具变动 |
## 工作流
1. 先用 `git diff --staged` 查看暂存区改动
2. 根据改动判断 type 和 scope
3. 用一句中文概括“做了什么”，不要写“为什么”
4. 改动量大时再补充 body 说明动机
## Gotchas
- 不要用“update”、“修改”这种空话作为描述
- scope 用模块名（如 `auth`、`scheduler`），不要用文件名
- 一次提交只做一件事；如果想写两个 type，说明应该拆成两个 commit使用方式
在 Claude Code 里配置好这个 skill 后，你只要说：
“帮我看下暂存区的改动，写个 commit message”
Claude 会自动识别 git-commit-helper 相关，然后按照里面的 workflow 跑一遍 git diff --staged、判断 type、给出符合规范的 commit。
四、官方预置 Skill 速查
Anthropic 在 Claude.ai 和 API 上已经预置了一批 skill，可直接使用：
| Skill | 作用 |
|---|---|
| docx | 创建、读取、编辑 Word 文档 |
| pptx | 创建和操作 PowerPoint 演示文稿 |
| xlsx | 创建和处理 Excel 表格 |
| 生成、读取、合并、填表等 PDF 操作 | |
| claude-api | 提供 Claude API/SDK 的最新参考资料（Claude Code 自带） |
API 调用时通过 container.skills 字段挂载，例如：
response = client.beta.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={
"skills": [{"type": "anthropic", "skill_id": "xlsx", "version": "latest"}]
},
messages=[{"role": "user", "content": "创建一个简单的预算 Excel"}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)五、写好 Skill 的几条经验
- Skill 是文件夹，不是 Markdown 文件。把整个文件系统当作 context engineering 工具来用，脚本、参考文档、示例都可以放进去，Claude 会按需加载。
- 聚焦默认思维之外的内容。Claude 本身已经懂很多通用做法，skill 应该写那些“不告诉它就会做错”的东西。
- Gotchas 章节是最有价值的部分。把 Claude 实际踩过的坑列出来，这比抽象的指南管用得多。
- 迭代驱动。Skill 是活文档，根据实际使用中暴露的问题持续更新。
六、安全提醒
官方文档明确强调：只使用可信来源的 skill（自己写的、或来自 Anthropic 官方仓库）。Skill 能让 Claude 执行代码和调用工具，恶意 skill 可能导致数据泄露或未授权访问。如果一定要用第三方 skill，先逐项审计 SKILL.md、所有脚本和资源文件。
参考资料
- Agent Skills 总览：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- API 中使用 Skills 指南：https://platform.claude.com/docs/en/build-with-claude/skills-guide
- Claude Code 中的 Skills：https://code.claude.com/docs/en/skills
- Claude API Skill 详情：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill
- 官方开源 Skills 仓库（含 docx/pptx/xlsx/pdf 源码）：https://github.com/anthropics/skills
- Skills 完整指南 PDF：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
- 开放标准网站：https://agentskills.io