---

name: skill-builder description: Create new Claude Code skills with proper SKILL.md format, frontmatter, and best practices. Use when building, scaffolding, or generating a new skill for Claude Code. allowed-tools: Read, Write, Glob, Grep, Bash metadata: author: mineflayer-bedrock version: "1.0"

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

| Field | Constraints | Purpose | |-------|-------------|---------| | name | Max 64 chars, lowercase, hyphens only | Unique identifier (must match directory name) | | description | Max 200 chars, non-empty | Critical - Claude uses this to decide when to invoke |

Optional Fields

| Field | Purpose | Example | |-------|---------|---------| | license | License type | Apache-2.0, MIT | | allowed-tools | Pre-approved tools | Read, Write, Glob, Grep, Bash | | compatibility | Environment requirements | node >= 18, unix | | metadata | Custom key-value pairs | author: name, version: "1.0" |

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

| Folder | Purpose | Loading | |--------|---------|---------| | SKILL.md | Core instructions | Always (when skill activates) | | scripts/ | Repeatable automation | Executed on demand | | references/ | Extended documentation | Read into context on demand | | assets/ | Templates and resources | Used for output generation |

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

| Feature | Skills | MCP Servers | |---------|--------|-------------| | Purpose | How to do something | Access to something | | Contains | Instructions, templates | Tools, resources | | Loading | On-demand (progressive) | Upfront | | Best for | Workflows, standards | Data access, APIs |

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

| Resource | URL | |----------|-----| | Skills Overview | https://code.claude.com/docs/en/skills | | Creating Skills | https://support.claude.com/en/articles/12512198 | | Agent Skills Spec | https://github.com/anthropics/skills/blob/main/agent_skills_spec.md | | Template Skill | https://github.com/anthropics/skills/tree/main/template-skill | | Best Practices | https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills |

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