大多数 Skill 不起作用。起作用的那 6 个遵循相同的模式。
模式 1：描述是唯一最重要的字段
Claude 在决定加载哪个 Skill 之前会扫描所有可用 Skill 的描述。如果你的描述只说 Skill 做什么，Claude 不知道什么时候该调用它。
坏描述：
description: Code review tool
好描述：
description: Review code for bugs, security issues, and maintainability.
Use when reviewing pull requests, checking code quality, analyzing diffs,
or when user mentions "review", "PR", "code quality", or "best practices".
好描述告诉 Claude 三件事：做什么 + 何时触发 + 监听哪些关键词。
50 字符以下的描述比有正确触发上下文的描述调用率低 3-5 倍。把用例放在前 250 字符里——那是会被装进 Claude 上下文预算的全部内容。
模式 2：指令是命令式的，不是对话式的
Skill 是指令，不是聊天。用祈使动词。
对话式（弱）：
Could you please review the code? Maybe check if there are any bugs?
命令式（强）：
Review the current diff. Check for:
1. Security vulnerabilities (OWASP Top 10)
2. Performance issues (N+1 queries, blocking calls)
3. Code style violations
Output as a checklist with severity ratings.
Claude 对命令式指令的遵循度高得多。看官方 Anthropic 仓库里的任何 Skill，都是同一个模式：直接动词、编号步骤、显式输出格式。
模式 3：指定输出格式
这是大多数自定义 Skill 失败的地方。它们告诉 Claude 要做什么，但不告诉输出应该长什么样。Claude 每次都自己编格式，结果不一致。
没有输出格式：
Generate a commit message for these changes.
结果：有时一行，有时段落，有时有前缀，有时没有。
有输出格式：
Generate a commit message in this exact format:
type(scope): short description
- What changed
- Why it changed (if not obvious)
Type must be one of: feat, fix, refactor, docs, test, chore.
Scope is the affected module name.
Short description is under 50 characters, present tense, lowercase.
现在每次输出结构一致。Skill 可复用。
模式 4：告诉 Claude 先读
最好的 Skill 不假设 Claude 了解你的项目。它们告诉 Claude 先看。
awesome-claude-skills 仓库里的 /test Skill 不是"写测试"，而是：
写测试之前：
1. 读目标文件，理解函数签名和类型
2. 找到现有测试目录，读 1-2 个现有测试
3. 确定测试框架（Jest、Vitest、Pytest 等）
4. 记录导入风格和断言模式
然后生成覆盖以下内容的测试：
- 幸福路径
- 边界情况（空、null、零、最大值）
- 错误情况
- 异步行为（如适用）
匹配现有测试的确切导入风格和模式。
写完后运行测试。修复失败再结束。
"先读"步骤区分了产生匹配你项目的代码的 Skill 和产生通用代码（破坏你的 linter）的 Skill。
模式 5：定义范围外内容
反直觉但强大。最好的 Skill 显式列出范围外的内容。
Anthropic 官方 PDF Skill：
## 范围之外
本 Skill 不处理：
- 扫描 PDF（使用 OCR Skill）
- 从零创建 PDF（使用文档生成 Skill）
- 处理密码保护文件
为什么重要：当用户问 Skill 做不了的事，Claude 不会尝试然后失败。它要么选择另一个 Skill，要么要求澄清。减少破碎输出，正确路由更多。
高质量 Skill 中 70% 有这个模式，低质量 Skill 几乎从没有。
模式 6：SKILL.md 保持在 300 行以内
每个 Skill 被调用时都加载到 Claude 上下文。2000 行的 Skill 在做任何事之前就吃掉 5000+ token。
Skill 越长，Claude 半路失去焦点、开始忽略底部指令的可能性越大。
官方 Anthropic Skill（frontend-design、code-review、security-guidance）都在 300 行以内。社区安装量最多的 Skill（Superpowers、Context7、mcp-builder）同样精简。
如果你的 Skill 变长了，拆开它。用渐进披露模式：
SKILL.md（200 行以内，始终加载）
├── ADVANCED_PATTERNS.md（仅在需要时加载）
├── REFERENCE.md（仅在被引用时加载）
└── EXAMPLES.md（仅在 Claude 需要示例时加载）
完整的 /commit Skill 示例
---
name: commit
description: Create structured git commits from current changes.
Use when user says "commit", "save changes", "commit this", or after
finishing a feature. Breaks changes into logical units with clear messages.
---
Create commits from current git state.
## Process
1. Run `git status` and `git diff` to see all changes
2. Group related changes into logical units (one feature = one commit)
3. For each unit, generate a commit message in this format:
type(scope): short description
- What changed
- Why it changed (if not obvious)
4. Stage and commit each unit separately using `git add` then `git commit`
5. Show summary: "Created N commits: [list of titles]"
## Rules
- Type must be: feat, fix, refactor, docs, test, chore
- Description is under 50 characters, lowercase, present tense
- Bullets are concise, no fluff
- Never combine unrelated changes in one commit
## Out of Scope
- Pushing to remote (use /push or git push manually)
- Creating PRs (use /pr skill)
- Merging branches
这个 Skill 在每个项目、每种语言、每次都有效。
自检清单
3 个以上中招？你的 Skill 可能没有被调用或输出糟糕。
1. 描述：至少有 3 个触发关键词？
2. 描述：用例在前 250 字符？
3. 指令：用祈使动词和编号步骤？
4. 输出：格式显式指定？
5. 项目感知：告诉 Claude 先读现有文件？
6. 范围：列出 Skill 不做的事？
7. 长度：SKILL.md 在 500 行以内？
复利效应
坏 Skill 让 Claude 更慢（吃 token 但无用）、产出不一致（无格式）、路由错误（描述模糊）。
好 Skill 向相反方向复利。每个写得好 Skill 让 Claude 更擅长为任何任务选择正确的 Skill。Skill 成为系统，不是集合。
做这件事 6 个月的人和刚起步的人，他们的 Skill 文件夹看起来完全不同。同一个 Claude，输出质量完全不同。