Skill Builder

Skill Builder

Create, validate, and refine Agent Skills.

Quick Start

1. Gather the capability, triggers, and required domain knowledge. 2. Choose a simple single-file skill or a multi-file skill with references. 3. Write SKILL.md with concise, trigger-focused instructions. 4. Add reference files only for detail that would otherwise bloat SKILL.md. 5. Validate YAML frontmatter, file layout, and naming. 6. Test the skill with the natural language users are likely to say.

Workflow

• Start with requirements and scope control.
• Design the structure before writing content.
• Keep descriptions in third person and include trigger keywords.
• Use progressive disclosure for long examples, templates, and validation details.

Gates

Follow in order. Pass means a check you can satisfy with concrete artifacts (written bullets, paths, line counts, parsed YAML)—not an internal sense of “done.”

1. Requirements — Pass: Capability, triggers, and any required domain knowledge (or explicit “none”) are written down or confirmed from the user. 2. Structure — Pass: Single-file vs SKILL.md + references/ is chosen; heavy detail lives in references, not inlined in SKILL.md. 3. Draft — Pass: Frontmatter is valid YAML with name and description; SKILL.md is ≤ 500 lines; every relative link from SKILL.md resolves to a path that exists under this skill directory; each allowed-tools entry (if present) is justified. 4. Trigger check — Pass: At least one natural-language user phrase plausibly matching the description is identified for a quick invocation test.

Validation

• Keep SKILL.md under 500 lines.
• Prefer one-level reference links.
• Avoid time-sensitive guidance.
• Confirm frontmatter is valid YAML.
• Check that any allowed-tools entries are necessary and correct.

Advanced Reference

For the full workflow, templates, examples, and validation checklist, see references/skill-builder-guide.md.

Skill Builder

Create, validate, and refine Agent Skills following official best practices.

Workflow Overview

1. Gather Requirements → 2. Design Structure → 3. Write SKILL.md → 4. Add Supporting Files → 5. Validate → 6. Test

Instructions

Phase 1: Gather Requirements

Before writing any skill, collect this information from the user:

Required:

• What capability should the skill provide?
• When should the agent invoke this skill (triggers)?
• What domain knowledge is needed that the agent doesn't have?

Optional:

• Are there utility scripts needed?
• Should tool access be restricted (allowed-tools)?
• What files/references should be included?

Ask clarifying questions if the scope is unclear. Skills should be focused on one capability.

Phase 2: Design the Structure

Determine the skill complexity:

Simple Skill (single file):

skill-name/
└── SKILL.md

Use when: Single capability, no scripts, under 200 lines of content.

Multi-file Skill (progressive disclosure):

skill-name/
├── SKILL.md           # Overview + navigation (under 500 lines)
├── reference.md       # Detailed API/schema info
├── examples.md        # Extended examples
└── scripts/           # Utility scripts
    ├── helper.py
    └── validate.py

Use when: Complex domain, multiple sub-capabilities, utility scripts needed.

Phase 3: Write SKILL.md

Frontmatter Requirements

---
name: skill-name-here
description: What it does and when to use it. Include trigger keywords.
allowed-tools: Read, Grep, Glob  # Optional: restrict tool access
---

Name rules:

• Lowercase letters, numbers, hyphens only
• Maximum 64 characters
• Use gerund form preferred: processing-pdfs, generating-commits
• No reserved words: "anthropic", "claude"

Description rules:

• Maximum 1024 characters
• Write in third person: "Processes X" not "I can process X"
• Include BOTH what it does AND when to use it
• Include trigger keywords users would naturally say

Description pattern:

<what it does>. <trigger conditions>.

Good examples:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Bad examples:

description: Helps with documents  # Too vague
description: I can process data    # Wrong person, too vague
description: Does stuff with files # Useless

Body Structure

Use this template:

# Skill Name

## Quick Start

<Minimal working example - 3-5 lines max>

## Instructions

<Step-by-step guidance - be specific about WHAT to do>

## Workflows

<For complex tasks, provide checklists the agent can track>

## Examples

<Input/output pairs showing desired style and output>

## Advanced

<Link to additional files if needed>
For detailed reference, see [reference.md](reference.md).

Phase 4: Apply Best Practices

Conciseness Principle

Default assumption: the agent is already very smart.

Only add context the agent doesn't have. Challenge each piece of information:

• "Does the agent really need this explanation?"
• "Can I assume the agent knows this?"
• "Does this paragraph justify its token cost?"

Bad (verbose):

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available...

Good (concise):

