Skill Creator (Tier 3 - Full Reference) Skill

Skill Creator (Tier 3 - Full Reference)

Persona: Curriculum designer creating focused, teachable modules - prioritizes clarity and immediate usability.

Skills are modular packages extending Claude with specialized knowledge, workflows, and tools.

Note: Core workflow is in instructions.md. This file contains detailed templates, examples, and advanced topics.

Skill Structure

Skills use a 3-tier progressive format for optimal context usage:

skill-name/
├── metadata.yml (Tier 1)      - ~50 tokens, always loaded
├── instructions.md (Tier 2)   - ~200 tokens, core workflow
├── SKILL.md (Tier 3)          - Full content, loaded on-demand
└── resources/ (Tier 3)        - Advanced materials
    ├── examples/              - Usage examples
    ├── templates/             - Reusable templates
    ├── scripts/               - Executable code
    └── references/            - Detailed documentation

3-Tier Loading Strategy

| Tier | File | Size | Always Loaded? | Contains | |------|------|------|----------------|----------| | 1 | metadata.yml | ~50 tokens | Yes | Name, triggers, 1-2 sentence description, quick reference | | 2 | instructions.md | ~200 tokens | When triggered | Core workflow, mandatory checks, anti-patterns, escalation | | 3 | SKILL.md | <5k words | On-demand | Full details, advanced topics, examples, edge cases | | 3 | resources/ | Variable | As needed | Templates, scripts, references, examples |

Tier 1: metadata.yml (~50 tokens)

The skill's "business card" - always in context, enables auto-triggering.

name: skill-name
version: 1.0.0

triggers:
  - keyword or phrase
  - another trigger
  - specific context

description: |
  One sentence what it does. One sentence when to use it.

summary: |
  2-3 line workflow summary
  Key principle or constraint

quick_reference:
  - "Step 1 in brief"
  - "Step 2 in brief"
  - "Critical rule"

Token budget: ~50 tokens. Every word counts.

Tier 2: instructions.md (~200 tokens)

Core workflow loaded when skill is triggered. Must be self-contained for simple cases.

Must include:

Core workflow (numbered steps)
Mandatory checks (verification gates)
Should NOT do (anti-patterns)
Escalate when (complexity triggers)

Optional:

Quick commands table
Common patterns
Reference to Tier 3 for advanced topics

Token budget: ~200 tokens. Focus on the 80% case.

Tier 3: SKILL.md & resources/ (on-demand)

Full detailed content loaded only when needed for complex scenarios.

SKILL.md includes:

Detailed explanations
Edge cases and advanced topics
Comprehensive examples
Troubleshooting guides
Philosophy and principles

resources/ includes: | Type | When to Include | Example | |------|-----------------|---------| | examples/ | Concrete usage scenarios | api-integration/, async-test/ | | templates/ | Reusable file templates | test-template.py, config.json | | scripts/ | Executable code for repeated tasks | rotate_pdf.py, analyze.sh | | references/ | Documentation to reference while working | schema.md, api_docs.md |

Progressive loading: metadata.yml (always) -> instructions.md (when triggered) -> SKILL.md (complex cases) -> resources/ (as needed)

Core Principles

Conciseness is Key

The context window is a public good. Claude is already very smart - only add context Claude doesn't already have.

Challenge each piece: "Does Claude really need this?" Prefer concise examples over verbose explanations.

Degrees of Freedom

Match specificity to task fragility:

| Freedom | Format | Use When | |---------|--------|----------| | High | Text instructions | Multiple approaches valid, context-dependent | | Medium | Pseudocode/parameterized scripts | Preferred pattern exists, some variation OK | | Low | Specific scripts, few params | Operations fragile, consistency critical |

Triggers Enable Auto-Activation

The triggers and description fields in metadata.yml are the primary mechanism for skill activation.

triggers: Keywords/phrases that should activate this skill description: 1-2 sentences: what it does + when to use it summary: The core workflow/constraint in 2-3 lines

These fields are ALWAYS loaded (Tier 1). They enable Claude to auto-trigger the skill when relevant.

Do NOT put "When to Use" in instructions.md or SKILL.md - those load AFTER triggering.

Should NOT Attempt

Creating skills that duplicate existing ones (check first)
Skills that are too broad (split into focused skills)
Skills with more than 5k words in SKILL.md (move to resources/)
Skills that should be commands (user-initiated workflows) or agents (delegated tasks)
Including large references inline (use resources/references/)
Putting triggers/description in SKILL.md (belongs in metadata.yml)
Creating single-file skills (use 3-tier format)

Failure Behavior

When unable to create a skill:

State what's blocking (unclear scope, conflicting requirements)
Ask clarifying questions with concrete examples
Suggest alternative approaches (command, agent, or simpler skill)

Escalation Triggers

| Situation | Escalate To | |-----------|-------------| | Scope unclear after 2 rounds | User clarification with examples | | Significant overlap with existing | Extend existing skill instead | | Better as command/agent | command-creator or agent-creator skill | | Resources exceed reasonable size | Split into multiple focused skills |

Creation Process

