name	description
skill-builder	Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

Skill Builder

Create and iterate on skills — modular packages that extend Claude with specialized knowledge, workflows, and tools.

Install: npx skills add echohack/skill-builder

Skill Structure

skill-name/
├── SKILL.md              # Required. Frontmatter + instructions.
├── scripts/              # Executable code for deterministic/repeated tasks
├── references/           # Documentation loaded into context on demand
└── assets/               # Files used in output (templates, icons, fonts)

Frontmatter

---
name: skill-name                # Required. Skill identifier.
description: What this skill does. Use when [triggers]. Covers [use cases].  # Required. Primary trigger mechanism.
allowed-tools:                  # Optional. Tools the skill needs permission to use.
  - Bash(npm run build)
  - WebFetch(docs.example.com/*)
---

The description is the primary trigger mechanism. Include all "when to use" language here — the body only loads after triggering.

allowed-tools grants tool permissions when the skill is active. Each entry is a tool name with an optional argument pattern. Use when the skill requires specific tool access (shell commands, web fetches, MCP tools) to function.

Formats:

• Bare tool name: Read, Write, Edit — grants full access to that tool
• With argument pattern: Bash(npm run build) — grants access only for matching invocations
• Wildcard patterns: WebFetch(docs.example.com/*) — matches any path under that domain
• Comma-separated list: Read, Write, Edit, Glob — multiple tools on one line
• MCP tools: mcp__server__tool_name — grants access to specific MCP server tools

Example — a knowledge vault skill that searches, captures, and archives via browser:

allowed-tools: Read, Write, Edit, Glob, Grep,
  mcp__qmd__search, mcp__qmd__vsearch, mcp__qmd__query, mcp__qmd__get,
  AskUserQuestion, WebFetch,
  mcp__claude-in-chrome__tabs_context_mcp, mcp__claude-in-chrome__tabs_create_mcp,
  mcp__claude-in-chrome__navigate, mcp__claude-in-chrome__get_page_text,
  mcp__claude-in-chrome__computer

Example — a docx skill that runs a conversion script:

allowed-tools:
  - Bash(elixir scripts/convert_docx.exs *)

Example — a deploy skill that needs shell commands and API docs:

allowed-tools:
  - Bash(docker *)
  - Bash(kubectl *)
  - WebFetch(docs.example.com/*)
  - Read
  - Glob

Bundled Resources

Directory	Purpose	Loads into context?
scripts/	Deterministic code, repeatedly needed	No (executed directly)
references/	Documentation Claude consults while working	Yes, on demand
assets/	Templates, images, boilerplate for output	No (used in output)

Test all added scripts by running them. Delete example files and directories not needed by the skill.

Standard Template

Follow the section order in references/template.md when writing SKILL.md:

1. Title + one-liner — Immediate orientation
2. Behavior — Input -> output transformations
3. Examples — Acceptance by example
4. Error Handling — Edge cases and failures
5. Bundled Resources — What's included and when to use it

Think of skills as functional constructs: declare the transformations (what goes in, what comes out), not procedural steps. For skills with multiple functions, declare each transformation separately.

Omit sections that don't apply. Keep SKILL.md under 500 lines.

Writing Style

The context window is a public good. Every line in a skill competes with system prompt, conversation history, and the user's actual request.

Rules:

• Write in imperative voice ("Extract text with..." not "You can extract text with...")
• Cut "why this works" paragraphs — Claude doesn't need motivation
• Prefer one example over three paragraphs of explanation
• Only add context Claude doesn't already have
• Challenge each paragraph: does it justify its token cost?

Use Declarative instead of Procedural

Pattern (declarative):

## Changelog Generation

input: git commit range (defaults to last tag..HEAD)
output: changelog entry prepended to CHANGELOG.md

Format: [Keep a Changelog](https://keepachangelog.com). Group commits by
conventional commit type. Use today's date and the next semantic version.

Anti-pattern (procedural):

## Generating a Changelog

1. First, run `git log` to get the commits since the last tag
2. Then, group the commits by type (feat, fix, chore)
3. Next, format each group as a markdown section
4. Finally, prepend the new entry to CHANGELOG.md with today's date

Design Patterns

Brief summaries below. For full examples, see references/patterns.md.

Progressive Disclosure

Load context in three levels:

Level	What	Budget
Metadata	name + description	~100 words, always loaded
SKILL.md body	Instructions, workflow	<5k words, on trigger
Bundled resources	Scripts, references, assets	Unlimited, on demand

Keep core behavior in SKILL.md. Move variant-specific details to reference files. Reference them clearly so Claude knows they exist and when to read them.

Degrees of Freedom

Match specificity to fragility:

Freedom	When	Format
High	Multiple valid approaches	Text instructions
Medium	Preferred pattern, some variation	Pseudocode or parameterized scripts
Low	Fragile operations, consistency critical	Exact scripts, few parameters

Acceptance by Example

Define success through concrete examples with testable acceptance criteria. Structure: Scenario (input) -> Expected output -> Acceptance criteria (pass/fail conditions).

Example — Changelog skill:

Scenario: User asks to generate a changelog entry for a bug fix.

Expected output:

## [1.2.1] - 2025-03-15
### Fixed
- Resolved timeout error when uploading files >50MB (#423)

Acceptance criteria:

• Follows Keep a Changelog format
• Version uses semantic versioning
• Change categorized correctly (Added, Fixed, Changed, etc.)
• References issue/PR number when available
• Date in ISO 8601 format (YYYY-MM-DD)

Case Arrows

Declare edge cases and failure modes with arrow (->) format. Edge cases first, expected behavior last:

case input:
  empty input     -> return empty result, no error
  missing field   -> use sensible default
  malformed input -> return clear error message
  valid input     -> produce expected output

Use arrows for branching logic, bullets for output quality within each branch.

Functional Decomposition

Declare each behavior as a small, independent transformation. Compose them to build complex functionality.

Pattern (decomposed):

## Document Processing

- **extract**: PDF path -> raw text
- **normalize**: raw text -> cleaned text (trim, collapse whitespace, fix encoding)
- **classify**: cleaned text -> document type (invoice, contract, receipt)
- **summarize**: cleaned text + document type -> structured summary

Anti-pattern (monolithic):

## Document Processing

Take a PDF, extract its text, clean it up, figure out what kind of document
it is, and produce a summary.

Each transformation is testable on its own, reusable across workflows, and can be given its own degree of freedom. When a skill has multiple behaviors, decompose them — don't describe them as one blob.

Skill Stacking

Each skill owns a specific domain. When a domain grows too large, split it into focused skills that compose together:

# Too broad — one skill doing everything
document-processor/    # handles PDF, DOCX, XLSX, images, OCR...

# Better — stacked skills with clear ownership
pdf-editor/            # PDF-specific transforms
docx-editor/           # DOCX-specific transforms
document-converter/    # converts between formats, invokes pdf-editor and docx-editor

Skills reference other skills for cross-domain tasks. A high-level skill orchestrates; leaf skills own their domain. Split when a skill accumulates unrelated functions or its SKILL.md approaches the 500-line limit.

Process

1. Understand

Gather concrete examples of how the skill will be used. Ask:

• What functionality should this skill support?
• What would a user say that should trigger it?
• Can you show example inputs and expected outputs?

Start with the most important questions. Follow up as needed.

2. Plan

Analyze each example to identify reusable resources:

If you find yourself...	Create a...
Rewriting the same code	scripts/ file
Re-discovering schemas or docs	references/ file
Copying the same boilerplate	assets/ directory

3. Build

Create the skill directory and SKILL.md. Follow the standard template and writing style rules.

Write the frontmatter first — description is the trigger, allowed-tools grants permissions. Then declare the behavior: input -> output transformations, examples, error handling, resource references.

Request user input when the skill needs their assets, documentation, or domain knowledge.

4. Iterate

1. Use the skill on real tasks
2. Notice struggles or inefficiencies
3. Update SKILL.md or bundled resources
4. Test again

Use case arrows to build a test plan. Verify edge cases first, expected behavior last.

Anti-patterns

Anti-pattern	Why it's bad	Fix
README, CHANGELOG, or other auxiliary docs	Clutter — skills are for agents, not humans	Delete them
"When to use" in the body	Body loads after triggering — too late	Move to frontmatter description
Nested references (ref -> ref -> ref)	Claude loses the thread	Keep references one level deep
Duplicated content across SKILL.md and references	Wastes context, risks drift	Single source of truth
Dead links to non-existent files	Confuses Claude, wastes a tool call	Verify all referenced files exist
Verbose explanations over examples	Higher token cost, lower signal	One example beats three paragraphs
Reference files >100 lines without TOC	Claude can't preview scope	Add table of contents at top