如何编写 Claude Skills：5 种写法风格与社区踩坑经验

摘要

Claude Agent Skills 本质上是 「目录 + 一份带 YAML frontmatter 的 SKILL.md + 可选脚本/资源」，依赖 progressive disclosure 三层加载：

Level 1 metadata（name + description）：常驻 system prompt，每个 Skill 约 100 tokens；
Level 2 SKILL.md 主体：被触发后才加载，建议 < 5k tokens、< 500 行；
Level 3 references / scripts：按需读取，理论上无限。

官方硬性约束：

name ≤ 64 字符，仅小写字母+数字+连字符，不能包含 “anthropic” / “claude”；
description ≤ 1024 字符，第三人称，必须同时回答「做什么」+「何时用」。

Skills 不是 MCP（MCP 是连工具/数据），不是 sub-agent（sub-agent 是隔离上下文的子任务），更接近「按需加载的过程性知识」。

社区最痛的核心坑只有一个：description 写不好 → 永远不触发 / 永远误触发。其他高频坑包括 SKILL.md 太长、嵌套引用过深、Windows 反斜杠路径、跨 surface（API / claude.ai / Claude Code）不互通、第三方 Skill 供应链风险。

可归纳出 5 种主流写法风格：纯 prompt 型、脚本驱动型、模板/资源型、工作流编排型、元 Skill 型。

研究问题

Claude Skills 的官方规范到底是什么？哪些字段必填、哪些是社区约定？
主流仓库（anthropics/skills、obra/superpowers、wshobson/agents 等）是怎么组织 SKILL.md 的？
Skills、MCP、Sub-agent、Projects 各自该用在哪里？
社区在写 Skills 时反复踩什么坑？
能否归纳出几种可复制的写法风格？每种各自适合什么场景？

发现

A. 规范与官方一手定义

SKILL.md 必填仅 2 个字段：name 和 description。name ≤ 64 字符、仅小写字母+数字+连字符、禁用 “anthropic”/“claude” 这种保留词；description ≤ 1024 字符、不能含 XML 标签、必须非空。这是写错最常见的地方（Anthropic 官方文档）。
三层加载的精确 token 预算：Level 1 metadata 约 100 tokens / Skill；Level 2 SKILL.md body 「Under 5k tokens」；Level 3 文件按需读取，「Effectively unlimited」（官方 overview 表格）。
官方推荐 SKILL.md 主体 ≤ 500 行，超过就拆到独立文件，这是 best-practices 页给出的明确数字（Best practices）。
allowed-tools 是 Claude Code 特有约定，不是 SKILL.md 官方核心 spec：在 Anthropic 官方文档的 frontmatter 字段说明里**只列了 name 与 description**；allowed-tools 在 Claude Code 生态广泛使用，用于限定该 Skill 可以调用哪些工具（如 Read, Grep, Glob 或 BigQuery:bigquery_schema 这类带 server 前缀的 MCP 工具名），写成逗号分隔字符串或 YAML 数组都行（来自社区/Claude Code 生态约定，GitHub workshop、官方 best-practices 关于 MCP 工具命名）。
官方强制要求第三人称写 description：「Processes Excel files and generates reports」是好；「I can help you process Excel files」是差。原因是 description 会被注入 system prompt，第一/第二人称会污染上下文（Best practices）。
description 必须同时讲「做什么 + 何时使用」，官方给的范本是：

Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

后半句 “Use when …” 是触发关键（Best practices）。
跨 surface 不互通是巨大隐性坑：claude.ai 上传的 zip Skill 不会同步到 API；API 的 Skill 不能用在 claude.ai；Claude Code 是基于本地文件系统（~/.claude/skills/ 或 .claude/skills/），三个 surface 必须分别管理。claude.ai 还不支持 admin 集中分发（官方 overview – Limitations）。
运行时差异：Claude API 中的 Skill 没有网络访问、不能运行时安装包；Claude Code 的 Skill 拥有用户机器的全部权限；claude.ai 的网络访问取决于 user/admin 设置。脚本依赖必须提前规划（官方 overview – Runtime environment）。

