# 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*