skill-builder

name	skill-builder
description	Create, refine, and validate Agent Skills following the agentskills.io specification. Use when writing a SKILL.md, creating a new skill directory, improving an existing skill's triggering or content, running evals, or diagnosing why a skill isn't activating.

Agent Skills

Create skills that follow the agentskills.io standard. A skill is a directory with a SKILL.md file and optional resources.

Golden rule: Add what the agent lacks, omit what it knows. If the agent would get it right without your instruction, cut it.

Language: All skill content must be written in English. Skill frontmatter, instructions, examples, and reference files are consumed by AI agents — English is the expected language.

Prose: No hard-wrapping — paragraphs flow as single lines; the renderer wraps. Write what matters, skip the rest; no preambles, no filler.

Quickstart — minimal skill

Create <name>/SKILL.md (directory name MUST match name):

---
name: roll-dice
description: Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.
---

To roll a die, use:

```bash
echo $((RANDOM % <sides> + 1))

Replace <sides> with the number of sides (6 for standard, 20 for d20).

That's a complete skill. Expand only as needed.

## Directory structure

skill-name/ ├── SKILL.md # Required: metadata + instructions ├── scripts/ # Optional: executable code ├── references/ # Optional: docs loaded on demand ├── assets/ # Optional: templates, static resources └── evals/ # Optional: test cases

Keep file references one level deep from `SKILL.md`. Avoid deeply nested chains.

## Frontmatter

### Required

| Field | Rules |
|---|---|
| `name` | 1-64 chars. `a-z`, `0-9`, hyphens. No leading/trailing/consecutive hyphens. Must match folder name. |
| `description` | 1-1024 chars. What it does AND when to use it. See "Writing descriptions" below. |

### Optional

| Field | Purpose |
|---|---|
| `license` | License name or bundled file reference |
| `compatibility` | 1-500 chars. Env requirements (tools, OS, products). Most skills don't need this. |
| `metadata` | Arbitrary key-value map. Use unique keys to avoid conflicts. |
| `allowed-tools` | Space-separated pre-approved tools (experimental, support varies) |

### Examples

Minimal:
```yaml
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
---

With optional fields:

---
name: data-pipeline
description: >
  Build and run data pipelines using our internal ETL framework.
  Use when the user mentions data ingestion, batch jobs, or ETL.
license: Proprietary. LICENSE.txt has complete terms
compatibility: Requires Python 3.14+ and uv
metadata:
  author: data-team
  version: "1.0"
allowed-tools: Bash(git:*) Bash(jq:*) Read
---

Writing descriptions

The description decides activation. Poor description → skill never triggers.

Principles:

• Imperative phrasing: "Use this skill when..." not "This skill helps..."
• User intent, not implementation: what the user is trying to achieve, not internal mechanics
• Err on the pushy side: explicitly list contexts, including implicit ones
• Name the boundary: what the skill does NOT do, when relevant

Good vs poor:

# Poor — vague, no trigger context
description: Helps with PDFs.

# Poor — too narrow, misses common phrasings
description: Process CSV files.

# Good — specific scope, explicit triggers, broad coverage
description: >
  Analyze CSV and tabular data — summary statistics, derived columns,
  charts, and data cleaning. Use when the user has a CSV, TSV, or
  Excel file and wants to explore, transform, or visualize data,
  even if they don't explicitly mention "CSV" or "analysis."

Nuance: agents often skip skills for simple one-step tasks they can handle alone. Descriptions matter most for specialized knowledge or non-obvious domains.

Writing the body

Keep SKILL.md under 500 lines / 5,000 tokens. Move reference material to separate files.

Ask for each paragraph: "Would the agent get this wrong without this instruction?" If no → cut it.

See references/WRITING_SKILLS.md for body structure, patterns, and examples.

Progressive disclosure

Three load stages:

1. Discovery (~100 tokens) — name + description loaded at startup for all skills
2. Activation (< 5000 tokens) — full SKILL.md loaded when task matches
3. Resources (on demand) — files in scripts/, references/, assets/ loaded only when referenced

Tell the agent when to load each file:

# Good
Read `references/api-errors.md` when the API returns a non-200 status.

# Bad
See references/ for details.

Scripts

Bundle executables in scripts/ when the agent repeats the same logic. Use one-off commands (uvx, npx) for simple invocations.

Design for agentic use:

• Non-interactive (no TTY prompts)
• --help documentation
• Helpful errors ("Received X, expected Y")
• Structured output (JSON/CSV) to stdout, diagnostics to stderr
• Idempotent where possible
• Dry-run flag for destructive ops
• Meaningful exit codes

See references/USING_SCRIPTS.md for language-specific setup (Python PEP 723, Deno, Bun, Ruby).

Evaluating skills

Test each case with skill vs without skill (or previous version) to prove the skill adds value.

See references/EVALUATING.md for full workflow.

Optimizing descriptions (triggering)

A skill only helps if it activates. Test triggering systematically.

See references/OPTIMIZING_DESCRIPTIONS.md for eval query design and optimization loop.

Validation

skills-ref validate ./my-skill

Checks frontmatter and naming conventions.

Best practices summary

1. Start from real expertise — extract from actual tasks or synthesize from project artifacts. Not generic references.
2. Refine with execution — read agent traces, not just outputs. Wasted steps signal vague instructions.
3. Spend context wisely — cut anything the agent would get right without the skill.
4. Scope coherently — one skill = one coherent unit of work. Not too narrow, not too broad.
5. Iterate with evals — test systematically, not anecdotally.

Gotchas

• Description under 1024 chars — they tend to grow during optimization.
• Directory name MUST match name in frontmatter. Mismatch breaks discovery.
• Body loads entirely on activation — anything not on the critical path belongs in references/.
• Generic references ("see references/") don't trigger loading. Specify the condition.
• Skills that don't improve vs baseline may not be adding value — test with and without.
• Description changes during optimization can regress on earlier-passing queries — validation split catches this.

See references/BEST_PRACTICES.md and references/SPECIFICATION.md for full details.