B. 官方仓库与第三方仓库结构

anthropics/skills 顶层结构：skills/（含 docx、pdf、pptx、xlsx 等 source-available 文档处理 Skill）、spec/（Agent Skills 规范）、template/（新建 Skill 的脚手架）、.claude-plugin/（plugin 配置）。文档型 Skill 用 source-available 许可，其他用 Apache 2.0（anthropics/skills）。
obra/superpowers 是社区最重的元 Skill 集合：brainstorming、writing-plans、executing-plans、test-driven-development、systematic-debugging、subagent-driven-development、writing-skills、using-superpowers 等 20+ 个，全部以「mandatory workflows」语义书写——通过强语气 description 让 Claude 必须先走某个流程，而不是自由发挥（obra/superpowers）。
wshobson/agents 是规模最大的「市场化」集合：184 agents + 150 skills + 78 plugins，按职业域切分（如 python-development plugin 只加载相关的 3 个 agents + 5 个 skills），是「插件化 Skill 包」的代表案例（wshobson/agents）。
karanb192/awesome-claude-skills 是社区认可度最高的精选清单，并明确总结了三件事的边界：Skills = workflow-specific、MCP = tool integration、system prompt = general behavior（karanb192/awesome-claude-skills）。

C. Skills vs MCP vs Sub-agent 的边界（社区共识）

官方版边界：Skills 是「procedural knowledge / how」，MCP 是「access」，Projects 是「background knowledge」，Sub-agents 是「task delegation」。Skills 跨会话持久但 token 成本低（progressive disclosure）；Projects 会一直占 token；MCP 在连接期间持续在线（Anthropic 官博 “Skills explained”）。
Simon Willison 的判断：Skills 比 MCP 更重要——MCP server（如 GitHub 官方 MCP）经常一加载就吃几万 tokens；而 Skill 只用几十 tokens 的 metadata 就能让 Claude 「知道有这个能力存在」，按需触发后才载入正文，token 经济性碾压（simonwillison.net）。
HN 讨论的反方观点：相当一部分开发者认为 Skills 「就是 prompt engineering 的设计模式，不需要硬 spec」；也有人指出 LLM 对 description 的选择是概率性的，缺乏人类判断力，所以 Skills 选择不可靠（Hacker News thread #45607117）。

D. 真实踩坑（来自 Reddit / HN / 独立博客）

Scott Spence 的实测：即使写了 hook 强制注入「INSTRUCTION: Use Skill(research)」，触发率也只有 4–5/10，完全自动触发是幻想。他建议关键场景显式调用 Skill(skill-name)，不要赌自动路由（Scott Spence 博客）。
关键词碰撞坑：description 写 “research” → 用户随口说「research why this test fails」也会误触发；描述里要加 negative constraints / 排除条款（”Do NOT activate when…”）（Scott Spence 博客、HN 讨论）。
“ALWAYS invoke when…” 句式有效：社区广泛报告把描述改成命令式 “ALWAYS invoke this skill when the user asks about X. Do not Y directly — use this skill first.” 可显著提升触发率，有作者报告从 ~37% 提升到接近 100%（Skill 调试指南汇总）。
嵌套引用过深 = Claude 只读一半：当 SKILL.md → advanced.md → details.md 这样链式跳转，Claude 经常用 head -100 预览而不会完整读取被嵌套的文件。所有 reference 文件必须从 SKILL.md 一级直链（官方 best-practices 明确强调）。
Windows 反斜杠路径会让 Skill 在 Unix 上炸掉，官方 anti-pattern 列表里专门列了这一条，永远用 scripts/helper.py 而不是 scripts\helper.py。
多 Skill 名字/描述重叠 → token 预算溢出：所有 Skill 的 metadata 一起塞进 system prompt，社区报告 ~15k tokens 的隐性上限。重叠的描述会互相挤压，导致重要 Skill 被忽略（CSDN/HN 综合讨论）。
Skill 安全风险被官方点名：Skills 可执行代码，等同于安装软件。第三方 Skill 可能在 calculate.py 里塞反向 shell；用 allowed-tools 限制权限是最低安全实践；外部 URL 抓取的 Skill 风险更高（官方 overview – Security、Hacker News thread）。
企业级管理坑：claude.ai 不支持 admin 集中分发 → 团队各自上传副本 → 版本漂移；推荐做法是把 Skills 作为「Skillplane」（受治理的 repo-first 库）+ Plugin 打包分发，避免命名冲突用 namespaced slash 命令（如 /team-plugin:deploy）（Michelle Pellon 企业 Playbook）。
Sub-agent 与 Skill 的取舍：sub-agent 适合「需要隔离上下文 + 限制工具权限 + 并行执行」的复杂任务（如 read-only 安全审计）；Skill 适合「在主上下文里反复使用的步骤性知识」。混合模式很常见——Skill 提供步骤蓝图，里面让 Claude 派 sub-agent 做隔离子步（karanb192/awesome-claude-skills、2cups.com）。

