# Claude Code + SKILL.md: build your first auto-invoking AI workflow in 15 minutes
**作者**: Nyk
**日期**: 2026-04-25T19:01:45.000Z
**来源**: [https://x.com/nyk_builderz/status/2048115264680829238](https://x.com/nyk_builderz/status/2048115264680829238)
---
I took the official docs, the top community skills (superpowers at 96K stars, gstack at 20K stars), and my own experience building skills for the x-article-factory pipeline - and put together the guide I wish existed when I started.
This is a long article. At the end of it, you will have a working skill. To help you navigate, here are the 7 sections:
1. What a skill actually is
2. The SKILL.md structure
3. Your first skill in 5 minutes
4. Auto-invocation (the magic part)
5. Adding templates and supporting files
6. 5 beginner skill types to start with
7. The mistakes that waste your time
Let's get into it.
## 1: What a skill actually is
A skill is a markdown file that teaches Claude Code how to do something it could not do before, or prevents a failure mode that costs you time every session.
That is it.
Not a plugin. Not a framework. Not an API integration. A markdown file in a folder.
When Claude encounters a task that matches the skill's description, it loads the skill automatically and follows the instructions. You do not need to invoke it manually. You do not need to write a prompt. The skill fires when relevant.
Skills vs commands vs agents:
- commands Wait for you to type /command-name. They are manual triggers.
- Agents are specialized subagent personas that run in their own context window.
- skills Watch the conversation and activate when the task matches. They are automatic.
The difference matters. Commands are buttons. Agents are specialists. Skills are instincts.
## 2: The SKILL.md structure
Every skill lives in its own directory with a SKILL.md file as the entry point.
The SKILL.md has two parts: frontmatter and instructions.
```
---
name: security-review
description: Comprehensive security audit. Use when reviewing
code for vulnerabilities, before deployments, or when the
user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:
1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication gaps
Report findings with severity ratings and specific fixes.
Reference @DETAILED_GUIDE.md for our security standards.
```
The description is everything. Claude reads it to decide whether to activate the skill. If the description is vague ("help with code"), the skill fires too often. If it is too narrow ("only for Python 3.11 FastAPI handlers"), it never fires.
The sweet spot: Describe the trigger condition, not the skill itself. "Use when reviewing code for vulnerabilities" is better than "security review tool."
## 3: Your first skill in 5 minutes
Let's build one. Right now.
The most useful beginner skill: a code review skill that checks for the problems your team actually has.
Step 1: Create the directory.
```
mkdir -p .claude/skills/code-review
```
Step 2: Write the SKILL.md.
```
---
name: code-review
description: Expert code reviewer. Use PROACTIVELY when
reviewing PRs, checking for bugs, or before merging.
allowed-tools: Read, Grep, Glob
---
You are a senior code reviewer focused on correctness.
When reviewing code:
- Flag bugs, not style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only at scale
Output format:
## Critical (must fix)
## Warnings (should fix)
## Notes (consider)
```
Step 3: Restart Claude Code or start a new session.
Step 4: Ask Claude to review some code. It will automatically load the skill.
That is a working skill. Total time: under 5 minutes.
## 4: auto-invocation (the magic part)
This is where skills become powerful.
Claude reads the description field in the frontmatter and decides whether to activate the skill based on the current task. You never type /code-review. Claude sees you working on a PR and loads the skill because the description matches.
How to control when skills fire:
Make the description specific. "Use when the user asks to review a pull request or when checking code before merging" fires on PR reviews. "Use for code" fires on everything.
The allowed-tools field restricts what the skill can do. A security review skill should only Read, Grep, and Glob — it should not Write or Edit files. This is your safety net.
Path-scoped activation. Add a paths field to the frontmatter:
```
---
paths:
- "src/api/**/*.ts"
- "src/handlers/**/*.ts"
---
```
Now the skill only activates when Claude is working with files that match those patterns. An API conventions skill that only fires for API files. A test standards skill that only fires for test files.
## 5: Adding templates and supporting files
Skills can bundle supporting files alongside them. This is what makes them packages, not just prompts.
```
.claude/skills/security-review/
├── SKILL.md
├── DETAILED_GUIDE.md # referenced with @
├── templates/
│ └── security-report.md # output template
└── examples/
└── good-review.md # example output
```
Reference files with @FILENAME.md in the skill instructions. Claude will load them when the skill activates.
When to add supporting files:
- The skill needs a detailed guide that would bloat the SKILL.md
- You want a consistent output template
- You have example outputs that show "what good looks like"
When not to: If the SKILL.md is under 50 lines, you probably do not need supporting files. Keep it simple.
## 6: 5 beginner skill types to start with
Do not try to build a complex multi-file skill on day one. Start with one of these.
1. Review skill. Checks code for specific problems. The example above. Easiest to build, highest immediate value.
2. Debugging skill. Forces a methodology before Claude starts guessing. "reproduce → isolate → hypothesize → verify" prevents the "guess and apply" loop that creates new bugs.
3. Documentation skill. Generates docs in your team's format. Give it a template, let it fill it in. Consistency without manual effort.
4. Test-first skill. Forces Claude to write the test before the implementation. Reverses the default behavior of "write code, then backfill tests that pass by definition."
5. Deploy skill. Runs your deployment checklist. Version bump, changelog, build, test, tag, push. Automates the sequence you always do manually.
Start with whichever matches your biggest daily friction. Install one tonight.
## 7: The mistakes that waste your time
Mistake 1: descriptions are too broad. "help with coding" matches everything and adds noise to every session. Be specific about the trigger.
mistake 2: too many instructions. A 200-line SKILL.md eats context without adding proportional value. If you cannot say it in 50 lines, split it into a SKILL.md and a @DETAILED_GUIDE.md.
mistake 3: no examples. Claude follows examples better than rules. If you want a specific output format, show it — do not just describe it.
mistake 4: skipping allowed-tools. Without tool restrictions, a skill can read, write, edit, and execute anything. Always specify the minimum tools needed.
mistake 5: building multi-file skills before single-file skills work. Master the basics. Add complexity only when the simple version fails.
## You can now build a skill
The most important thing I learned: a skill is not code. It is a behavioral contract written in markdown. The better you define the trigger, the instructions, and the output format, the more reliably Claude delivers.
Start with one skill. Test it on 5 real tasks. Improve one thing. Then build the next one.
Personal skills go in ~/.claude/skills/ (available in every project). Project skills go in .claude/skills/ (shared with your team via git).
The skill marketplace has 80,000+ entries. But the one you write yourself — for your specific workflow, your specific gotchas, your specific team — will always outperform a generic download.
What is the one task Claude keeps getting wrong that a 20-line skill would fix?
## 相关链接
- [Nyk](https://x.com/nyk_builderz)
- [@nyk_builderz](https://x.com/nyk_builderz)
- [@FILENAME](https://x.com/@FILENAME)
- [@DETAILED_GUIDE](https://x.com/@DETAILED_GUIDE)
- [Upgrade to Premium](https://x.com/i/premium_sign_up)
- [3:01 AM · Apr 26, 2026](https://x.com/nyk_builderz/status/2048115264680829238)
- [3,037 Views](https://x.com/nyk_builderz/status/2048115264680829238/analytics)
---
*导出时间: 2026/4/26 12:08:23*
---
## 中文翻译
# Claude Code + SKILL.md：15 分钟构建你的第一个自动触发的 AI 工作流
**作者**: Nyk
**日期**: 2026-04-25T19:01:45.000Z
**来源**: [https://x.com/nyk_builderz/status/2048115264680829238](https://x.com/nyk_builderz/status/2048115264680829238)
---
我结合了官方文档、最热门的社区技能（superpowers 有 96K star，gstack 有 20K star），以及我自己为 x-article-factory 流水线构建技能的经验，写出了这份指南——我入门时真希望有这样一篇教程。
这是一篇长文。读完之后，你将拥有一个可用的技能。为了方便你阅读，全文分为 7 个部分：
1. 技能到底是什么
2. SKILL.md 的结构
3. 5 分钟做出你的第一个技能
4. 自动触发（神奇的部分）
5. 添加模板和辅助文件
6. 新手入门的 5 种技能类型
7. 浪费你时间的常见错误
让我们开始吧。
## 1：技能到底是什么
技能就是一个 markdown 文件，它教会 Claude Code 去做它以前做不到的事情，或者防止那种每次会话都浪费你时间的失败模式。
就是这么简单。
不是插件。不是框架。不是 API 集成。就是一个文件夹里的 markdown 文件。
当 Claude 遇到与技能描述相匹配的任务时，它会自动加载该技能并按照说明执行。你不需要手动调用它。你不需要写提示词。技能会在相关时机自动触发。
技能 vs 命令 vs 智能体：
- 命令（commands）需要你输入 /command-name 才会执行。它们是手动触发的。
- 智能体（agents）是在自己独立上下文窗口中运行的专用子智能体角色。
- 技能（skills）会监视对话，当任务匹配时自动激活。它们是自动的。
这个区别很重要。命令是按钮。智能体是专家。技能是本能。
## 2：SKILL.md 的结构
每个技能都存放在自己的目录中，以一个 SKILL.md 文件作为入口。
SKILL.md 有两部分：前置元数据（frontmatter）和指令说明。
```
---
name: security-review
description: Comprehensive security audit. Use when reviewing
code for vulnerabilities, before deployments, or when the
user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:
1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication gaps
Report findings with severity ratings and specific fixes.
Reference @DETAILED_GUIDE.md for our security standards.
```
描述字段至关重要。Claude 通过阅读它来决定是否激活该技能。如果描述太模糊（“协助编码”），技能就会触发得过于频繁。如果描述太窄（“仅适用于 Python 3.11 的 FastAPI 处理器”），它就永远不会触发。
最佳平衡点：描述触发条件，而不是技能本身。“在审查代码漏洞时使用”比“安全审查工具”效果更好。
## 3：5 分钟做出你的第一个技能
我们来实际做一个。现在就开始。
对新手最有用的技能：一个代码审查技能，用于检查你的团队实际存在的问题。
第 1 步：创建目录。
```
mkdir -p .claude/skills/code-review
```
第 2 步：编写 SKILL.md。
```
---
name: code-review
description: Expert code reviewer. Use PROACTIVELY when
reviewing PRs, checking for bugs, or before merging.
allowed-tools: Read, Grep, Glob
---
You are a senior code reviewer focused on correctness.
When reviewing code:
- Flag bugs, not style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only at scale
Output format:
## Critical (must fix)
## Warnings (should fix)
## Notes (consider)
```
第 3 步：重启 Claude Code 或开启一个新会话。
第 4 步：让 Claude 审查一些代码。它会自动加载这个技能。
这就是一个可用的技能了。总耗时：不到 5 分钟。
## 4：自动触发（神奇的部分）
这正是技能变得强大的地方。
Claude 会阅读前置元数据中的 description 字段，并根据当前任务决定是否激活该技能。你永远不需要输入 /code-review。Claude 看到你在处理 PR 时，就会因为描述匹配而加载该技能。
如何控制技能的触发时机：
让描述更具体。“在用户要求审查 pull request 或在合并前检查代码时使用”会在 PR 审查时触发。“用于代码”则什么都会触发。
allowed-tools 字段限制了技能能做的事情。安全审查技能应该只能 Read、Grep 和 Glob——它不应该 Write 或 Edit 文件。这是你的安全保障。
路径范围激活。在前置元数据中添加一个 paths 字段：
```
---
paths:
- "src/api/**/*.ts"
- "src/handlers/**/*.ts"
---
```
现在，该技能只在 Claude 处理匹配这些模式的文件时激活。一个只对 API 文件触发的 API 规范技能。一个只对测试文件触发的测试标准技能。
## 5：添加模板和辅助文件
技能可以捆绑辅助文件。这正是它们成为“软件包”而不仅仅是提示词的原因。
```
.claude/skills/security-review/
├── SKILL.md
├── DETAILED_GUIDE.md # referenced with @
├── templates/
│ └── security-report.md # output template
└── examples/
└── good-review.md # example output
```
在技能指令中用 @FILENAME.md 来引用文件。技能激活时 Claude 会加载它们。
什么时候应该添加辅助文件：
- 技能需要一份详细的指南，但那会让 SKILL.md 过于臃肿
- 你想要一个一致的输出模板
- 你有示例输出，可以展示“好的输出长什么样”
什么时候不需要：如果 SKILL.md 在 50 行以内，你可能不需要辅助文件。保持简单。
## 6：新手入门的 5 种技能类型
不要在第一天就尝试构建复杂的多文件技能。从下面这些开始。
1. 审查技能。检查代码中的特定问题。就是上面的例子。最容易构建，即时价值最高。
2. 调试技能。在 Claude 开始猜测之前强制执行一套方法论。“复现 → 隔离 → 假设 → 验证”可以避免“猜测并应用”的循环，防止产生新 bug。
3. 文档技能。按照你团队的格式生成文档。给它一个模板，让它来填写。无需手动操作即可保持一致性。
4. 测试优先技能。强制 Claude 先写测试再写实现。逆转“先写代码，然后补写注定通过的测试”的默认行为。
5. 部署技能。运行你的部署清单。版本号更新、变更日志、构建、测试、打标签、推送。将你总是手动执行的流程自动化。
从最匹配你日常最大痛点的那个开始。今晚就安装一个。
## 7：浪费你时间的错误
错误 1：描述过于宽泛。“帮助编程”什么都匹配，会给每个会话增加噪音。触发条件要具体。
错误 2：指令太多。一个 200 行的 SKILL.md 会消耗上下文却不能带来相应的价值。如果 50 行写不完，就把它拆成 SKILL.md 和一个 @DETAILED_GUIDE.md。
错误 3：没有示例。Claude 遵循示例的效果比遵循规则更好。如果你想要特定的输出格式，直接展示出来——不要只是描述。
错误 4：跳过 allowed-tools。没有工具限制，一个技能可以读取、写入、编辑和执行任何东西。务必只指定所需的最少工具。
错误 5：在单文件技能还没弄好之前就构建多文件技能。先掌握基础。只有当简单版本失效时才增加复杂度。
## 你现在可以构建一个技能了
我学到的最重要一点：技能不是代码。它是用 Markdown 写成的行为契约。你把触发条件、指令和输出格式定义得越好，Claude 的交付就越可靠。
从一个技能开始。在 5 个真实任务上测试它。改进一个地方。然后构建下一个。
个人技能放在 ~/.claude/skills/（在所有项目中可用）。项目技能放在 .claude/skills/（通过 git 与团队共享）。
技能市场有 8 万多个条目。但你自己写的那个——针对你的特定工作流、你的特定坑、你的特定团队——永远会比通用的下载版本表现更好。
Claude 反复出错、而一个 20 行的技能就能修复的任务是什么？
## 相关链接
- [Nyk](https://x.com/nyk_builderz)
- [@nyk_builderz](https://x.com/nyk_builderz)
- [@FILENAME](https://x.com/@FILENAME)
- [@DETAILED_GUIDE](https://x.com/@DETAILED_GUIDE)
- [升级到 Premium](https://x.com/i/premium_sign_up)
- [2026年4月26日 凌晨3:01](https://x.com/nyk_builderz/status/2048115264680829238)
- [3,037 次浏览](https://x.com/nyk_builderz/status/2048115264680829238/analytics)
---
*导出时间: 2026/4/26 12:08:23*
