skill-builder

Files (8)

• SKILL.md
• SKILL.md · assets/template-skill/
• best-practices.md · references/
• patterns.md · references/
• specification.md · references/
• workflows.md · references/
• init_skill.py · scripts/
• validate_skill.py · scripts/

SKILL.md (first lines)

# Skill Builder

A comprehensive guide for creating effective Agent Skills that extend Claude's capabilities with specialized knowledge, workflows, and tools.

## Overview

Agent Skills are filesystem-based resources that provide Claude with domain-specific expertise. Skills use **progressive disclosure** to efficiently manage context:

1. **Level 1 - Metadata** (~100 tokens): `name` and `description` in YAML frontmatter - always loaded at startup
2. **Level 2 - Instructions** (<5k tokens): SKILL.md body - loaded when skill triggers
3. **Level 3+ - Resources** (unlimited): Bundled files in scripts/, references/, assets/ - loaded on-demand

## Skill Structure

```
skill-name/
├── SKILL.md                    # Required - Core instructions
├── scripts/                    # Optional - Executable code
│   ├── helper.py
│   └── validate.sh
├── references/                 # Optional - Documentation
│   ├── api-reference.md
│   └── examples.md
└── assets/                     # Optional - Templates, images, etc.
    ├── template.html
    └── logo.png
```

## Creating a New Skill

### Step 1: Define Purpose and Scope

Before writing any code, answer these questions:

- What specific problem does this skill solve?
- What tasks trigger this skill? (Be specific for the description)
- What procedural knowledge does Claude lack for this task?
- What reusable resources would help? (scripts, references, assets)

**Decision Framework:**
- Use **scripts/** when: Operations need deterministic reliability, code is repeatedly rewritten, or external tools are involved
- Use **references/** when: Domain knowledge needs to be loaded into context, documentation is too long for SKILL.md
- Use **assets/** when: Output requires templates, binary files, or static resources

### Step 2: Initialize the Skill

Run the initialization script from this skill's directory:

```bash
python scripts/init_skill.py <skill-name>
```

This creates `~/.claude/skills/<skill-name>/` by default (Claude Code's user-level skills folder).

Options:
- `--path <dir>` - Create skill in a different location (e.g., `--path ./project/.claude/skills`)
- `--resources scripts,references,assets` - Include specific resource directories
- `--examples` - Include example placeholder files

### Step 3: Write the YAML Frontmatter

The frontmatter is critical - it determines when Claude uses your skill.

```yaml
---
name: my-skill-name
description: Clear description of what the skill does and when to use it. Include trigger keywords and specific use cases.
license: Apache-2.0
metadata:
  author: your-name
  version: "1.0"
---
```

**Validation Rules:**
- `name`: Max 64 characters, lowercase letters/numbers/hyphens only, no XML tags
- `description`: Max 1024 characters, non-empty, no XML tags. Be specific about triggers.

**Good vs Bad Descriptions:**
- ❌ "Helps with code" (too vague)
- ✅ "Reviews Python and JavaScript code for security vulnerabilities, PEP 8 compliance, and performance issues"
- ❌ "PDF stuff" (no trigger words)
- ✅ "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."

### Step 4: Write the Instructions

The SKILL.md body is loaded when the skill triggers. Keep it under 500 lines.

**Writing Guidelines:**
- Use imperative/infinitive form ("To accomplish X, do Y" not "You should do X")
- Include only information Claude doesn't already know
- Prefer concise examples over verbose explanations
- Reference bundled files explicitly so Claude knows they exist

**Recommended Sections:**
```markdown
## Overview
Brief purpose statement (2-3 sentences)

## Quick Start
Minimal working example

## Detailed Instructions
Step-by-step procedures for common tasks

## Common Patterns
Typical workflows and when to use them

## Edge Cases
How to handle unusual situations

## References
Links to bundled files for more detail
```

### Step 5: Add Bundled Resources

For detailed guidance on resource types, see:
- `references/specification.md` - Complete format specification

From michaellaret7/Agent-Harness-First-Principles, Apache-2.0.

More from michaellaret7/Agent-Harness-First-Principles