Use pdfplumber for text extraction:
\`\`\`python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

Degrees of Freedom

Match specificity to task fragility:

High freedom (text-based instructions) - when multiple approaches are valid:

## Code review process
1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability

Low freedom (exact commands) - when operations are fragile:

## Database migration
Run exactly this script:
\`\`\`bash
python scripts/migrate.py --verify --backup
\`\`\`
Do not modify the command or add additional flags.

Feedback Loops

For quality-critical tasks, add validation steps:

## Editing Process
1. Make your edits
2. **Validate immediately**: `python scripts/validate.py`
3. If validation fails:
   - Review the error message
   - Fix the issues
   - Run validation again
4. **Only proceed when validation passes**

Checklists for Complex Workflows

Provide copyable checklists:

````markdown

Form Filling Workflow

Copy this checklist and track progress:

Task Progress:
- [ ] Step 1: Analyze the form
- [ ] Step 2: Create field mapping
- [ ] Step 3: Validate mapping
- [ ] Step 4: Fill the form
- [ ] Step 5: Verify output

````

Examples Pattern

Show input/output pairs for style guidance:

````markdown

Commit Message Format

Example 1: Input: Added user authentication with JWT tokens Output:

feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware

Example 2: Input: Fixed bug where dates displayed incorrectly Output:

fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation

````

Progressive Disclosure

Reference additional files instead of including everything:

## Advanced Features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Critical: Keep references one level deep from SKILL.md. Don't create chains of references.

Phase 5: Validation Checklist

Before finalizing, verify:

Core Quality:

• [ ] Description is specific and includes trigger keywords
• [ ] Description includes both what it does AND when to use it
• [ ] Description is written in third person
• [ ] Name uses lowercase-hyphen format
• [ ] SKILL.md body is under 500 lines
• [ ] No time-sensitive information
• [ ] Consistent terminology throughout
• [ ] Examples are concrete, not abstract
• [ ] File references are one level deep
• [ ] Workflows have clear steps

Technical:

• [ ] Valid YAML frontmatter (no tabs, correct syntax)
• [ ] No Windows-style paths (use forward slashes)
• [ ] Required packages listed if applicable
• [ ] Scripts have explicit error handling

If using `allowed-tools`:

• [ ] Only necessary tools are listed
• [ ] Tool names are correct (Read, Grep, Glob, Edit, Write, Bash, etc.)

Phase 6: Test the Skill

After creating the skill:

1. Place in correct location for your agent (e.g. a personal or project-level skills directory such as ~/.claude/skills/skill-name/SKILL.md, .claude/skills/skill-name/SKILL.md, or ~/.agents/skills/skill-name/SKILL.md — follow your harness's convention).

2. Reload the agent so it discovers the skill.

3. Test with natural language that matches your description triggers:

   User: "Help me extract text from this PDF"
   → Should invoke skill with "PDF" trigger

4. Verify the agent navigates correctly to reference files when needed

5. Iterate based on observation:

• Does the agent find the right information?
• Does the agent apply rules correctly?
• Are there missing examples or edge cases?

Anti-Patterns to Avoid

DON'T:

• Use Windows-style paths (scripts\helper.py)
• Offer too many options without a default
• Include time-sensitive information
• Use inconsistent terminology
• Create deeply nested file references
• Assume tools are installed without documenting
• Write overly verbose explanations the agent already knows
• Use first or second person in descriptions

DO:

• Provide a single recommended approach with alternatives noted
• Use consistent terminology throughout
• Structure longer files with table of contents
• Document package requirements explicitly
• Trust the agent's existing knowledge
• Write descriptions that help the agent select the right skill

Template: Simple Skill

---
name: your-skill-name
description: <What it does>. Use when <trigger conditions>.
---

# Your Skill Name

## Quick Start

<Minimal example - get user productive immediately>

## Instructions

<Clear, numbered steps for common use cases>

## Examples

<2-3 input/output examples showing desired style>

Template: Multi-File Skill

SKILL.md:

---
name: your-skill-name
description: <What it does>. Use when <trigger conditions>.
---

# Your Skill Name

## Quick Start

<Minimal example>

## Common Tasks

### Task A
<Brief instructions>

### Task B
<Brief instructions>

## Advanced

- **Full reference**: See [reference.md](reference.md)
- **Examples**: See [examples.md](examples.md)
- **Utility scripts**: See [scripts/](scripts/)

reference.md:

# Reference

## Contents
- Section A
- Section B
- Section C

## Section A
<Detailed content>
...

Example Output

After gathering requirements for a "code-review" skill:

Created skill: .claude/skills/reviewing-code/

Files:
├── SKILL.md (245 lines) - Core instructions and checklists
├── security-patterns.md - Common security issues to check
└── examples.md - Example review outputs

Description: "Reviews code changes for production readiness, checking code quality, architecture, testing, and security. Use when reviewing PRs, checking code before merge, or auditing code quality."

Next steps:
1. Review the generated files
2. Reload the agent to discover the skill
3. Test with: "Review the changes in my current branch"

Guidelines

When the user asks for a skill: 1. Ask clarifying questions about scope and triggers 2. Propose the structure (simple vs multi-file) 3. Write the SKILL.md following all patterns above 4. Run through the validation checklist 5. Explain how to test the skill

Iterative refinement: If the user reports the skill isn't working: 1. Check if description triggers match user's natural language 2. Verify YAML syntax is valid 3. Ensure file paths are correct 4. Review if instructions are clear enough for the task