Skill Builder

Skill Builder - Complete Guide

This skill provides comprehensive guidance for building skills following Anthropic's Agent Skills specification. Use this skill whenever you need to create a new skill or improve an existing one.

Table of Contents

1. Understanding Skills
2. Planning & Design
3. Technical Requirements
4. Writing the Skill
5. Testing & Iteration
6. Distribution
7. Patterns
8. Troubleshooting

Understanding Skills

What is a Skill?

A skill is a folder containing:

• SKILL.md (required): Instructions in Markdown with YAML frontmatter
• scripts/ (optional): Executable code (Python, Bash, etc.)
• references/ (optional): Documentation loaded as needed
• assets/ (optional): Templates, fonts, icons used in output

Core Design Principles

Progressive Disclosure

Skills use a three-level system:

1. First level (YAML frontmatter): Always loaded in Claude's system prompt. Provides just enough information for Claude to know when each skill should be used without loading all of it into context.

2. Second level (SKILL.md body): Loaded when Claude thinks the skill is relevant to the current task. Contains the full instructions and guidance.

3. Third level (Linked files): Additional files bundled within the skill directory that Claude can choose to navigate and discover only as needed.

Composability

Claude can load multiple skills simultaneously. Your skill should work well alongside others, not assume it's the only capability available.

Portability

Skills work identically across Claude.ai, Claude Code, and API. Create a skill once and it works across all surfaces without modification.

Planning & Design

Start with Use Cases

Before writing any code, identify 2-3 concrete use cases your skill should enable.

Good Use Case Definition:

Use Case: Project Sprint Planning
Trigger: User says "help me plan this sprint" or "create sprint tasks"
Steps:
1. Fetch current project status from Linear (via MCP)
2. Analyze team velocity and capacity
3. Suggest task prioritization
4. Create tasks in Linear with proper labels and estimates
Result: Fully planned sprint with tasks created

Ask yourself:

• What does a user want to accomplish?
• What multi-step workflows does this require?
• Which tools are needed (built-in or MCP)?
• What domain knowledge or best practices should be embedded?

Common Skill Use Case Categories

Category 1: Document & Asset Creation

Used for: Creating consistent, high-quality output including documents, presentations, apps, designs, code, etc.

Key techniques:

• Embedded style guides and brand standards
• Template structures for consistent output
• Quality checklists before finalizing
• No external tools required - uses Claude's built-in capabilities

Category 2: Workflow Automation

Used for: Multi-step processes that benefit from consistent methodology, including coordination across multiple MCP servers.

Key techniques:

• Step-by-step workflow with validation gates
• Templates for common structures
• Built-in review and improvement suggestions
• Iterative refinement loops

Category 3: MCP Enhancement

Used for: Workflow guidance to enhance the tool access an MCP server provides.

Key techniques:

• Coordinates multiple MCP calls in sequence
• Embeds domain expertise
• Provides context users would otherwise need to specify
• Error handling for common MCP issues

Define Success Criteria

How will you know your skill is working?

Quantitative metrics:

• Skill triggers on 90% of relevant queries
• Completes workflow in X tool calls
• 0 failed API calls per workflow

Qualitative metrics:

• Users don't need to prompt Claude about next steps
• Workflows complete without user correction
• Consistent results across sessions

Technical Requirements

File Structure

your-skill-name/
├── SKILL.md              # Required - main skill file
├── scripts/              # Optional - executable code
│   ├── process_data.py  # Example
│   └── validate.sh      # Example
├── references/           # Optional - documentation
│   ├── api-guide.md     # Example
│   └── examples/        # Example
└── assets/              # Optional - templates, etc.
    └── report-template.md # Example

Critical Rules

1. SKILL.md naming: Must be exactly SKILL.md (case-sensitive). No variations accepted (SKILL.MD, skill.md, etc.)

2. Skill folder naming: Use kebab-case: notion-project-setup

   • No spaces: Notion Project Setup ❌
   • No underscores: notion_project_setup ❌
   • No capitals: NotionProjectSetup ❌

3. No README.md: Don't include README.md inside your skill folder. All documentation goes in SKILL.md or references/

4. Security: Never include XML tags (< or >) in frontmatter

Writing the Skill

YAML Frontmatter - The Most Important Part

The YAML frontmatter is how Claude decides whether to load your skill. Get this right.

Minimal required format:

---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

Field Requirements

name (required):

• kebab-case only
• No spaces or capitals
• Should match folder name

description (required):

• MUST include BOTH:
  • What the skill does
  • When to use it (trigger conditions)
• Under 1024 characters
• No XML tags (< or >)
• Include specific tasks users might say
• Mention file types if relevant