何时该写 Skill（决策清单）

写 Skill 之前先问自己：这件事我会重复做吗？做错的代价大吗？做法每次差不多吗？三个都是 yes，再写 Skill。否则有更轻的工具。

✅ 推荐写 Skill 的场景

重复出现的多步流程——例如发版、code review、incident 响应、写 commit message、写 PR 描述。一次性的事不值得写 Skill。
有「正确做法」的领域知识——团队的代码规范、品牌 tone、SQL 数据集口径、合规检查项。把人的经验变成 Claude 默认知道的东西。
LLM 不擅长但脚本擅长的活——PDF 表单填写、OOXML 编辑、精确数值计算、文件批处理、迁移。把这类活封装成「让 Claude 调脚本」的 Skill，比让 Claude 直接写代码做更稳定。
跨项目复用的工作流——你在 5 个项目都要做同样的事（如 changelog 生成、发布前检查），写一次放 ~/.claude/skills/ 就够了。
需要按需加载的大体量参考资料——BigQuery 多 schema、API 多语言文档、品牌素材库。Skill 的 progressive disclosure 让总量再大也不爆 context。
想让 Claude 默认走某个流程而不是自由发挥——例如「修 bug 之前必须先复现」「写代码之前必须 TDD」「研究之前必须拆 2-4 个角度」。obra/superpowers 整个仓库就是这种用法。
要给团队/客户分发可复用能力——比直接发一段 prompt 给同事更可控、可版本化、可审计。
prompt 长到要做内部目录索引——如果你已经在 system prompt 里写了 “When user asks X, do Y; when X’, do Y’”，那其实是一组 Skill 在挤一个 prompt，拆开就对了。

⚠️ 不要写 Skill 的场景

一次性任务——直接 prompt 完事，写 Skill 是负担。
已经有合适的 MCP server——访问外部数据/工具是 MCP 的活，不是 Skill 的活（GitHub、Slack、数据库连接器都该是 MCP）。
要改全局行为——影响 Claude「整体性格 / 永远怎么说话」的事属于 system prompt / project instructions，不是 Skill。
强依赖隔离的复杂子任务——需要独立上下文 + 限制工具的活（如 read-only 安全审计、并行子任务），用 sub-agent 更合适。
凭证 / 密钥相关——任何要塞 API key 的需求都不该走 Skill；用环境变量 + MCP / hooks。
触发条件描述不清楚——如果你自己都说不清「什么时候该用它」，Claude 也不会知道，Skill 永远不会被触发。先想清楚 description，再决定要不要写。
逻辑还在频繁变——流程没稳定就写 Skill，每次改都要重新调 description 触发率，不如先用 prompt 迭代几轮。

决策树（30 秒判断）

要做的事 …
├─ 一次性 / 探索性？           → 直接 prompt
├─ 接外部系统取数据/调工具？   → MCP server
├─ 改 Claude 整体行为？        → system prompt / project instructions
├─ 需要隔离上下文 + 限工具？   → sub-agent
└─ 重复的流程 / 步骤 / 知识？  → ✅ 写 Skill
       ├─ 只是规则文本？           → 风格 1：纯 prompt 型
       ├─ 要跑代码确保正确？       → 风格 2：脚本驱动型
       ├─ 大体量参考资料？         → 风格 3：模板/资源型
       ├─ 多步流程 + 验证回路？    → 风格 4：工作流编排型
       └─ 给别人造 Skill 用？      → 风格 5：元 Skill 型