Step 1: Understand with Concrete Examples

Ask: "What functionality should this skill support?", "Can you give usage examples?", "What should trigger this skill?"

Skip only when usage patterns are already clear.

Step 2: Plan Reusable Contents

For each example, analyze:

How to execute from scratch
What scripts/references/assets would help when repeating

| Example Query | Reusable Resource | |---------------|-------------------| | "Rotate this PDF" | resources/scripts/rotate_pdf.py | | "Build me a todo app" | resources/templates/hello-world/ | | "How many users logged in?" | resources/references/schema.md |

Step 3: Initialize

~/.claude/skills/skill-creator/scripts/init_skill.py <skill-name> --path <output-directory>

Creates: skill directory with 3-tier structure (metadata.yml, instructions.md, SKILL.md, resources/)

Step 4: Edit the Skill

Writing style: Imperative/infinitive form ("To accomplish X, do Y" not "You should do X")

Edit in order:

metadata.yml (~50 tokens):
- Add specific trigger keywords
- Write clear 1-2 sentence description
- Distill summary to 2-3 lines
- Create quick reference bullets
instructions.md (~200 tokens):
- Define core workflow (numbered steps)
- Add mandatory checks/verification gates
- List "Should NOT Do" anti-patterns
- List "Escalate When" complexity triggers
- Add quick commands if applicable
SKILL.md (detailed):
- Remove TODO placeholders
- Keep/expand persona statement
- Provide detailed process explanations
- Add comprehensive examples
- Cover advanced topics and edge cases
- Reference resources/ as needed
resources/:
- Customize or delete example files
- Add concrete examples in examples/
- Add reusable templates in templates/
- Add scripts/references only if needed

Step 5: Package

~/.claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-folder> [output-dir]

Validates (frontmatter, structure, description quality) then creates distributable zip.

Step 6: Iterate

Use skill on real tasks -> notice struggles -> update SKILL.md or resources -> test again

Migrating Existing Skills

For skills with old single-file format (YAML frontmatter + content in SKILL.md):

Extract metadata.yml:
- Copy name from frontmatter
- Add version: 1.0.0
- Create triggers list from description/context
- Write 1-2 sentence description
- Distill summary to 2-3 lines
- Create quick_reference bullets (~3-5 items)
Create instructions.md:
- Extract core workflow/process (numbered steps)
- Add mandatory checks/verification gates
- List anti-patterns ("Should NOT Do")
- List escalation triggers ("Escalate When")
- Keep under 200 tokens
Update SKILL.md:
- Remove frontmatter (now in metadata.yml)
- Remove core workflow (now in instructions.md)
- Keep detailed explanations, examples, edge cases
- Expand on advanced topics
- Reference instructions.md for basic workflow
Organize resources:
- Move existing scripts/ to resources/scripts/ (optional)
- Move existing references/ to resources/references/ (optional)
- Add resources/examples/ for concrete scenarios
- Add resources/templates/ for reusable files

Token targets: metadata.yml ~50, instructions.md ~200, SKILL.md <5k words

Template

metadata.yml (Tier 1, ~50 tokens)

name: skill-name
version: 1.0.0

triggers:
  - primary keyword
  - context phrase
  - specific scenario

description: |
  One sentence what it does. One sentence when to use it.

summary: |
  Core workflow in 2-3 lines
  Key principle or constraint

quick_reference:
  - "Step 1 brief"
  - "Step 2 brief"
  - "Critical rule"

instructions.md (Tier 2, ~200 tokens)

# {Skill Name} Instructions (Tier 2)

{One-line constraint or principle if critical.}

## Cycle/Process

1. **{Step}:** {What to do}
2. **{Step}:** {What to do}
3. **{Step}:** {What to do}

## Mandatory Checks

Before X:
- Verify Y
- Confirm Z

## Should NOT Do

- {Anti-pattern 1}
- {Anti-pattern 2}

## Escalate When

- {Complexity trigger 1}
- {Complexity trigger 2}

## Quick Commands

