# The Anatomy of a Perfect Skill: Reverse-Engineered from 100 Best Examples
**作者**: darkzodchi
**日期**: 2026-04-26T10:16:27.000Z
**来源**: [https://x.com/zodchiii/status/2048345453096313005](https://x.com/zodchiii/status/2048345453096313005)
---
Most skills don't work. The ones that do follow the same 6 patterns.
I'll walk through each one with real examples from skills people actually use daily.
By the end you'll know exactly why your custom skills don't fire and how to fix them👇
Before we dive in, I share daily notes on AI & vibe coding in my Telegram channel: https://t.me/zodchixquant🧠
## The 30-second refresher
A skill is a markdown file with YAML frontmatter at the top and instructions below.
You put it in ~/.claude/skills/skill-name/SKILL.md. C
laude loads it automatically when context matches the description, or you invoke it manually with /skill-name.
```
~/.claude/skills/
├── commit/SKILL.md → /commit
├── code-review/SKILL.md → /code-review
└── deploy/
├── SKILL.md → /deploy
└── scripts/helper.sh
```
That's the whole architecture. The hard part is what goes inside SKILL.md.
## Pattern 1: Description tells Claude WHEN, not just WHAT
This is the single most important field. Claude scans descriptions of all available skills before deciding which to load. If your description only says what the skill does, Claude won't know when to use it.
Bad description:
```
description: Code review tool
```
Good description:
```
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".
```
The good one tells Claude: what the skill does + when to trigger it + which keywords to listen for.
Skills with descriptions under 50 characters get invoked 3-5x less often than skills with proper trigger context. Front-load the use case in the first 250 characters because that's all that gets included in Claude's context budget.
## Pattern 2: Be directive, not conversational
Skills are instructions, not chat. Use imperative verbs.
Conversational (weak):
```
Could you please review the code? Maybe check if there are any bugs?
```
Directive (strong):
```
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 follows imperative instructions much more reliably than questions or polite requests.
Look at any skill from the official Anthropic repository, and you'll see the same pattern: direct verbs, numbered steps, explicit output formats.
## Pattern 3: Specify the output format
This is where most custom skills fail. They tell Claude what to do but not what the output should look like. Claude makes up a format every time and the results are inconsistent.
Without output format:
```
Generate a commit message for these changes.
```
You get: sometimes one line, sometimes paragraphs, sometimes with prefixes, sometimes without.
With output format:
```
Generate a commit message in this exact format:
type(scope): short description
- Bullet point of what changed
- Bullet point of why it changed
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.
```
Now you get the same output structure every time. The skill is reusable.
## Pattern 4: Include the "read first" step
The best skills don't assume Claude knows your project. They tell Claude to look first.
Take the /test skill from the awesome-claude-skills repo. Instead of "write tests," it does this:
```
Before writing tests:
1. Read the target file to understand function signatures and types
2. Find the existing test directory and read 1-2 existing tests
3. Identify the testing framework (Jest, Vitest, Pytest, etc.)
4. Note the import style and assertion patterns
Then generate tests covering:
- Happy path
- Edge cases (empty, null, zero, max values)
- Error cases
- Async behavior (if applicable)
Match exact import style and patterns from existing tests.
Run tests after writing them. Fix failures before finishing.
```
The "read first" step is what separates skills that produce code matching your project from skills that produce generic code that breaks your linter.
## Pattern 5: Define what the skill does NOT do
Counterintuitive but powerful. The best skills explicitly list what's out of scope.
From Anthropic's official PDF skill:
```
## Out of Scope
This skill does NOT:
- Handle scanned PDFs (use OCR skill instead)
- Create PDFs from scratch (use document-generation skill)
- Process password-protected files
```
Why this matters: when a user asks for something the skill can't do, Claude doesn't try and fail.
It either picks a different skill or asks for clarification. You get fewer broken outputs and more correct routing.
This pattern shows up in 70% of high-quality skills and almost never in low-quality ones.
## Pattern 6: Keep it under 500 lines
Every skill loads into Claude's context when invoked. A 2000-line skill eats 5000+ tokens before doing anything.
The longer the skill, the more chance Claude loses focus halfway through and starts ignoring instructions at the bottom.
The official Anthropic skills (frontend-design, code-review, security-guidance) are all under 300 lines. The community skills with the most installs (Superpowers, Context7, mcp-builder) are similarly tight.
If your skill is getting long, split it. Use the progressive disclosure pattern:
```
SKILL.md (under 200 lines, always loaded)
├── ADVANCED_PATTERNS.md (loaded only when needed)
├── REFERENCE.md (loaded only when referenced)
└── EXAMPLES.md (loaded only when Claude needs examples)
```
In SKILL.md you reference the other files:
```
For complex form filling, see [FORMS.md](FORMS.md)
For full API reference, see [REFERENCE.md](REFERENCE.md)
For more examples, see [EXAMPLES.md](EXAMPLES.md)
```
Claude loads the supporting files only when the task actually needs them.
## A real example: The /commit skill, broken down
Here's a /commit skill that follows all 6 patterns. This is what good looks like:
```
---
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
```
Notice:
- Description tells Claude WHEN
- Instructions are directive (imperative verbs, numbered steps)
- Output format is explicit (the commit message structure)
- "Read first" step is built in (git status, git diff)
- Out of scope is defined
- Total length: under 50 lines
This skill works on every project, in every language, every time.
## What kills skills
The skills that don't work share these failure patterns:
```
DESCRIPTION FAILURES:
- Under 50 characters
- Inconsistent point of view ("I help" vs "You can use this")
- No trigger keywords
- No use case context
CONTENT FAILURES:
- Conversational instead of directive
- No output format specified
- No "read first" step
- No out-of-scope section
- Over 1000 lines
DESIGN FAILURES:
- Trying to do 5 things in one skill
- Hardcoded to one project's specifics
- No version control on the skill itself
- Never updated after first write
```
If your custom skill checks 3+ of these boxes, it's probably not getting invoked or producing bad output.
## How to fix existing skills
Pull up your weakest skill (the one Claude never invokes). Run through this checklist:
```
1. Description: Does it have at least 3 trigger keywords?
2. Description: Is the use case in the first 250 characters?
3. Instructions: Are they imperative verbs in numbered steps?
4. Output: Is the format specified explicitly?
5. Project awareness: Does it tell Claude to read existing files first?
6. Scope: Does it list what the skill does NOT do?
7. Length: Is the SKILL.md under 500 lines?
```
Fix the failed ones. Test by asking Claude something the skill should handle without invoking it manually.
If Claude picks the right skill, your description is working. If it picks a different skill or none at all, the description needs more trigger context.
## The compounding effect
Bad skills make Claude slower (eating context for nothing), produce inconsistent output (no format), and route incorrectly (vague descriptions).
Good skills compound in the opposite direction.
Each well-written skill makes Claude better at picking the right one for any task. The skills become a system, not a collection.
The skills folder of someone who's been doing this for 6 months looks completely different from someone who just started.
Same Claude, completely different output quality.
I share daily notes on AI, finance, and vibe coding in my Telegram channel: https://t.me/zodchixquant
Thanks for reading🙏🏼
## 相关链接
- [darkzodchi](https://x.com/zodchiii)
- [@zodchiii](https://x.com/zodchiii)
- [1.1K](https://x.com/zodchiii/status/2048345453096313005/analytics)
- [https://t.me/zodchixquant](https://t.me/zodchixquant)
- [https://t.me/zodchixquant](https://t.me/zodchixquant)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [6:16 PM · Apr 26, 2026](https://x.com/zodchiii/status/2048345453096313005)
- [1,159 Views](https://x.com/zodchiii/status/2048345453096313005/analytics)
- [View quotes](https://x.com/zodchiii/status/2048345453096313005/quotes)
---
*导出时间: 2026/4/26 21:00:54*
---
## 中文翻译
# 完美技能的剖析：从 100 个最佳案例中逆向工程得出
**作者**: darkzodchi
**日期**: 2026-04-26T10:16:27.000Z
**来源**: [https://x.com/zodchiii/status/2048345453096313005](https://x.com/zodchiii/status/2048345453096313005)
大多数技能都不起作用。那些起作用的都遵循相同的 6 个模式。
我将结合人们日常实际使用的真实案例逐一讲解。
读完本文，你将准确知道为什么你的自定义技能无法触发，以及如何修复它们👇
在深入之前，我在我的 Telegram 频道分享关于 AI 和 vibe coding 的日常笔记：https://t.me/zodchixquant🧠
## 30 秒回顾
所谓技能（Skill），就是一个顶部带有 YAML frontmatter、下方包含指令的 Markdown 文件。
你将其放在 ~/.claude/skills/skill-name/SKILL.md 中。
当上下文匹配描述时，Claude 会自动加载它，或者你可以使用 /skill-name 手动调用它。
```
~/.claude/skills/
├── commit/SKILL.md → /commit
├── code-review/SKILL.md → /code-review
└── deploy/
├── SKILL.md → /deploy
└── scripts/helper.sh
```
这就是整个架构。难点在于 SKILL.md 里面的内容。
## 模式 1：描述告诉 Claude 何时使用，而不仅仅是做什么
这是最重要的字段。Claude 在决定加载哪个技能之前会扫描所有可用技能的描述。如果你的描述只说了技能是做什么的，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：使用祈使语气，而非对话式
技能是指令，不是聊天。使用祈使动词。
**对话式（软弱）：**
```
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 仓库中的任何技能，你会看到相同的模式：直接的动词、编号的步骤、明确的输出格式。
## 模式 3：指定输出格式
这是大多数自定义技能失败的地方。它们告诉 Claude 做什么，却没说输出应该长什么样。Claude 每次都会自己编造格式，导致结果不一致。
**没有输出格式：**
```
Generate a commit message for these changes.
```
你会得到：有时是一行，有时是段落，有时带前缀，有时不带。
**带有输出格式：**
```
Generate a commit message in this exact format:
type(scope): short description
- Bullet point of what changed
- Bullet point of why it changed
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.
```
现在你每次都能得到相同的输出结构。该技能变得可复用。
## 模式 4：包含“先读”步骤
最好的技能不会假定 Claude 了解你的项目。它们会告诉 Claude 先看一眼。
以 awesome-claude-skills 仓库中的 /test 技能为例。它不是简单地“写测试”，而是这样做：
```
Before writing tests:
1. Read the target file to understand function signatures and types
2. Find the existing test directory and read 1-2 existing tests
3. Identify the testing framework (Jest, Vitest, Pytest, etc.)
4. Note the import style and assertion patterns
Then generate tests covering:
- Happy path
- Edge cases (empty, null, zero, max values)
- Error cases
- Async behavior (if applicable)
Match exact import style and patterns from existing tests.
Run tests after writing them. Fix failures before finishing.
```
“先读”这一步，正是那些能生成符合项目规范的代码的技能，与那些生成让 linter 报错的通用代码的技能之间的区别所在。
## 模式 5：定义技能**不**做什么
这违反直觉，但非常强大。最好的技能会明确列出什么不在其范围内。
摘自 Anthropic 官方 PDF 技能：
```
## Out of Scope
This skill does NOT:
- Handle scanned PDFs (use OCR skill instead)
- Create PDFs from scratch (use document-generation skill)
- Process password-protected files
```
为什么这很重要：当用户要求技能做不到的事情时，Claude 不会尝试执行然后失败。
它会选择不同的技能，或者请求澄清。这样你会得到更少的错误输出和更正确的路由。
这种模式出现在 70% 的高质量技能中，而在低质量技能中几乎从未出现过。
## 模式 6：保持在 500 行以内
每个技能在被调用时都会加载到 Claude 的上下文中。一个 2000 行的技能在做任何事之前就要消耗 5000+ 个 token。
技能越长，Claude 在半途走神并开始忽略底部指令的可能性就越大。
官方 Anthropic 技能（frontend-design、code-review、security-guidance）都在 300 行以内。安装量最多的社区技能（Superpowers、Context7、mcp-builder）也同样精简。
如果你的技能变长了，把它拆分。使用渐进式披露模式：
```
SKILL.md (under 200 lines, always loaded)
├── ADVANCED_PATTERNS.md (loaded only when needed)
├── REFERENCE.md (loaded only when referenced)
└── EXAMPLES.md (loaded only when Claude needs examples)
```
在 SKILL.md 中引用其他文件：
```
For complex form filling, see [FORMS.md](FORMS.md)
For full API reference, see [REFERENCE.md](REFERENCE.md)
For more examples, see [EXAMPLES.md](EXAMPLES.md)
```
Claude 只在任务真正需要时才会加载这些辅助文件。
## 真实案例：/commit 技能拆解
这是一个遵循所有 6 个模式的 /commit 技能。这就是好的技能的样子：
```
---
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
```
请注意：
- 描述告诉 Claude 何时（WHEN）使用
- 指令是指令式的（祈使动词、编号步骤）
- 输出格式明确（commit message 结构）
- 内置“先读”步骤（git status, git diff）
- 定义了超出范围的内容
- 总长度：50 行以内
这个技能在每个项目、每种语言中每次都能完美运行。
## 技能的杀手
不起作用的技能都有以下失败模式：
```
DESCRIPTION FAILURES:
- Under 50 characters
- Inconsistent point of view ("I help" vs "You can use this")
- No trigger keywords
- No use case context
CONTENT FAILURES:
- Conversational instead of directive
- No output format specified
- No "read first" step
- No out-of-scope section
- Over 1000 lines
DESIGN FAILURES:
- Trying to do 5 things in one skill
- Hardcoded to one project's specifics
- No version control on the skill itself
- Never updated after first write
```
如果你的自定义技能符合上述 3 点以上，它可能无法被调用，或者产生糟糕的输出。
## 如何修复现有技能
打开你最弱的那个技能（Claude 从不调用的那个）。对照这个清单检查：
```
1. Description: Does it have at least 3 trigger keywords?
2. Description: Is the use case in the first 250 characters?
3. Instructions: Are they imperative verbs in numbered steps?
4. Output: Is the format specified explicitly?
5. Project awareness: Does it tell Claude to read existing files first?
6. Scope: Does it list what the skill does NOT do?
7. Length: Is the SKILL.md under 500 lines?
```
修复失败的项。通过向 Claude 提问一个该技能应处理的内容来测试，且不要手动调用。
如果 Claude 选对了技能，你的描述是有效的。如果它选了不同的技能或根本没选，描述需要更多的触发上下文。
## 复利效应
糟糕的技能会让 Claude 变慢（白白消耗上下文），产生不一致的输出（无格式），并导致路由错误（描述模糊）。
好的技能则会产生相反方向的复利效应。
每个编写精良的技能都会让 Claude 在为任何任务选择正确技能时变得更聪明。技能变成一个系统，而不是一堆集合。
一个坚持这样做 6 个月的人的 skills 文件夹，看起来与刚入门的人完全不同。
同样的 Claude，完全不同的输出质量。
我在我的 Telegram 频道分享关于 AI、金融和 vibe coding 的日常笔记：https://t.me/zodchixquant
感谢阅读🙏🏼
## 相关链接
- [darkzodchi](https://x.com/zodchiii)
- [@zodchiii](https://x.com/zodchiii)
- [1.1K](https://x.com/zodchiii/status/2048345453096313005/analytics)
- [https://t.me/zodchixquant](https://t.me/zodchixquant)
- [https://t.me/zodchixquant](https://t.me/zodchixquant)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [6:16 PM · Apr 26, 2026](https://x.com/zodchiii/status/2048345453096313005)
- [1,159 Views](https://x.com/zodchiii/status/2048345453096313005/analytics)
- [View quotes](https://x.com/zodchiii/status/2048345453096313005/quotes)
---
*导出时间: 2026/4/26 21:00:54*