一个判断锚点：这件事值不值得写 description？

写 Skill 的成本主要不在 SKILL.md 正文，而在 「想出一条会被正确触发的 description」——通常要 A/B 试 3-5 轮才稳。如果你都不愿意花 10 分钟想 description，那这件事不值得写 Skill；直接 prompt 就好。这条经验来自 Scott Spence、Hacker News、企业 Playbook 的反复印证：Skill 的瓶颈是触发，不是内容。

对比与判断：5 种 SKILL.md 写法风格

风格 1：纯 prompt 型（pure-prompt skill）

典型场景：编码风格规范、写作规范、code review checklist、品牌文案 tone。
特征：只有 SKILL.md，没有 scripts/ 或 references/。正文是清单/规则/模板。
优点：写得快、无依赖、跨 surface 都能跑（API 也行）。
缺点：不可执行；规则一多就爆 token；无法做客观验证（feedback loop）。
真实例子：obra/superpowers/skills/brainstorming 之类的协作 skill。

---
name: writing-commit-messages
description: Generates conventional commit messages by analyzing staged diffs. Use when the user asks for help writing commit messages, reviewing staged changes, or mentions "commit", "git diff", or "conventional commits". Do NOT activate for general code review or branching questions.
---

# Writing Commit Messages

## When to use
Triggered after `git add`, before `git commit`.

## Format
`type(scope): subject` + body, e.g. `feat(auth): add JWT middleware`.

## Examples
**Input**: Added user authentication with JWT tokens
**Output**:
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

## Rules
- Subject ≤ 72 chars, imperative mood, no trailing period
- Body wraps at 72 chars
- Scopes drawn from package.json `workspaces`

风格 2：脚本驱动型（script-driven skill）

典型场景：PDF 表单填写、OOXML 编辑、数据库 migration、批量验证——「LLM 算不准 / 不该让 LLM 算」的活。
特征：SKILL.md 短，主要任务是告诉 Claude 「跑 python scripts/xxx.py」。脚本输出（不是脚本源码）才进 context。
优点：确定性高、token 极省、可复现。
缺点：需要维护脚本依赖；API surface 没有网络/运行时装包能力，依赖必须预装。
真实例子：anthropics/skills/skills/pdf、anthropics/skills/skills/docx。

---
name: filling-pdf-forms
description: Fills interactive PDF forms by analyzing fields, mapping values, and validating output. Use when the user provides a PDF form, mentions "fill form", "PDF fields", or asks to populate a .pdf with data.
allowed-tools: Read, Bash
---

# Filling PDF Forms

## Workflow
- [ ] Step 1: `python scripts/analyze_form.py input.pdf > fields.json`
- [ ] Step 2: Edit fields.json to set values
- [ ] Step 3: `python scripts/validate_fields.py fields.json`
- [ ] Step 4: `python scripts/fill_form.py input.pdf fields.json output.pdf`
- [ ] Step 5: `python scripts/verify_output.py output.pdf`

If validation fails at step 3, return to step 2.

## Dependencies
Requires pypdf and pdfplumber (pre-installed in API code execution env).

For advanced redlining/OOXML, see [REDLINING.md](REDLINING.md).

风格 3：模板/资源型（template & reference skill）

典型场景：BigQuery schema 库、API doc 库、企业知识库、品牌素材库。
特征：SKILL.md 是「目录页」，正文短、用一级链接指向 reference/finance.md、reference/sales.md 等；正文几乎不含具体内容。
优点：Skill 总体可以非常大（GB 级也行），但只在被需要时按文件加载。
缺点：必须把链接保持一级深度——嵌套引用会让 Claude 只读 100 行就停。
真实例子：官方 best-practices 给的 BigQuery 多 dataset 范式；anthropics/skills 中的 claude-api-skill（按 8 种语言切分文档）。

