Agent Skills 已经成了 AI 编程工具的「npm 生态」——写一次，到处用。Claude Code、Cursor、Codex CLI、Copilot 全部支持。本文教你从零写一个 Skill，让 AI 自动按你的规范干活。
为什么你需要 Skills？
如果你用 Claude Code 超过一周，一定经历过这些场景：
- 每次开新会话，都要重新解释团队代码规范、命名约定、提交信息格式
- 同样的错误处理模式、同样的 API 调用模板，每次都要口述一遍
- 想让 Claude 按特定风格写代码，但每次描述的结果都不太一样
Skills 解决的就是「重复解释」的问题。 把一整套工作流程编码成一个文件夹，Claude 在需要时自动加载——你不用再当复读机。
更关键的是，Agent Skills 已经是一个跨平台开放标准。你在 Claude Code 里写的 Skill，可以直接拿到 Cursor、GitHub Copilot、Gemini CLI 里用。目前整个生态已经有 490,000+ 个 Skill，被社区称为「AI Agent 的 npm」。
一、Skill 的目录结构
一个 Skill 本质上是一个文件夹，最小结构只需要一个 SKILL.md 文件：
my-code-review-skill/
├── SKILL.md # 必需：指令 + 元数据
├── scripts/ # 可选：可执行脚本
│ └── lint-check.sh
├── references/ # 可选：参考文档
│ └── style-guide.md
└── assets/ # 可选：模板、图标
└── template.py
放在 Claude Code 项目的 .claude/skills/ 目录下即可生效。
二、SKILL.md 怎么写：两层结构
SKILL.md 由两部分组成：YAML 元数据 + Markdown 指令正文。
最简模板
---
name: code-review
description: >
Review code changes for bugs, security issues, and style violations.
Use this skill whenever the user asks for a code review, PR review,
or says "review this", "check my code", "audit".
---
# Code Review Skill
## Steps
1. Read all changed files in the diff
2. Check for: null pointer, unhandled promises, SQL injection, XSS
3. Check naming conventions: camelCase for JS, snake_case for Python
4. Output a structured review with Severity (Critical/Major/Minor) and fix suggestion for each issue
## Output Format
**Severity:** Critical
**File:** path/to/file.ts:42
**Issue:** Unhandled promise rejection
**Fix:** Add `.catch()` or wrap in try/catch
核心原则
1. description 是触发器——写得好不好决定 Skill 会不会被调用
Claude 读取所有 Skill 的 name + description 来判断哪个 Skill 匹配当前任务。description 要足够具体，甚至有点"推销感"：
# ❌ 太模糊，永远不会触发
description: Format code.
# ✅ 具体，包含触发词和使用场景
description: >
Apply team code standards to all TypeScript and Python files.
Use when user mentions: code review, lint, formatting, style guide,
PR standards, team conventions, clean code. Also use before any
git commit to ensure compliance.
2. 解释"为什么"，而不是只下命令
# ❌ 只给规则
ALWAYS use 4-space indentation.
# ✅ 解释原因
Use 4-space indentation — our CI pipeline enforces this via ESLint,
and mixing 2-space/4-space causes merge conflicts on large PRs.
3. 用示例教 Claude 什么是对的
## Commit Message Format
**Good:**
- feat(auth): add JWT token refresh endpoint
- fix(api): handle null response from payment gateway
**Bad:**
- fixed stuff
- updated code
- WIP
三、渐进式加载机制——为什么 Skills 不会撑爆上下文
Skills 采用三级加载，保证不浪费 token：
| 层级 | 内容 | 何时加载 | 大小建议 |
|---|---|---|---|
| 第1层 | name + description | 每次对话开始 | ~100词 |
| 第2层 | SKILL.md 正文 | 任务匹配时 | <500行 |
| 第3层 | references/ scripts/ assets/ | 正文引用时才加载 | 无限制 |
实战技巧：如果你的 Skill 内容越来越长，把详细的参考资料移到 references/ 目录，在 SKILL.md 里用一句话指向它：
For the complete API error code reference, see references/error-codes.md.
四、实战：写一个「公众号排版」Skill
咱们 AI 创业内参的读者里，很多人用 Claude Code 做内容。下面是一个真实可用的 Skill，让 Claude Code 自动按公众号规范排版：
---
name: wechat-article-formatter
description: >
Format articles for WeChat Official Account publishing.
Use when user mentions: 公众号, 排版, 发布, WeChat article,
draft, 草稿, 推文. Apply strict formatting rules: inline
styles only, no h1 in body, illustration captions required.
---
# WeChat Article Formatter
## Core Rules
1. **NO h1 in body** — WeChat API adds the title automatically
2. **All styles must be inline** — no external CSS, no <style> tags
3. **Every image needs a caption** — centered, gray, 13px font
4. **Code blocks need background** — #f5f5f5, 4px padding, monospace
5. **Paragraph spacing ≥ 16px** — use margin-bottom style
## HTML Template
<div style="padding:24px 28px;font-family:'PingFang SC','Microsoft YaHei',sans-serif">
<!-- content goes here -->
</div>
## Image Caption Format
<p style="text-align:center;color:#888;font-size:13px;margin-top:8px">
▲ 图注文字
</p>
## Checklist Before Output
- [ ] Root <div> wrapper present
- [ ] No h1 tags in body
- [ ] All images have captions
- [ ] Inline styles only
五、三个必装的开源 Skill 推荐
1. Handoff —— 跨会话传递上下文
https://github.com/anthropics/skills/tree/main/handoff
把当前会话压缩成一份 Markdown 文档，新会话直接加载。告别「刚才我们说到哪了」。
2. Grill Me —— AI 面试官，逼你把需求想清楚
https://github.com/anthropics/skills/tree/main/grill-me
在你写任何代码之前，Claude 会像面试官一样追问你的需求、边界条件、验收标准。适合需求模糊时使用。
3. Superpowers —— 多步骤开发工作流
https://github.com/anthropics/skills/tree/main/superpowers
结构化你的开发流程：先出计划 → 分子任务 → TDD → 逐个验收。把 Claude Code 从「一次性的代码生成器」升级为「有流程的工程助手」。
六、踩坑笔记
坑1：description 太保守
Claude 倾向于少触发 Skill 而非多触发。如果你的 Skill 总是加载不出来，把 description 写得更"推销"一些，多加触发词。
坑2：正文太长
超过 500 行的 SKILL.md 正文会影响加载速度。把参考资料拆到 references/ 里。
坑3：把 Skill 当成「一次性 prompt」
Skill 的价值在于复用。写 Skill 时问自己：这个工作流我未来还会用 10 次以上吗？如果答案是不会，那就别写成 Skill。
行动建议
今天就可以做的事：
- 打开你的 Claude Code 项目，在
.claude/skills/下新建一个文件夹 - 从最烦人的重复工作流开始——比如格式化 commit message、代码审查 checklist、部署前检查清单
- 写一个 SKILL.md，重点打磨 description 字段
- 测试：新开一个会话，说一句相关的话，看 Skill 是否自动触发
一人公司的效率密码不在工具多，在于把「每次都要说一遍」的东西，变成「说一次，自动执行」。