Skill Builder

Claude Skill Builder

Skills are the primary way to give Claude persistent, domain-specific expertise. A skill is a folder containing a SKILL.md file plus optional scripts, references, and assets — all discoverable and loadable on demand without bloating context.

> Deep dive references: > - references/anatomy.md — structure, file layout, frontmatter spec, progressive disclosure > - references/writing.md — writing patterns, style guide, description engineering, pitfalls > - references/evals.md — testing, grading, iteration loop, packaging

---

The Mental Model: Onboarding Guide for an Expert Hire

Building a skill is like writing an onboarding guide for a new hire who is already highly capable but lacks your specific organizational knowledge. They don't need to be told what code is. They need to know: your naming conventions, your deployment dance, which script to run when, and why you do things a certain way.

The implication: don't explain what Claude already knows. Only encode knowledge Claude can't infer from its training — your procedures, your environment's quirks, your tools' gotchas, your output standards.

---

Quick Decision: What Kind of Skill?

| Need | Skill Type | |------|-----------| | Teach a workflow with multiple steps | Procedural — numbered steps, decision tree | | Wrap an environment's constraints (libraries, paths, formats) | Environmental — code snippets, gotcha table | | Layer expert guidance on top of an MCP server | MCP Enhancement — workflow + tool guidance | | Router that dispatches to other skills/files | Router — dispatch table, references/ per domain | | Style or quality standard | Standard — constraints, examples of good/bad |

Most skills combine types. Decide the primary type first; it governs the opening structure.

---

The Core Loop

Identify gap → Draft SKILL.md → Test on 2-3 real prompts → Review outputs → 
Revise based on what Claude actually did wrong → Repeat → Package

This is not waterfall. The most common mistake is writing 500 lines before running a single test. Start thin, iterate from real failures.

Step 1 — Capture Intent Before Writing

Answer these before touching a file:

1. What will Claude be able to do that it couldn't before?
2. What does the user say when they need this? (triggers)
3. What is the output format — a file, a code block, a decision, prose?
4. What does Claude do wrong without the skill? (This is your assertion list.)

If you can't answer all four, talk to the user more. The answers determine what goes in the skill.

Step 2 — Write the SKILL.md

Start with the YAML frontmatter, then the body. See references/anatomy.md for the exact format.

Frontmatter minimum:

---
name: my-skill           # lowercase, hyphens, max 64 chars
description: |
  What it does and when to trigger it. 1-4 sentences.
  Be specific about trigger phrases. "Pushy" is right — Claude undertriggers.
---

Body structure for most skills:

# [Skill Name]

Brief framing paragraph (what this is, the mental model).

## Decision Tree / When to Use What
Short table or if-then. Helps Claude pick the right path fast.

## Core Workflow
Steps or sections. Explain the *why* behind non-obvious choices.

## Gotchas / Common Mistakes
What Claude will get wrong without this section.

## Quick Reference
Copy-paste templates, code snippets, lookup tables.

Keep SKILL.md under 500 lines. When you exceed that: extract to references/.

Step 3 — Test on Real Prompts

Run 2-3 prompts that represent what real users would actually say. Observe:

• Did Claude read the skill? (Check for bash SKILL.md in transcript)
• Did Claude follow the workflow or improvise its own?
• Did the output match what you'd consider correct?
• Where did it go off-track?

Write down specific failures — not "it was bad" but "it used pip install without --break-system-packages" or "it didn't read references/forms.md before filling the form."

Step 4 — Revise Based on Failures

Map each failure to a skill fix:

| Failure Type | Fix | |-------------|-----| | Claude ignored a step | Make the step more explicit + explain why it matters | | Claude reinvented a helper script | Bundle the script in scripts/, reference it explicitly | | Claude read SKILL.md but missed the reference file | Make the reference call-to-action more direct | | Output format was wrong | Add a template or example in the skill | | Claude undertriggered (didn't read skill when it should) | Strengthen the description; add more trigger phrases | | Claude overtriggered (read skill unnecessarily) | Tighten the description with explicit NOT triggers |

Step 5 — Package

When the skill is stable:

python package_skill.py path/to/skill-folder/

This creates a .skill file ready for installation. See references/evals.md for the full packaging checklist.

---

The Three Laws of Skill Writing

1. Only say what Claude doesn't already know. Every line competes for context window. If Claude could infer it from training, cut it. Domain-specific gotchas, environment paths, output templates — keep. Generic "be helpful and clear" — cut.

2. Explain the why, not just the what. Instructions without reasons get ignored when Claude thinks it knows better. "Use --break-system-packages" is weaker than "Use --break-system-packages because pip in this environment rejects installs without it, even for packages you need."

3. Trust progressive disclosure — don't front-load everything. The SKILL.md body is Level 2. Reference files are Level 3. Scripts are Level 4 (execute without loading). If information is only needed for a sub-case, move it to a reference file and point to it with a clear trigger.

---

Common Pitfalls

| Mistake | What Happens | Fix | |---------|-------------|-----| | Front-loading the full reference manual | SKILL.md hits 800 lines, Claude struggles to extract the key steps | Split into references/ — put procedures in SKILL.md, details in references/ | | Writing ALWAYS/NEVER without explaining why | Claude ignores caps-lock rules when its own judgment says otherwise | Replace with reasoning: "Do X because Y will happen otherwise" | | Generic description that doesn't name triggers | Skill never fires even when it should | Name the exact phrases users say ("write a skill", "build a SKILL.md") | | Asserting things Claude already knows | Wasted tokens, no improvement | Audit every line: "Would Claude do this without being told?" If yes, cut | | No evals before shipping | Skill seems fine but fails on real diverse inputs | Always run 3 real prompts before packaging | | Bundle everything in one file | Any context means all context — bloated for simple cases | Use progressive disclosure, reference files for optional content |

---

Quick Reference: File Layout

my-skill/
├── SKILL.md           ← Required. Frontmatter + core instructions.
├── references/        ← Optional. Domain docs, sub-guides.
│   ├── guide-a.md
│   └── guide-b.md
├── scripts/           ← Optional. Pre-built Python/bash helpers.
│   └── process.py
├── assets/            ← Optional. Templates, fonts, icons.
└── evals/             ← Recommended. Test prompts for iteration.
    └── evals.json

The .skill file is just a zip of this folder (evals/ excluded from distribution).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Razaib-khan
• Source: Razaib-khan/ForgeWeave
• License: MIT

Install and usage instructions live in the source repository linked above.