---
name: querying-bigquery
description: Writes BigQuery SQL using internal datasets. Use when user asks for revenue, ARR, pipeline, opportunities, API usage, marketing attribution, or mentions BigQuery / .sql / a known dataset name.
allowed-tools: Read, Bash, BigQuery:bigquery_schema
---

# Querying BigQuery

## Available datasets (one-level deep references)

- **Finance** (revenue, ARR, billing) → see [reference/finance.md](reference/finance.md)
- **Sales** (opportunities, pipeline) → see [reference/sales.md](reference/sales.md)
- **Product** (API usage, features) → see [reference/product.md](reference/product.md)
- **Marketing** (campaigns, attribution) → see [reference/marketing.md](reference/marketing.md)

## Hard rules
- ALWAYS exclude rows where `account_type = 'test'`.
- ALWAYS use UTC for date filters.
- Use BigQuery:bigquery_schema (full MCP name) before guessing column names.

## Quick search
grep -i "revenue" reference/finance.md

风格 4：工作流编排型（workflow / pipeline skill）

典型场景：发布流程、incident response、安全审计、研究报告生成。
特征：SKILL.md 是带 checkbox 的多步流程，每步指明用什么工具/脚本/sub-agent；带 feedback loop（validator → fix → repeat）。
优点：把脆弱的多步操作变可复现；Claude 能逐步勾选。
缺点：写起来重；流程一长触发率会降，因为描述要兼顾多种入口。
真实例子：obra/superpowers/skills/executing-plans、wshobson/commands 中的 /workflows:feature-development。

---
name: releasing-to-production
description: Runs the full pre-prod release checklist (tests, changelog, version bump, deploy, smoke test). Use when the user says "release", "ship", "deploy to prod", "cut a version", or mentions a semver bump. Do NOT activate for hotfix/cherry-pick flows.
allowed-tools: Read, Bash, Grep
---

# Releasing to Production

Copy this checklist and tick as you go:

```
Release Progress:
- [ ] 1. Run full test suite
- [ ] 2. Generate changelog from commits since last tag
- [ ] 3. Bump version in package.json + lockfile
- [ ] 4. Tag & push
- [ ] 5. Trigger deploy workflow
- [ ] 6. Smoke test prod URL
```

Step 1: `pnpm test --run`. If fail → STOP, report.
Step 2: `python scripts/gen_changelog.py --since=last-tag > CHANGELOG.next.md`
Step 3: `npm version <patch|minor|major>` per scripts/decide_bump.py output
Step 4: `git push --follow-tags`
Step 5: `gh workflow run deploy.yml --ref main`
Step 6: `python scripts/smoke_test.py https://app.example.com`

Validation loop: if step 6 fails, run rollback in scripts/rollback.sh and return to step 1.

风格 5：元 Skill / skill-of-skills（meta skill）

典型场景：用 Skill 来生成/审查/管理其他 Skill（Anthropic 官方 skill-creator、obra/superpowers/skills/writing-skills）。
特征：description 强调「当用户要求创建/编辑/审计 skill 时」；正文教 Claude 走 build-eval-iterate 流程，并产出符合 frontmatter 规范的 SKILL.md。
优点：把「如何写好 Skill」本身规范化、可复用；适合非开发者通过对话造 Skill。
缺点：依赖底层模型对 Skill spec 的理解；输出仍需人工审；容易和其他「写文档」类 Skill 触发冲突。
真实例子：官方 skill-creator、obra/superpowers writing-skills。

---
name: writing-skills
description: Creates new Claude Agent Skills with proper SKILL.md frontmatter, progressive disclosure, and evaluations. Use when the user says "create a skill", "make a new skill", "write a SKILL.md", or asks to bundle a workflow as a reusable Skill. Do NOT use for editing prompts or sub-agents.
---

# Writing Skills

## Workflow
1. Interview user: what gap, what triggers, what surfaces (API/Code/claude.ai)?
2. Draft 3 candidate descriptions; rank by specificity + trigger keywords.
3. Generate folder skeleton (SKILL.md, scripts/, references/, evals/).
4. Write 3 evaluations BEFORE writing SKILL.md body.
5. Validate frontmatter: name ≤64 chars, lowercase+hyphens, no "anthropic"/"claude"; description ≤1024 chars, third-person, "Use when ..." clause.
6. Run evals against current Claude; iterate description until activation rate ≥ baseline.

