How to Create Your Own SKILL.md File from Scratch
A SKILL.md file tells AI agents exactly what your skill does and how to use it. You'll build one from scratch in minutes, not hours.
Start with frontmatter that matters
Every SKILL.md file begins with YAML frontmatter. This metadata helps agents understand your skill before reading the full instructions.
---
name: "code-reviewer"
description: "Reviews code for bugs, performance issues, and style problems"
version: "1.0.0"
author: "Your Name"
triggers:
- "review this code"
- "check for bugs"
- "code quality"
requirements:
- "Access to file system"
- "Code analysis tools"
---
The name field becomes your skill's identifier. Use lowercase with hyphens, not spaces or underscores. The triggers array lists phrases that should activate your skill. Think about how developers actually talk. They say "review this code" more often than "perform code analysis."
Requirements tell agents what they need to execute your skill. Be specific. "File system access" is better than "system permissions."
Write instructions that work
After the frontmatter, write clear instructions. Start with what the skill does, then explain how to use it.
## What this skill does
Reviews code files for common issues including bugs, performance problems,
style violations, and security concerns. Returns a structured report with
specific line numbers and fix suggestions.
## How to use it
1. Provide the code file path or paste code directly
2. Specify the programming language if not obvious from file extension
3. Mention any specific concerns (performance, security, style)
Your instructions should answer: what happens when someone triggers this skill? What input do they need to provide? What output should they expect?
Skip the marketing language. Developers want to know if your skill solves their problem, not whether it's "innovative" or "cutting-edge."
Add concrete examples
Examples make your skill instantly usable. Show real inputs and expected outputs.
## Examples
**Basic usage:**
"Review this Python function for bugs"
```python
def calculate_average(numbers):
return sum(numbers) / len(numbers)
With specific focus: "Check this JavaScript for performance issues"
for (let i = 0; i < items.length; i++) {
document.getElementById('list').innerHTML += items[i];
}
Good examples show variety. Include simple cases and complex ones. Show different input formats. If your skill works with files, show file paths. If it works with URLs, include real URLs.
The [SKILL.md spec](/specs/skill-md) defines exactly which fields are required versus optional. Following it ensures your skill works across different AI agents.
## Handle edge cases upfront
Your skill will receive unexpected inputs. Plan for them in your instructions.
```markdown
## Error handling
If no code is provided, ask the user to share code or specify a file path.
If the file type is unsupported, list supported languages: Python, JavaScript,
TypeScript, Go, Rust, Java, C++.
If code is too large (>1000 lines), offer to review specific functions or
classes instead of the entire file.
This prevents your skill from breaking when someone provides bad input. It also sets clear expectations about limitations.
Test across different agents
Your SKILL.md file needs to work with Claude, ChatGPT, and other AI systems. Each interprets instructions slightly differently.
Create a test file with your skill and run it through different agents. Ask them to trigger your skill with the same input. Compare outputs. If one agent consistently misunderstands your instructions, revise them.
The create a skill guide covers testing in detail, including automated testing approaches.
Structure for scanning
Agents scan your SKILL.md file quickly. Use clear headings and short paragraphs. Break up walls of text.
## Input formats
**File paths:** `/path/to/file.py`
**Inline code:** Wrapped in code blocks
**GitHub URLs:** `https://github.com/user/repo/blob/main/file.js`
## Output format
Returns markdown with:
- Issue severity (High/Medium/Low)
- Line numbers where issues occur
- Specific fix recommendations
- Code examples showing corrections
Notice how this scans easily. Agents can quickly find what input formats work and what output to expect.
Link to related skills
Your skill probably relates to others in the skills library. Mention them when relevant.
## Related skills
Works well with:
- `code-formatter` for style fixes
- `security-scanner` for detailed security analysis
- `performance-profiler` for runtime optimization
This helps users discover complementary tools. It also shows you understand the broader ecosystem.
Version and maintain
Add version numbers to track changes. When you update your skill, increment the version in the frontmatter.
version: "1.2.0"
changelog:
- "1.2.0: Added support for TypeScript files"
- "1.1.0: Improved error messages for unsupported languages"
- "1.0.0: Initial release"
Keep a changelog so users know what changed. This matters more than you think. Developers get frustrated when skills silently change behavior.
Your finished SKILL.md file should be 200-500 words for simple skills, longer for complex ones. The best practices guide covers optimization techniques for different skill types.
Deploy and iterate
Upload your SKILL.md file to test it immediately. Real usage reveals problems that theoretical testing misses.
Watch how people actually use your skill. Do they trigger it differently than you expected? Do they ask for outputs you didn't plan for? Update your file based on real feedback.
The difference between a working skill and a great one is iteration. Start with something functional, then refine based on how developers actually use it.
Your SKILL.md file is now ready. It has clear metadata, specific instructions, concrete examples, and handles edge cases. Most importantly, it solves a real problem that developers face.