license (optional):

• Use if making skill open source
• Common: MIT, Apache-2.0

compatibility (optional):

• 1-500 characters
• Indicates environment requirements

metadata (optional):

• Any custom key-value pairs
• Suggested: author, version, mcp-server

Examples of Good Descriptions

# Good - specific and actionable
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".

# Good - includes trigger phrases
description: Manages Linear project workflows including sprint planning, task creation, and status tracking. Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".

# Good - clear value proposition
description: End-to-end customer onboarding workflow for PayFlow. Handles account creation, payment setup, and subscription management. Use when user says "onboard new customer", "set up subscription", or "create PayFlow account".

Examples of Bad Descriptions

# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user triggers
description: Implements the Project entity model with hierarchical relationships.

Writing the Main Instructions

After the frontmatter, write the actual instructions in Markdown.

Recommended structure:

# Your Skill Name

## Instructions

### Step 1: [First Major Step]
Clear explanation of what happens.

Example:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]

Step 2: [Second Major Step]

... (Add more steps as needed)

Examples

Example 1: [common scenario]

User says: "[phrase user might say]" Actions:

1. [Action 1]
2. [Action 2] Result: [What happens]

Example 2: [another scenario]

...

Troubleshooting

Error: [Common error message]

Cause: [Why it happens] Solution: [How to fix]

### Best Practices for Instructions

1. **Be Specific and Actionable**

✅ Good: Run python scripts/validate.py --input {filename} to check data format. If validation fails, common issues include:

• Missing required fields (add them to the CSV)
• Invalid date formats (use YYYY-MM-DD)

❌ Bad: Validate the data before proceeding.

2. **Include Error Handling**

Common Issues

MCP Connection Failed

If you see "Connection refused":

1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Your Service] > Reconnect

3. **Reference Bundled Resources Clearly**

Before writing queries, consult references/api-patterns.md for:

• Rate limiting guidance
• Pagination patterns
• Error codes and handling

4. **Use Progressive Disclosure**
Keep SKILL.md focused on core instructions. Move detailed documentation to `references/` and link to it.

---

## Testing & Iteration

### Recommended Testing Approach

#### 1. Triggering Tests

Goal: Ensure your skill loads at the right times.

**Should trigger:**
- "Help me set up a new ProjectHub workspace"
- "I need to create a project in ProjectHub"
- "Initialize a ProjectHub project for Q4 planning"

**Should NOT trigger:**
- "What's the weather in San Francisco?"
- "Help me write Python code"
- "Create a spreadsheet" (unless skill handles spreadsheets)

#### 2. Functional Tests

Goal: Verify the skill produces correct outputs.

- Valid outputs generated
- API calls succeed
- Error handling works
- Edge cases covered

#### 3. Performance Comparison

Goal: Prove the skill improves results vs. baseline.

**Baseline comparison:**

Without skill:

• User provides instructions each time
• 15 back-and-forth messages
• 3 failed API calls requiring retry
• 12,000 tokens consumed

With skill:

• Automatic workflow execution
• 2 clarifying questions only
• 0 failed API calls
• 6,000 tokens consumed

### Iteration Based on Feedback

**Undertriggering signals:**
- Skill doesn't load when it should
- Users manually enabling it
- Support questions about when to use it

Solution: Add more detail and nuance to the description

**Overtriggering signals:**
- Skill loads for irrelevant queries
- Users disabling it
- Confusion about purpose

Solution: Add negative triggers, be more specific

**Execution issues:**
- Inconsistent results
- API call failures
- User corrections needed

Solution: Improve instructions, add error handling

---

## Distribution

### Hosting on GitHub

1. Create a public repository
2. Include clear README with installation instructions
3. Add example usage and screenshots
4. Document in your MCP documentation

### Recommended README Structure