## Hard rules
- Never embed secrets / API keys.
- Always forward slashes in paths.
- Keep SKILL.md body ≤ 500 lines, references one level deep.
- For each script, state explicitly: "Run X" vs "Read X as reference".

## Templates
- Pure-prompt: see templates/pure_prompt.md
- Script-driven: see templates/script_driven.md
- Workflow: see templates/workflow.md

五种风格速查表

风格	一句话定义	何时选	何时别选
纯 prompt 型	只有 SKILL.md 的规则集	风格规范、checklist、tone 指南	需要确定性运算
脚本驱动型	LLM 调用 bundled 脚本	文件处理、数据计算、迁移	API surface 又需要联网装包
模板/资源型	SKILL.md 当目录页	大体量知识库、schema 库	小而美的单一任务
工作流编排型	多步 checklist + 验证回路	发布、审计、incident、多阶段研究	单步任务，会过度工程
元 Skill 型	用 Skill 创建/管理 Skill	给团队造 Skill 工厂	个人一次性 Skill

description 写法清单（核心中的核心）

社区共识压缩成一张写 description 的 checklist：

第三人称起手（”Generates / Extracts / Reviews”），不要 “I can”。
第一句讲做什么，第二句以 Use when... 开头讲何时触发。
列出触发关键词（用户可能说的原话/文件后缀/工具名）。
加 1 条反向约束：Do NOT activate when ...，避免误触发。
总长 ≤ 1024 字符；避免和现有 Skill 描述重叠。
高优先级流程可用命令式：”ALWAYS invoke this skill when …”。
不写自夸词（”powerful”, “best”），它们不增加触发概率。

不确定性

allowed-tools 字段的「官方权威性」 仍模糊：官方 overview / best-practices 没把它列入 frontmatter spec，但 Claude Code 生态、anthropics/skills 实例和大量第三方 Skill 都广泛使用。最稳妥的判断是：Claude Code surface 支持，API surface 行为可能不同，建议看你部署的 surface 文档再下判断。
触发率的具体数字（如「37% → 100%」「20x 提升」）来源多为中文社区与个人博客复述，未见 Anthropic 官方 benchmark；当作经验性方向参考、不要当作硬指标。
anthropics/skills 的星标和 fork 数：搜索结果给出 149k stars / 17.5k forks 的数字看起来过高，可能是抓取时混入了其他仓库或镜像。建议以 GitHub 实际页面为准。
「15k tokens 的 available_skills 上限」：广泛在社区流传但 Anthropic 没有公开声明；当作软性预算上限处理。
跨 surface 同步：现状是不同步，但 Anthropic 在 2025 年底有「Skills sharing 大升级」的报道，细节未读到一手公告。

后续行动

建一个本仓库的 .claude/skills/ 目录，先写一个「pure-prompt 型」最小 Skill 验证 frontmatter（name、description、可选 allowed-tools）在 Claude Code 上是否被识别。
用 obra/superpowers 的 writing-skills 或 anthropics/skills 的 skill-creator 作为元 Skill 启动器，对比两者生成的 SKILL.md 风格差异。
写 3 条 description 候选，做 A/B 触发测试（用同一组 5–10 句日常请求，统计自动触发率）。
给团队用：把 Skills 放进单一 git repo（”Skillplane”），用 Plugin namespace 避免命令冲突；明确禁用第三方未审计 Skill。
在 Obsidian 里以本笔记为蓝本沉淀「公司内部 Skills 风格指南」，重点写两件事：① 描述模板（”Verb + 何时触发 + 何时不触发”）；② 命名约定（gerund 形式：processing-xxx / writing-xxx）。
若计划公开发布到 Hexo，给本笔记加 publish: true；当前默认仅 Obsidian 私有。

来源

官方一手

官方 / 高质量 GitHub 仓库

独立社区 / 技术博客（≥3 个独立来源）