Claude Code Skill Builder

Create well-structured Claude Code skills that follow best practices and the Agent Skills specification.

Quick Start

1. Choose skill location: Project (.claude/skills/) or Personal (~/.claude/skills/)
2. Create directory: {location}/{skill-name}/
3. Generate SKILL.md using template below
4. Add supporting files (scripts, references, assets) as needed
5. Test the skill by asking Claude to perform matching tasks

SKILL.md Template

Create file at: {location}/{skill-name}/SKILL.md

markdown
1---
2name: your-skill-name
3description: Clear description of what this skill does (max 200 chars). Include trigger keywords users would naturally say.
4allowed-tools: Read, Write, Glob, Grep, Bash
5metadata:
6  author: your-name
7  version: "1.0"
8---
9
10# Your Skill Name
11
12Brief overview of the skill's purpose.
13
14## When to use
15
16- Trigger condition 1
17- Trigger condition 2
18- Trigger condition 3
19
20## When NOT to use
21
22- Exclusion condition 1
23- Exclusion condition 2
24
25## Instructions
26
27Step-by-step guidance for completing the workflow:
28
291. **First step**: Description
302. **Second step**: Description
313. **Third step**: Description
32
33## Examples
34
35### Example 1: [Scenario Name]
36
37**Input**: User says "..."
38
39**Output**: Claude does...
40
41## Common mistakes to avoid
42
43- Mistake 1 and how to prevent it
44- Mistake 2 and how to prevent it
45
46## References
47
48| Resource | Location |
49|----------|----------|
50| Documentation | `references/docs.md` |
51| API Reference | `references/api.md` |

Frontmatter Reference

Required Fields

Optional Fields

Directory Structure

skill-name/
├── SKILL.md           # Required - Core instructions (<500 lines)
├── scripts/           # Optional - Executable code (Python/Bash)
│   └── helper.py
├── references/        # Optional - Documentation loaded into context
│   ├── api.md
│   └── schema.md
└── assets/            # Optional - Templates, config files
    └── template.json

File Purposes

Writing Effective Descriptions

The description is critical - it determines whether Claude activates your skill.

Good Description Pattern

[What it does] + [When to use it with trigger keywords]

Examples

Good:

yaml
1description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs, forms, or document extraction.

Good:

yaml
1description: Generate TypeScript API clients from OpenAPI specs. Use when creating SDK, API wrapper, or client code from swagger/openapi files.

Bad:

yaml
1description: Helps with PDFs.

Bad:

yaml
1description: A utility for API work.

Best Practices

Keep SKILL.md Concise

• Target under 500 lines (~5,000 tokens)
• Move detailed documentation to references/
• Use tables and bullet points over prose

Define Clear Boundaries

Always include both:

• When to use: Positive triggers
• When NOT to use: Negative boundaries to prevent over-activation

Use Relative Paths

Reference files using paths relative to skill root:

• scripts/extract.py
• references/api-docs.md
• assets/template.html

Security

• Never hardcode secrets, API keys, or passwords
• Audit scripts from untrusted sources
• Use environment variables for sensitive config

Skill vs MCP Server

A skill can orchestrate multiple MCP servers. Use skills for workflow logic and MCP for connectivity.

Testing Checklist

1. Directory name matches name in frontmatter
2. Description includes trigger keywords
3. SKILL.md under 500 lines
4. All file references use relative paths
5. When/When NOT sections are clear
6. Examples demonstrate expected behavior
7. Restart Claude Code to load new skill
8. Test with natural language matching description

Example: Complete Skill

code-review Skill

markdown
1---
2name: code-review
3description: Review code for bugs, security issues, and best practices. Use when reviewing PRs, checking code quality, or auditing implementations.
4allowed-tools: Read, Glob, Grep
5metadata:
6  author: team
7  version: "1.0"
8---
9
10# Code Review
11
12Systematic code review following team standards.
13
14## When to use
15
16- Reviewing pull requests
17- Checking code before commit
18- Auditing security-sensitive code
19- Evaluating code quality
20
21## When NOT to use
22
23- Simple typo fixes (just fix them)
24- Understanding code (use exploration instead)
25- Writing new code (use appropriate coding skill)
26
27## Review Checklist
28
29### Security
30- [ ] No hardcoded secrets
31- [ ] Input validation present
32- [ ] SQL injection prevention
33- [ ] XSS prevention
34
35### Code Quality
36- [ ] Functions under 50 lines
37- [ ] Clear naming conventions
38- [ ] Error handling present
39- [ ] No dead code
40
41### Testing
42- [ ] Unit tests for new functions
43- [ ] Edge cases covered
44- [ ] Integration tests if needed
45
46## Output Format
47
48Provide findings as:
49
50| Severity | File:Line | Issue | Suggestion |
51|----------|-----------|-------|------------|
52| High | src/auth.ts:42 | Hardcoded API key | Use env variable |
53| Medium | src/user.ts:15 | Missing null check | Add optional chaining |

Documentation Links

Common Patterns

Workflow Skill

For multi-step processes:

markdown
1## Workflow
2
31. **Gather**: Collect required information
42. **Validate**: Check prerequisites
53. **Execute**: Perform main action
64. **Verify**: Confirm success

Template Skill

For generating files:

markdown
1## Template Usage
2
31. Copy template from `assets/template.ext`
42. Replace placeholders: `{{name}}`, `{{date}}`
53. Save to destination

Integration Skill

For connecting services:

markdown
1## Integration Steps
2
31. Check MCP server is connected
42. Authenticate if needed
53. Call required endpoints
64. Transform response