Here is how to create Claude Skills, from the first SKILL.md to installing the skill in Claude.ai or Claude Code and testing that it triggers.
In Part 1 of this series - “An Intro to Claude Skills and How It’s Different” - we covered the fundamentals:
What Claude Skills are and how progressive disclosure works
The critical differences between Skills, Projects, MCP, and Custom Instructions
A decision framework for when to use each tool
Why Skills represent a fundamental shift in AI customization
If you haven’t read Part 1 yet, I highly recommend starting there to understand the concepts we’ll be building on.
Now that you understand what Skills are and why they matter, it’s time to get hands-on. In this guide, we’ll actually build Skills together, explore real-world use cases, and give you the practical knowledge to start creating your own AI expertise library.
What we’ll cover in this post:
Creating your first Skill step-by-step (Code Review Skill example)
Adding executable scripts for deterministic operations
Real-world Skills I use as a CTO
Industry examples from companies using Skills in production
Advanced patterns and best practices
Common pitfalls and debugging strategies
Your week-by-week action plan
Let’s build.
If you only want the steps, here they are. The rest of the guide explains each one.
Create a folder named after the skill, for example code-review/. In Claude Code the folder name becomes the command name.
Inside it, create SKILL.md. Start with YAML frontmatter containing a name (64 characters maximum) and a description (200 characters maximum). Claude reads the description to decide when to load the skill, so write it as the situations that should trigger it, not as a slogan.
Below the frontmatter, write the instructions in Markdown: when to use the skill, the standards to apply, and the output format. Put long reference material in separate files in the same folder and link to them from SKILL.md, so Claude loads them only when needed.
Add scripts under scripts/ if a step needs a deterministic result, such as a complexity check.
Install it. Where you put the folder depends on which Claude you are using:
Claude.ai and the desktop app: zip the folder (the skill folder must be the root of the zip), upload it, then enable it under Customize, then Skills.
Claude Code: no upload. Save the folder as .claude/skills/code-review/ inside the repository for a project skill, or ~/.claude/skills/code-review/ for a personal skill available in every project.
/code-review. Then try a fresh session with the skill disabled and compare the two outputs. If the skill did not help, the instructions need work.
Now, the full walk-through.
Let’s build something real. I’ll show you how to create a “Code Review Skill” that enforces your team’s standards.
Every skill needs just one required file: SKILL.md
Here’s the basic structure:
---
name: code-review
description: Review code following team standards, catching common issues and suggesting improvements
---
## When to Use This Skill
Activate this skill when the user asks to:
- Review code for quality, security, or performance
- Check pull requests
- Identify anti-patterns or bugs
- Suggest code improvements
## Our Code Standards
### TypeScript/JavaScript
- Use explicit return types for functions
- Prefer const over let, never use var
- Use meaningful variable names (no single letters except loop counters)
- Max function length: 50 lines
- Max file length: 300 lines
### Python
- Follow PEP 8 strictly
- Use type hints for function signatures
- Docstrings required for all public functions
- Max function complexity: 10 (McCabe)
### General Principles
- DRY: Don’t Repeat Yourself
- Single Responsibility: Each function does one thing
- Boy Scout Rule: Leave code better than you found it
## Common Anti-Patterns to Flag
1. **God Objects**: Classes that do too much
2. **Magic Numbers**: Unexplained constants
3. **Premature Optimization**: Over-engineering simple solutions
4. **Callback Hell**: Deeply nested callbacks (use async/await)
5. **Swallowed Exceptions**: Empty catch blocks
## Review Checklist
For each code review, check:
- [ ] Code follows language-specific standards above
- [ ] Functions have clear, single purposes
- [ ] No obvious security issues (SQL injection, XSS, etc.)
- [ ] Error handling is appropriate
- [ ] Tests would be easy to write for this code
- [ ] Code is self-documenting or has necessary comments
## Output Format
Structure your review as:
**Summary**: Brief overview (2-3 sentences)
**Critical Issues**: Security or correctness problems (if any)
**Improvements**: Specific suggestions with line numbers
**Positive Notes**: What’s done well (always include this!)
**Priority**: High/Medium/Low for addressing the issues
## Examples
### Good Review Example
**Summary**: Clean implementation of user authentication with proper validation and error handling.
**Critical Issues**: None
**Improvements**:
- Line 45: Consider extracting email validation to a separate utility
- Line 78: Add rate limiting to prevent brute force attacks
**Positive Notes**: Excellent use of TypeScript types, clear separation of concerns, good test coverage.
**Priority**: Medium (suggestions are enhancements, not blockers)
Method 1: Manual Creation in Claude.ai
Create a folder: code-review/. The folder name should match the name in the frontmatter.
Inside it, create SKILL.md with the content above
Zip the folder so that the skill folder is the root of the archive, not nested inside another folder
In Claude.ai, upload the zip and enable the skill under Customize, then Skills. Anthropic's custom skills guide has the current screenshots; this menu has moved once already since Skills launched.
Skills need code execution enabled in your Claude.ai settings. If the upload option is missing, check that first.
Method 1b: Manual Creation in Claude Code
Claude Code reads skills from disk, so there is nothing to upload:
Create .claude/skills/code-review/SKILL.md in the repository (project skill, shared with everyone who clones it) or ~/.claude/skills/code-review/SKILL.md (personal skill, every project on your machine)
Start a session and type /code-review to run it directly, or ask for a review and let Claude pick it up from the description
The frontmatter format is the same, so one folder can serve both. The Claude Code skills reference lists extra frontmatter fields that only apply there, such as pre-approving tools.
Method 2: Use the skill-creator Skill (Recommended)
This is meta, but it works brilliantly. The skill-creator is a pre-installed Skill that helps you create new Skills:
In Claude.ai, enable the “skill-creator” skill (it’s pre-installed)
Say: “I want to create a code review skill”
Claude will interview you about your requirements
It generates the folder structure and SKILL.md file
It even bundles resources you might need
The skill-creator asks questions like:
“What’s the primary purpose of this skill?”
“What specific workflows should it support?”
“Do you need any executable scripts?”
“What format should outputs follow?”
Then it creates everything for you. It’s like using an AI to teach an AI how to help you better.
Skills can include scripts for deterministic operations. Here’s an example for the code review skill:
Create code-review-skill/scripts/complexity_checker.py:
#!/usr/bin/env python3
“”“
Check code complexity metrics
“”“
import sys
import ast
def calculate_complexity(code: str) -> dict:
“”“Calculate McCabe complexity and other metrics”“”
try:
tree = ast.parse(code)
stats = {
‘functions’: 0,
‘classes’: 0,
‘lines’: len(code.split(’\n’)),
‘complexity’: 0
}
for node in ast.walk(tree):
if isinstance(node, ast.FunctionDef):
stats[’functions’] += 1
complexity = 1 # Base complexity
for subnode in ast.walk(node):
if isinstance(subnode, (ast.If, ast.While, ast.For,
ast.ExceptHandler, ast.With)):
complexity += 1
stats[’complexity’] = max(stats[’complexity’], complexity)
elif isinstance(node, ast.ClassDef):
stats[’classes’] += 1
return stats
except Exception as e:
return {’error’: str(e)}
if __name__ == ‘__main__’:
if len(sys.argv) < 2:
print(”Usage: complexity_checker.py <file_path>”)
sys.exit(1)
with open(sys.argv[1], ‘r’) as f:
code = f.read()
results = calculate_complexity(code)
print(f”Functions: {results.get(’functions’, 0)}”)
print(f”Classes: {results.get(’classes’, 0)}”)
print(f”Lines: {results.get(’lines’, 0)}”)
print(f”Max Complexity: {results.get(’complexity’, 0)}”)
Update your SKILL.md to reference it:
## Tools Available
This skill includes a complexity checker script. Claude can run:
`python scripts/complexity_checker.py <file_path>`
to get objective complexity metrics before reviewing.
Now Claude can automatically run complexity analysis without you asking, and without the entire script into context.
The most common problem with a first skill is that it never activates. Work through these in order:
Is it enabled? In Claude.ai, check Customize, then Skills. In Claude Code, check the folder path and that the file is named exactly SKILL.md.
Does the description match how you ask? Claude only sees the description until it decides to load the skill. A description that says “Review code following team standards” will not fire for “look at this PR”. Add the phrasings you actually use.
Is the frontmatter valid? A missing closing --- or a description over 200 characters is enough to break .
Force it once. In Claude Code, invoke the skill with /code-review to confirm the instructions work when loaded. If the output is right, the problem is activation, not content, and the fix is the description.
Let me share some Skills I’ve built and how they’ve changed my workflow:
Problem: Every time I designed a new system, I’d have to remember our documentation template, what diagrams to include, what sections to cover.
Solution: Created a skill that knows:
Our architecture doc template (intro, requirements, constraints, options, decision, consequences)
When to create sequence diagrams vs. architecture diagrams
How to document trade-offs in our style
Our specific Mermaid diagram conventions
Impact: Architecture docs that used to take 2 hours now take 30 minutes, and they’re consistently formatted.
Problem: Creating Jira tickets with proper structure, acceptance criteria, and labels was tedious.
Solution: Skill that encodes:
Our ticket template (title format, description structure, acceptance criteria format)
Team conventions (when to add specific labels, how to estimate points)
Links to related documentation
A script to validate ticket structure before creation
Impact: Combined with MCP (Jira connection), I can now say “create tickets for this feature” and get properly structured, ready-to-assign tickets.
Problem: Needed consistency across interviewers for technical evaluations.
Solution: Skill containing:
Interview question bank by difficulty
Evaluation rubric
Follow-up questions based on candidate responses
How to give hints without giving away answers
Note-taking template
Impact: All interviewers now use the same framework, making candidate comparisons fair and feedback consistent.
Some real implementations from companies using Skills:
Rakuten (E-commerce Giant)
Created Skills for management accounting workflows
Automated finance operations that previously required manual coordination across departments
Result: Streamlined workflows, reduced processing time
Box (Enterprise Content Management)
Skills that transform stored files into presentations, spreadsheets, and Word documents
All outputs follow organizational standards automatically
Result: Hours saved on document creation, consistent branding
Financial Services Firms
Skills for Discounted Cash Flow (DCF) modeling
Comparable company analysis
Due diligence workflows
Initiating coverage reports
Result: Junior analyst work automated, consistent methodologies
Here’s how to dive into Skills effectively:
Enable Skills in Claude.ai under Customize, then Skills
Try the document creation skills (docx, pptx, xlsx, pdf)
Ask Claude to create a simple document to see Skills in action
Note: You’ll see Skills mentioned in Claude’s “thinking” as it works
Ask yourself:
What task do I repeat weekly that has specific rules?
What workflow requires consistency across my team?
What knowledge do I keep having to explain to Claude?
Good first Skills:
Email response templates for common scenarios
Report generation following your format
Code scaffolding for your tech stack
Meeting note structuring
Use the skill-creator skill to build your first custom skill
Test it thoroughly with variations of your typical requests
Refine the instructions based on what Claude misses
Share with a colleague for feedback
Create a complementary skill
Test how they work together automatically
Document what worked/didn’t work
Plan your next 3 skills
Wrong: “General writing skill” that covers emails, blogs, tweets, documentation, and reports
Right: Separate skills for each content type with specific guidelines
Why: Broad skills defeat the purpose of progressive disclosure. Claude loads the whole skill when any writing task comes up.
Problem: Your skill works for the happy path but fails when things get weird
Solution:
Test with incomplete inputs
Try contradictory requirements
See what happens when users ask questions the skill doesn’t anticipate
Problem: Including your entire company handbook in a single skill
Remember Claude only loads what it needs, but massive skills take longer to parse
Break large knowledge bases into focused skills
Use links to external docs for reference rather than including everything
Problem: Creating skills and never updating them as processes change
Version your skills (add version info to YAML frontmatter)
Set quarterly reviews
Track when skills give outdated advice
Update promptly when processes change
Once you’re comfortable with basic Skills, here are some advanced patterns:
Create skills that naturally work together:
data-extraction skill → pulls data from sources
data-analysis skill → analyzes extracted data
report-generation skill → formats analysis into reports
Claude automatically chains them when you say “analyze this data and create a report.”
Use clear conditionals in your skill instructions:
## Decision Logic
**If** the user is asking about production issues:
- Load emergency response procedures
- Include on-call rotation information
- Flag the urgency level
**If** the user is asking about development:
- Load coding standards
- Reference architecture docs
- Suggest testing approaches
Start simple, evolve based on usage:
Version 1: Basic instructions and examples\
Version 2: Add common edge cases you discovered\
Version 3: Include executable scripts for repeated computations\
Version 4: Add links to related skills for complex workflows
Track version history in your SKILL.md:
---
name: my-skill
description: Does something useful
version: 1.2.0
last_updated: 2025-11-02
---
## Changelog
- v1.2.0: Added script for automated validation
- v1.1.0: Expanded examples based on user feedback
- v1.0.0: Initial release
Before writing a skill, describe what you want in a normal conversation with Claude. Refine it over several chats. Once you have wording that works consistently, turn that into a skill.
When Claude uses a skill, you see it in the “thinking” section (if enabled). This shows:
Which skills were activated
What information was loaded
How skills interacted
This is invaluable for debugging and improving skills.
If one skill relies on another, document it:
## Related Skills
This skill works best when combined with:
- `data-validation` skill (for input checking)
- `report-formatting` skill (for output styling)
Claude should load these skills when using this one for comprehensive workflows.
## When NOT to Use This Skill
Don’t use this skill for:
- Quick calculations (use built-in math instead)
- Simple queries (this skill is for complex analysis only)
- Real-time data (use MCP connections for live data)
This helps Claude make better decisions about skill activation.
Keep a log of times when:
The skill didn’t activate when it should have
The skill activated incorrectly
The output wasn’t what you expected
Use this to refine the description and instructions.
The real magic happens when you combine Skills with MCP connections. Here’s a concrete example:
Setup:
MCP connection to your company’s PostgreSQL database
MCP connection to your Slack workspace
Skill: “Database Query Standards”
Skill: “Slack Message Formatting”
What you can do:
“Check yesterday’s sales numbers and post a summary to the [#sales] channel”
Claude:
Loads the Database Query Standards skill
Writes a query following your conventions
Executes it via MCP connection
Loads the Slack Message Formatting skill
Formats results according to team style
Posts via MCP to Slack
All of this happens automatically, consistently, following your standards.
Skills will evolve. Here’s how to build them for longevity:
version: 2.1.3
## Assumptions
This skill assumes:
- Python 3.9+ is available
- User has basic understanding of financial models
- Data is in CSV format with headers
- Date format is YYYY-MM-DD
## Deprecation Notice
**Status**: Active (will be deprecated 2026-03-01)
**Replacement**: Use `advanced-analysis-v2` skill instead
**Migration**: [Link to migration guide]
One skill, one purpose. Don’t try to make a skill that does everything. It’s easier to maintain five focused skills than one mega-skill.
If you’re still reading, you’re probably convinced that Skills are worth exploring. Here’s my opinionated take on getting started:
Start with: A code generation skill for your stack
Include your team’s conventions
Add linting rules
Include common patterns
Add a script to validate generated code
Then build: A PR review skill
Your review checklist
Common issues in your codebase
How to give constructive feedback
Auto-generated review comments format
Advanced: A deployment verification skill
Pre-deployment checklist
Post-deployment verification steps
Rollback procedures
Incident response templates
Start with: Content formatting skill
Your brand voice guidelines
Content structure templates
SEO best practices specific to your niche
CTAs that work for your audience
Then build: Research synthesis skill
How you organize research notes
Citation formats you prefer
Insight extraction methods
Content ideation from research
Advanced: Multi-platform adaptation skill
Blog post → Twitter thread converter
Twitter thread → LinkedIn post adapter
Long-form → Newsletter snippet generator
Start with: Meeting notes skill
Your meeting note template
Action item formatting
Who gets which type of follow-up
Integration with your project management
Then build: Report generation skill
Company report templates
KPI calculations
Visualization preferences
Distribution formatting
Advanced: Process documentation skill
SOP template
Process mapping conventions
Troubleshooting flowcharts
Training material generation
We’re at the very beginning of the Skills era. Right now (November 2025), Skills are:
Two weeks old
Understood by few
Used by fewer
Mastered by almost none
This is your opportunity.
In six months, there will be Skills for everything. There will be best practices, design patterns, and entire ecosystems. Companies will have libraries of organizational Skills. Freelancers will specialize in Skill creation. Courses will teach “Skills Engineering.”
But right now? It’s wide open.
The people who start building Skills today will be the experts everyone learns from tomorrow. The companies that encode their processes into Skills now will have a significant advantage over competitors who wait.
This isn’t hype, it’s the logical evolution of how we work with AI. Skills turn one-off interactions into reusable expertise. They turn prompt engineering into knowledge engineering. They turn AI assistance into AI collaboration.
Today: Enable Skills in your Claude account, try the pre-built document skills
This week: Identify one repetitive task that has specific rules, use skill-creator to build your first custom skill
This month: Create three skills that work together, share them with a colleague or community
This quarter: Build a library of skills for your core workflows, measure the time saved
And when you do, I’d love to hear about it. What skills are you building? What’s working? What surprised you?
Because here’s the thing: Skills are so new that we’re all figuring this out together. Every experiment matters. Every insight contributes to the collective understanding.
The revolution isn’t coming. It’s here. And it’s wearing the humble disguise of a Markdown file in a folder.
Want to dive deeper? Check out Anthropic’s Skills GitHub repository for examples, or join the discussion on r/ClaudeAI.
Final Note: This guide will become outdated. Skills are evolving rapidly. I’ll update it as I learn more, and I encourage you to treat Skills as an experiment, not a doctrine. Try things. Break things. Share what you learn.
The best Skill you’ll ever create is the one you start building today.
Originally published on nulltensor.com.