# Skill Builder

> Comprehensive skill creation assistant. Use when user wants to create a new skill, build a skill from scratch, or improve an existing skill. Handles all aspects of skill development including planning, structure, YAML frontmatter, writing instructions, testing, and distribution. Follow this guide to create high-quality, production-ready skills.

- Skill: `ankitjh4/skill-builder` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ankitjh4/skill-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ankitjh4/skill-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ankitjh4 (https://skillmd.com/u/ankitjh4)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ankitjh4/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](#understanding-skills)
2. [Planning & Design](#planning--design)
3. [Technical Requirements](#technical-requirements)
4. [Writing the Skill](#writing-the-skill)
5. [Testing & Iteration](#testing--iteration)
6. [Distribution](#distribution)
7. [Patterns](#patterns)
8. [Troubleshooting](#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:**
```yaml
---
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

```yaml
# 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

```yaml
# 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:**
```markdown
# 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`:
```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:
```markdown
**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