什么是 Claude 技能？

打开任何技能，骨架都一样。最小只有一个文件 SKILL.md，放在以技能命名的文件夹里。更大的技能会围着它长出子文件夹：

• SKILL.md——唯一必需的文件。顶部 YAML frontmatter，下面是 markdown 指令。
• scripts/——可执行辅助脚本（Python、Bash、Node），Agent 直接运行而不是现写一次性的代码。
• references/——需要时才加载的长文档：API 参考、风格指南、检查清单。
• assets/——技能产出依赖的模板、字体或文件。

frontmatter 里两个字段要紧。name 是技能的 slug——小写、连字符、与文件夹同名。description 是整个技能里最重要的一行：它是 Agent 判断这个技能是否适用于你请求的依据。写成何时触发，而不是它是什么——「从 markdown 大纲生成幻灯片」能触发，「一个演示工具」不能。

最小可用技能就这么点：

---
name: changelog-writer
description: Write a release changelog from merged PR titles and commit messages when the user asks for release notes.
---

# Changelog Writer

When asked for a changelog:

1. Run `git log --oneline` between the last tag and HEAD.
2. Group commits into Added / Fixed / Changed / Removed.
3. Write one line per change, user-facing language only.
4. Skip internal refactors unless they change behavior.

渐进式披露是装五十个技能不毁上下文窗口的原因。技能分三层加载，一层比一层贵：

1. 元数据（始终加载）。每个已装技能的 name 和 description——各几十个 token——常驻上下文，让 Agent 知道有什么可用。
2. 指令（触发时加载）。请求命中某个 description 时，Agent 才读 SKILL.md 正文——真正的操作步骤。
3. 附带文件（按需加载）。脚本、references、assets 只在指令点名时拉进来，内容可以分段读取而不必整体灌入。

设计推论：SKILL.md 正文要短，细节推到 references/。正文写成五千字长文的技能每次触发都吃掉这些上下文；同样的内容挪到 references/ 只在 Agent 真需要时才花 token。

四种机制重叠到让人混淆，但它们回答的是不同问题：

• 技能教会 Agent「怎么做」——打包好的专业知识与工作流，按需加载。
• MCP server给 Agent「访问」——通过协议暴露的实时工具和数据（数据库、API、你的日历）。
• Subagent改变「谁来干」——有独立上下文和工具的单独 Agent，承接委派的任务。
• 系统提示词 / CLAUDE.md定「永远生效的规则」——对每条消息都适用的约定，不只是匹配的任务。

实践中它们是组合的：技能可以告诉 Agent 何时调 MCP 工具；项目 CLAUDE.md 定家规，技能处理重复工作。知识是有条件的（「只做幻灯片时」）就写进技能；是无条件的（「永不提交密钥」）就写进系统提示词。CLI 侧的对照实操见 Claude Code 技能。

三条路径，按方便程度排：

1. skills CLI。npx skills add owner/repo 把技能从 GitHub 拷进正确目录——Claude Code、Codex 和大多数 SKILL.md 运行时通用。npx skills 页面有语法和版本固定说明。
2. 手动拷贝。把仓库（或只拷技能文件夹）clone 到 ~/.claude/skills/ 做全项目可用的用户级安装，或拷进项目内 .claude/skills/ 做项目级。
3. 插件市场。Claude Code 和 Codex 都有插件流程（如 /plugin marketplace add owner/repo 然后 /plugin install name@repo），能让技能保持自动更新。

装完常见的两种翻车：技能没被发现——技能在会话启动时注册，重启 Agent 即可——以及目录结构错了，比如多套一层 ~/.claude/skills/repo-name/repo-name/。SKILL.md 必须位于 skills 目录下第一层。

从你反复做的事入手，别从漂亮文案入手。一个好的入门技能：「写我们的发版 changelog」。循环是：

1. 先手动做一遍，记下你会交给一个靠谱同事的步骤。
2. 写 SKILL.md——name、写成触发条件的 description、编号步骤。
3. 用自然请求触发，看 description 是否命中、步骤是否产出想要的结果。
4. 先迭代 description。误触发和不触发几乎都是 description 问题，不是指令问题。

第一节的例子就是一个完整可用技能——拷过去、改名、调步骤。技能写好要分享前，跑一遍 SkillOpt 做可度量的收紧，再看最佳 Claude 技能榜单上的规范写法长什么样。

Anthropic 用官方 Claude 技能仓库推出了这个格式——文档技能（docx、xlsx、pptx、pdf）加 skill-creator 和 mcp-builder——随后迅速成为事实标准：OpenAI 的 Codex 读同一批 SKILL.md，Google 的 Antigravity IDE 采用了它，Vercel 为整个生态出了安装器 CLI。awesome Claude skills这类社区目录则收录生态发布的内容。

标准化的实际意义：技能不再绑死在某家厂商的 Agent 上。写一次 SKILL.md，跟着你跨 Claude Code、claude.ai、Codex 以及下一个采用该格式的运行时——这就是为什么技能成了 Agent 能力的默认打包单位，就像扩展之于编辑器功能。

每次安装都逃不掉一个决定：作用域。~/.claude/skills/ 下的是用户级——每个项目、每个会话可用。仓库 .claude/skills/ 下的是项目级——只在这个代码库内激活。口诀：个人效率技能（演示稿、截图、笔记流）放用户级；编码团队工作方式的（changelog 格式、评审清单、发版流程）放项目级，可以随仓库提交共享。

提交进仓库的项目技能是被低估的模式——它把口口相传的知识变成有版本、可评审的配置。新队友的 Agent 第一天就继承团队约定，因为技能随 clone 到位。而且项目技能只是仓库里的文件夹，走和其他改动一样的 PR 评审——没人能不经 diff 评审就改动共享 Agent 的行为。