Skill Builder

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

---
name: your-skill-name
description: Clear description of what this skill does (max 200 chars). Include trigger keywords users would naturally say.
allowed-tools: Read, Write, Glob, Grep, Bash
metadata:
  author: your-name
  version: "1.0"
---

# Your Skill Name

Brief overview of the skill's purpose.

## When to use

- Trigger condition 1
- Trigger condition 2
- Trigger condition 3

## When NOT to use

- Exclusion condition 1
- Exclusion condition 2

## Instructions

Step-by-step guidance for completing the workflow:

1. **First step**: Description
2. **Second step**: Description
3. **Third step**: Description

## Examples

### Example 1: [Scenario Name]

**Input**: User says "..."

**Output**: Claude does...

## Common mistakes to avoid

- Mistake 1 and how to prevent it
- Mistake 2 and how to prevent it

## References

| Resource | Location |
|----------|----------|
| Documentation | `references/docs.md` |
| 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:

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

Good:

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

Bad:

description: Helps with PDFs.

Bad:

description: 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

---
name: code-review
description: Review code for bugs, security issues, and best practices. Use when reviewing PRs, checking code quality, or auditing implementations.
allowed-tools: Read, Glob, Grep
metadata:
  author: team
  version: "1.0"
---

# Code Review

Systematic code review following team standards.

## When to use

- Reviewing pull requests
- Checking code before commit
- Auditing security-sensitive code
- Evaluating code quality

## When NOT to use

- Simple typo fixes (just fix them)
- Understanding code (use exploration instead)
- Writing new code (use appropriate coding skill)

## Review Checklist

### Security
- [ ] No hardcoded secrets
- [ ] Input validation present
- [ ] SQL injection prevention
- [ ] XSS prevention

### Code Quality
- [ ] Functions under 50 lines
- [ ] Clear naming conventions
- [ ] Error handling present
- [ ] No dead code

### Testing
- [ ] Unit tests for new functions
- [ ] Edge cases covered
- [ ] Integration tests if needed

## Output Format

Provide findings as:

| Severity | File:Line | Issue | Suggestion |
|----------|-----------|-------|------------|
| High | src/auth.ts:42 | Hardcoded API key | Use env variable |
| Medium | src/user.ts:15 | Missing null check | Add optional chaining |

Documentation Links

Common Patterns

Workflow Skill

For multi-step processes:

## Workflow

1. **Gather**: Collect required information
2. **Validate**: Check prerequisites
3. **Execute**: Perform main action
4. **Verify**: Confirm success

Template Skill

For generating files:

## Template Usage

1. Copy template from `assets/template.ext`
2. Replace placeholders: `{{name}}`, `{{date}}`
3. Save to destination

Integration Skill

For connecting services:

## Integration Steps

1. Check MCP server is connected
2. Authenticate if needed
3. Call required endpoints
4. Transform response