\```bash
# Common operation
command --flag

# Another operation
command2
\```

For {advanced topic}, see SKILL.md.

SKILL.md (Tier 3, detailed)

---
name: skill-name
description: What this skill does AND when to use it.
context: fork                    # Optional: run in forked sub-agent context (NEW)
agent: explore                   # Optional: agent type for execution (NEW)
user-invocable: true             # Optional: show in slash command menu (default: true) (NEW)
allowed-tools:                   # Optional: YAML-style tool list (NEW)
  - Read
  - Grep
  - Glob
  - Bash
hooks:                           # Optional: skill-scoped hooks (NEW)
  PreToolUse:
    - type: command
      command: "$HOME/.claude/hooks/skill_hook.py"
      timeout: 2
---

# Skill Name

{One paragraph: what this skill teaches Claude to do.}

## Persona

{1-2 sentences: expertise/approach shaping behavior.}

## Detailed Process

1. **{Step}:** {Detailed explanation}
2. **{Step}:** {Detailed explanation}

## Examples

### {Scenario}
{Input and expected behavior - detailed}

## Advanced Topics

### {Topic}
{Explanation}

## Should NOT Attempt

- {Anti-pattern 1 with explanation}
- {Anti-pattern 2 with explanation}

## Escalation

{When to recommend alternatives or ask for guidance.}

## Resources

- `resources/examples/X/`: {Purpose}
- `resources/templates/Y`: {Usage}
- `resources/scripts/Z.py`: {What it does}

New Frontmatter Fields (2026)

| Field | Type | Description | |-------|------|-------------| | context | fork | Run skill in forked sub-agent context (isolated) | | agent | string | Agent type for execution (explore, task, general-purpose) | | user-invocable | boolean | Show in slash command menu (default: true, set false to hide) | | allowed-tools | YAML list | Tools available to skill (cleaner than comma-separated) | | hooks | object | Skill-scoped hooks (PreToolUse, PostToolUse, Stop) |

Note: Triggers and "When to Use" belong in metadata.yml (Tier 1), not in instructions.md or SKILL.md.

Skill vs Command vs Agent

| Aspect | Skill | Command | Agent | |--------|-------|---------|-------| | Trigger | Auto or /skill-name | /command-name only | Task(subagent_type) | | Purpose | Procedural knowledge | User workflow | Delegated task | | Scope | How to think about X | Steps to do X | Execute X separately | | Example | systematic-debugging | /commit | code-reviewer |

Choose skill when: Claude needs to learn a methodology or approach. Choose command when: User wants a repeatable workflow. Choose agent when: Task should be delegated to a subagent.

Versioning Policy

Skills use Semantic Versioning in metadata.yml:

version: MAJOR.MINOR.PATCH

| Change Type | Bump | Example | |-------------|------|---------| | Breaking change (new required fields, removed sections) | MAJOR | 1.0.0 → 2.0.0 | | New feature (added section, new examples) | MINOR | 1.0.0 → 1.1.0 | | Fix (typo, clarification, correction) | PATCH | 1.0.0 → 1.0.1 |

When to bump:

MAJOR: Changes that would break existing usage (rare for skills)
MINOR: Adding new content, sections, examples, triggers
PATCH: Fixing errors, improving clarity, updating outdated info

Example version history:

1.0.0: Initial release
1.0.1: Fixed typo in example code
1.1.0: Added troubleshooting section
1.2.0: Added new templates to resources/
2.0.0: Restructured to 3-tier format

Note: The version is informational - it helps track changes but doesn't affect loading.

Common Mistakes

| Mistake | Fix | |---------|-----| | Skill too broad | Split into focused skills | | No concrete examples | Add 2-3 real usage scenarios | | Missing triggers in metadata.yml | Add specific trigger keywords | | Too much inline content | Move to resources/ | | No anti-patterns | Add "Should NOT Do" in instructions.md | | No failure guidance | Add "Escalate When" section | | Triggers in SKILL.md not metadata.yml | Move to metadata.yml Tier 1 | | Core workflow only in SKILL.md | Put in instructions.md Tier 2 | | metadata.yml exceeds 50 tokens | Trim to essential info only | | instructions.md exceeds 200 tokens | Move details to SKILL.md |

Related Skills

hook-creator: Create hooks skills reference
agent-creator: Create agents skills invoke
command-creator: Create commands for skills

When Blocked

If unable to create a working skill:

Request more concrete examples of usage
Check if existing skills already cover the use case
Consider if command or agent is more appropriate
Start with minimal skill and iterate based on real usage

Progressive Skill Format

Three-tier loading to minimize token usage (60-80% reduction for skill-heavy workflows).

Directory Structure

skills/<name>/
├── metadata.yml      # Tier 1: ~50 tokens (always scannable)
├── instructions.md   # Tier 2: ~200 tokens (core rules)
├── SKILL.md          # Tier 3: Full content (on demand)
└── resources/        # Tier 3: Examples, templates
    ├── examples/
    └── templates/

Tier Content

| Tier | File | Content | Tokens | When Loaded | |------|------|---------|--------|-------------| | 1 | metadata.yml | Name, triggers, one-line summary | ~50 | Always (index scanning) | | 2 | instructions.md | Core rules, quick reference | ~200 | On activation | | 3 | SKILL.md + resources/ | Full docs, examples, templates | Variable | On demand |

For file format templates, see the Template section above.

Usage

# Load tier 1 only (quick scan)
~/.claude/scripts/smart/skill-loader.sh test-driven-development 1

# Load tier 2 (core instructions)
~/.claude/scripts/smart/skill-loader.sh test-driven-development 2

# Load full skill (default)
~/.claude/scripts/smart/skill-loader.sh test-driven-development 3

When to Use Progressive Format

High-frequency skills - Loaded often, benefit from tiering
Large skills - >500 lines benefit most from tiering
Reference-heavy skills - Keep examples in tier 3

Migration Checklist

Create metadata.yml with triggers and summary
Extract core rules to instructions.md
Keep full content in SKILL.md
Move examples to resources/examples/
Test with skill-loader.sh at each tier

Agent Skills: Skill Creator (Tier 3 - Full Reference)

Skill Files