```markdown
# [Skill Name]

[Brief description of what the skill does]

## Features

- Feature 1
- Feature 2
- Feature 3

## Prerequisites

- [Required tool/service]
- [API keys needed]

## Installation

1. Clone the repo or download ZIP
2. Upload to Claude.ai via Settings > Skills
3. Enable the skill

## Usage

[Example commands/queries]

## Configuration

[Environment variables, API keys, etc.]

Patterns

Pattern 1: Sequential Workflow Orchestration

Use when: Users need multi-step processes in a specific order.

### Workflow: Onboard New Customer

#### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

#### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification

#### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

#### Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template

Pattern 2: Multi-MCP Coordination

Use when: Workflows span multiple services.

### Phase 1: Design Export (Figma MCP)
1. Export design assets from Figma
2. Generate design specifications
3. Create asset manifest

### Phase 2: Asset Storage (Drive MCP)
1. Create project folder in Drive
2. Upload all assets
3. Generate shareable links

### Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks
3. Assign to engineering team

### Phase 4: Notification (Slack MCP)
1. Post handoff summary to #engineering
2. Include asset links and task references

Pattern 3: Iterative Refinement

Use when: Output quality improves with iteration.

### Iterative Report Creation

#### Initial Draft
1. Fetch data via MCP
2. Generate first draft report
3. Save to temporary file

#### Quality Check
1. Run validation script: `scripts/check_report.py`
2. Identify issues:
   - Missing sections
   - Inconsistent formatting
   - Data validation errors

#### Refinement Loop
1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met

#### Finalization
1. Apply final formatting
2. Generate summary
3. Save final version

Pattern 4: Context-Aware Tool Selection

Use when: Same outcome, different tools depending on context.

### Smart File Storage

#### Decision Tree
1. Check file type and size
2. Determine best storage location:
   - Large files (>10MB): Use cloud storage MCP
   - Collaborative docs: Use Notion/Docs MCP
   - Code files: Use GitHub MCP
   - Temporary files: Use local storage

#### Execute Storage
Based on decision:
- Call appropriate MCP tool
- Apply service-specific metadata
- Generate access link

#### Provide Context to User
Explain why that storage was chosen

Pattern 5: Domain-Specific Intelligence

Use when: Your skill adds specialized knowledge beyond tool access.

### Payment Processing with Compliance

#### Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
   - Check sanctions lists
   - Verify jurisdiction allowances
   - Assess risk level
3. Document compliance decision

#### Processing
IF compliance passed:
  - Call payment processing MCP tool
  - Apply appropriate fraud checks
  - Process transaction
ELSE:
  - Flag for review
  - Create compliance case

#### Audit Trail
- Log all compliance checks
- Record processing decisions
- Generate audit report

Troubleshooting

Skill Won't Upload

Error: "Could not find SKILL.md in uploaded folder"

• Cause: File not named exactly SKILL.md
• Solution: Rename to SKILL.md (case-sensitive)

Error: "Invalid frontmatter"

• Cause: YAML formatting issue
• Solution: Ensure proper --- delimiters and valid YAML

Error: "Invalid skill name"

• Cause: Name has spaces or capitals
• Solution: Use kebab-case only

Skill Doesn't Trigger

Symptom: Skill never loads automatically

Fix: Revise your description field. Quick checklist:

• Is it too generic? ("Helps with projects" won't work)
• Does it include trigger phrases users would actually say?
• Does it mention relevant file types if applicable?

Skill Triggers Too Often

Symptom: Skill loads for unrelated queries

Solutions:

1. Add negative triggers:

   description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).
   

2. Be more specific
3. Clarify scope

MCP Connection Issues

Symptom: Skill loads but MCP calls fail

Checklist:

1. Verify MCP server is connected
2. Check authentication (API keys valid, OAuth tokens refreshed)
3. Test MCP independently
4. Verify tool names

Instructions Not Followed

Symptom: Skill loads but Claude doesn't follow instructions

Common causes:

1. Instructions too verbose
2. Instructions buried (put critical instructions at the top)
3. Ambiguous language (be specific about validations)

Large Context Issues

Symptom: Skill seems slow or responses degraded

Solutions:

1. Optimize SKILL.md size - keep under 5,000 words
2. Move detailed docs to references/
3. Reduce enabled skills

Quick Checklist

Before you start:

• Identified 2-3 concrete use cases
• Tools identified (built-in or MCP)
• Reviewed best practices
• Planned folder structure

During development:

• Folder named in kebab-case
• SKILL.md file exists (exact spelling)
• YAML frontmatter has --- delimiters
• name field: kebab-case, no spaces, no capitals
• description includes WHAT and WHEN
• No XML tags (< >) anywhere
• Instructions are clear and actionable
• Error handling included
• Examples provided

Before upload:

• Tested triggering on obvious tasks
• Tested triggering on paraphrased requests
• Verified doesn't trigger on unrelated topics
• Functional tests pass
• Tool integration works (if applicable)

Resources

• Official Docs: https://docs.anthropic.com/en/docs/agentic-skills
• Skills Repository: https://github.com/anthropics/skills
• Community Forums: Claude Developers Discord

How to Use This Skill Builder

When someone asks you to create a skill:

1. Clarify the use case: What specific task should the skill handle?
2. Identify triggers: What phrases would trigger the skill?
3. Determine tools: What tools (MCP, built-in) are needed?
4. Map the workflow: Step-by-step process
5. Create structure: Use the template above
6. Write SKILL.md: Following all the rules
7. Add scripts: If executable code is needed
8. Test: Verify triggering and functionality
9. Iterate: Refine based on testing

Remember: A skill should be focused, not comprehensive. Start with one use case and expand later.

Advanced: Iterative Skill Development

This section provides a structured approach to creating and improving skills through iteration, based on Anthropic's skill-creator methodology.

The Core Loop

The skill development process follows this cycle:

1. Draft - Write initial skill based on user requirements
2. Test - Run test prompts with the skill
3. Review - Have user evaluate outputs qualitatively
4. Improve - Refine based on feedback
5. Repeat - Continue until satisfied

Step 1: Capture Intent

Start by understanding what the user wants:

1. What should this skill enable Claude to do?
2. When should this skill trigger? (what user phrases/contexts)
3. What's the expected output format?
4. Should we set up test cases to verify the skill works?

Key principle: Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them.

Step 2: Interview and Research

Proactively ask questions about:

• Edge cases
• Input/output formats
• Example files
• Success criteria
• Dependencies

Step 3: Write Test Cases

After writing the skill draft, create 2-3 realistic test prompts — the kind of thing a real user would actually say.

Save test cases to evals/evals.json:

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

Step 4: Running Test Cases

For each test case, spawn two subagents:

• With-skill run: The skill path pointing to your skill
• Baseline run: No skill at all (for new skills) or the old version (for improvements)

Organize results in iteration folders:

workspace/
└── iteration-1/
    ├── eval-0/
    │   ├── with_skill/outputs/
    │   └── without_skill/outputs/
    └── eval_metadata.json

Step 5: User Review Loop

Present results to the user for qualitative feedback. Focus on:

• Does the output match expectations?
• Are there any corrections needed?
• What's working well?

After receiving feedback, generalize from it — don't overfit to specific examples. The skill should work for many different prompts, not just your test cases.

Step 6: Description Optimization

The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill.

How Skill Triggering Works

Skills appear in Claude's available_skills list with their name + description. Claude decides whether to consult a skill based on that description.

Important: Claude only consults skills for tasks it can't easily handle on its own. Simple, one-step queries may not trigger a skill even if the description matches, because Claude can handle them directly with basic tools.

This means eval queries should be substantive enough that Claude would actually benefit from consulting a skill.

Creating Trigger Eval Queries

Create 20 eval queries — a mix of should-trigger and should-not-trigger:

Should-trigger (8-10):

• Different phrasings of the same intent
• Some formal, some casual
• Cases where user doesn't explicitly name the skill
• Uncommon use cases
• Cases where this skill competes with another but should win

Should-not-trigger (8-10):

• Near-misses: queries that share keywords but actually need something different
• Adjacent domains
• Ambiguous phrasing where naive keyword match would trigger but shouldn't

Bad examples:

• "Format this data" — too simple
• "Extract text from PDF" — too obvious

Good examples:

• "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage"

Include concrete details: file paths, personal context, column names, company names, URLs.

Step 7: Improving the Skill

When refining based on feedback:

1. Generalize from the feedback — don't overfit to specific examples
2. Keep the prompt lean — remove things that aren't pulling their weight
3. Explain the why — try to explain the reasoning behind instructions
4. Look for repeated work — if all test cases did similar things, bundle that into scripts/

Writing Style Guidelines

From the Anthropic skill-creator:

Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples.

• Avoid overuse of "MUST" or "NEVER" — these are yellow flags
• Use imperative form in instructions
• Include examples formatted like:

**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

Quality Indicators

Undertriggering signals:

• Skill doesn't load when it should
• Users manually enabling it

Overtriggering signals:

• Skill loads for irrelevant queries
• Users disabling it

Execution issues:

• Inconsistent results
• API call failures
• User corrections needed

Additional Patterns

Pattern: Multi-Domain Support

When a skill supports multiple domains/frameworks, organize by variant:

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude reads only the relevant reference file based on context.

Pattern: Progressive Disclosure for Large Skills

If SKILL.md approaches 500 lines, add an additional layer of hierarchy:

• Keep core workflow in SKILL.md
• Move detailed documentation to references/
• Include clear pointers about where to go next

Pattern: Bundling Common Scripts

Read transcripts from test runs and notice if subagents all wrote similar helper scripts. If so, write it once, put it in scripts/, and tell the skill to use it. This saves every future invocation from reinventing the wheel.

Reference

• Agent Skills Spec: https://agentskills.io/specification
• Anthropic Skills Repo: https://github.com/anthropics/skills
• Official Documentation: https://docs.anthropic.com/en/docs/agentic-skills