---

name: skill-creator-ultimate description: Use when creating new skills, editing existing skills, verifying skills work, or learning skill best practices. Covers complete frontmatter options, progressive disclosure, testing methodology, and packaging.

Skill Creator Ultimate

Create effective skills that Claude can discover and use successfully.

Core Principles

1. Conciseness

The context window is a public good. Default assumption: Claude is already very smart.

Only add context Claude doesn't already have. Challenge each piece:

• "Does Claude really need this explanation?"
• "Does this paragraph justify its token cost?"

Good (~50 tokens):

## Extract PDF text
Use pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

**Bad** (~150 tokens): Explaining what PDFs are before showing code.

### 2. Degrees of Freedom

Match specificity to task fragility:

| Freedom Level | When to Use | Example |
|---------------|-------------|---------|
| **High** (text) | Multiple valid approaches | Code review guidelines |
| **Medium** (pseudocode) | Preferred pattern exists | Report generation template |
| **Low** (exact script) | Fragile/error-prone ops | Database migration command |

### 3. Progressive Disclosure

Three-tier loading system:
1. **Metadata** (always loaded): name + description (~100 tokens)
2. **SKILL.md body** (when triggered): instructions (<500 lines)
3. **Bundled resources** (as needed): references, scripts (unlimited)

## Skill Anatomy

skill-name/ ├── SKILL.md # Required - main instructions ├── references/ # Optional - loaded as needed │ ├── api-reference.md │ └── workflows.md ├── scripts/ # Optional - executed, not loaded │ ├── init.py │ └── validate.py └── assets/ # Optional - used in output only └── template.pptx

### SKILL.md Structure

```yaml
---
name: my-skill
description: What it does and WHEN to use it
---

# My Skill

## Overview
[1-2 sentences]

## Quick Reference
[Table or bullets for scanning]

## [Main Sections]
[Implementation details]

## Common Mistakes
[What goes wrong + fixes]

Complete Frontmatter Reference

All fields are optional except description is strongly recommended.

Core Fields

Field	Max Length	Description
name	64 chars	Lowercase letters, numbers, hyphens only. If omitted, uses directory name.
description	1024 chars	CRITICAL for discovery. What the skill does AND when to use it. Third person.

Invocation Control

Field	Default	Description
disable-model-invocation	false	true = Only user can invoke via /name. Claude cannot auto-trigger.
user-invocable	true	false = Hidden from / menu. Only Claude can invoke.
argument-hint	none	Hint shown in autocomplete. Example: [issue-number] or [filename] [format]

Execution Control

Field	Description
allowed-tools	Tools Claude can use without permission. Example: Read, Grep, Bash(git:*)
model	Override model for this skill. Example: opus, sonnet, haiku
context	Set to fork to run in isolated subagent context.
agent	Subagent type when context: fork. Options: Explore, Plan, general-purpose, or custom agent name.
hooks	Hooks scoped to this skill's lifecycle. See Hooks documentation.

Example: Deploy Skill (User-Only, Forked)

---
name: deploy
description: Deploy application to production. Use when deployment is requested.
disable-model-invocation: true
context: fork
agent: general-purpose
allowed-tools: Bash(npm:*), Bash(git:*)
---

Deploy $ARGUMENTS to production:
1. Run test suite
2. Build application
3. Push to deployment target

String Substitutions

Skills support dynamic values:

Variable	Description
$ARGUMENTS	All arguments passed when invoking. If not in content, appended as ARGUMENTS: <value>
${CLAUDE_SESSION_ID}	Current session ID. Useful for session-specific files/logging.

Dynamic Context Injection

The !command`` syntax runs shell commands BEFORE skill content is sent to Claude:

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Task
Summarize this pull request...

Commands execute immediately; Claude receives the output, not the command.

Claude Search Optimization (CSO)

The description field is the PRIMARY triggering mechanism. Optimize for discovery.

Description Rules

1. Start with "Use when..." to focus on triggering conditions
2. Write in third person (injected into system prompt)
3. Include specific triggers, symptoms, situations
4. NEVER summarize workflow in description (Claude may shortcut and skip reading the skill body)

# BAD: Summarizes workflow - Claude may follow this instead of reading skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# GOOD: Just triggering conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

Keyword Coverage

Include words Claude would search for:

• Error messages: "Hook timed out", "ENOTEMPTY"
• Symptoms: "flaky", "hanging", "zombie"
• Synonyms: "timeout/hang/freeze"
• Tools: Actual commands, library names

Naming Conventions

Use gerund form (verb + -ing):

• processing-pdfs not pdf-processing
• analyzing-spreadsheets not spreadsheet-analysis
• testing-code not code-tests

Skill Types

Type	Purpose	Example
Technique	Concrete method with steps	condition-based-waiting
Pattern	Way of thinking about problems	flatten-with-flags
Reference	API docs, syntax guides	office-docs
Workflow	Multi-step procedures	deploy-to-production

Bundled Resources

scripts/

Executable code for deterministic, repeatedly-needed tasks.

When to include:

• Same code being rewritten repeatedly
• Deterministic reliability needed
• Token efficiency (execute without loading)

This skill includes:

• init_skill.py - Initialize new skill from template
• package_skill.py - Create distributable .skill file
• validate_skill.py - Validate skill structure

references/

Documentation loaded as needed into context.

When to include:

• Comprehensive API docs
• Detailed workflow guides
• Complex patterns and examples
• Large files (>10k words) - include grep patterns in SKILL.md

This skill includes:

• frontmatter-reference.md - Complete frontmatter options
• patterns.md - Output and workflow patterns
• testing-methodology.md - TDD-adapted testing for skills

assets/

Files used in output, NOT loaded into context.

When to include:

• Templates (.pptx, .docx)
• Boilerplate code directories
• Images, fonts, icons

Skill Creation Process

Step 1: Understand with Concrete Examples

Before writing, gather concrete usage examples:

• "What would a user say that should trigger this skill?"
• "Can you give examples of how this skill would be used?"

Step 2: Plan Reusable Contents

Analyze each example:

1. How would you execute this from scratch?
2. What scripts, references, assets would help with repeated use?

Example analysis:

• PDF rotation → scripts/rotate_pdf.py
• Frontend webapp → assets/hello-world/ template
• BigQuery queries → references/schema.md

Step 3: Initialize

python scripts/init_skill.py <skill-name> --path <output-directory>

Creates:

• Skill directory with SKILL.md template
• Example scripts/, references/, assets/ directories
• Placeholder files to customize or delete

Step 4: Edit

Write SKILL.md and implement resources:

Frontmatter:

• name: Hyphen-case identifier
• description: Complete "what + when" explanation (max 1024 chars)

Body:

• Imperative/infinitive form throughout
• Prefer concise examples over verbose explanations
• Reference bundled files when relevant

Step 5: Package

python scripts/package_skill.py <path/to/skill-folder> [output-directory]

Automatically validates, then creates .skill file (zip format).

Step 6: Iterate

Use skill on real tasks → observe struggles → update → re-test.

Testing Methodology (TDD-Adapted)

Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

RED Phase: Establish Baseline

Run pressure scenarios WITHOUT the skill:

• Document exact behavior
• Capture rationalizations verbatim
• Identify patterns in failures

GREEN Phase: Write Minimal Skill

Write skill addressing those specific failures:

• Don't add content for hypothetical cases
• Run scenarios WITH skill
• Verify compliance

REFACTOR Phase: Close Loopholes

Agent found new rationalization?

• Add explicit counter
• Build rationalization table
• Create red flags list
• Re-test until bulletproof

See references/testing-methodology.md for complete testing process.

What NOT to Include

A skill should ONLY contain essential files:

DO NOT create:

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md

The skill is for an AI agent, not a human reader.

Progressive Disclosure Patterns

Pattern 1: High-Level Guide with References

# PDF Processing

## Quick start
[Code example]

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)

Pattern 2: Domain-Specific Organization

bigquery-skill/
├── SKILL.md (overview + navigation)
└── reference/
    ├── finance.md (revenue metrics)
    ├── sales.md (pipeline data)
    └── product.md (usage analytics)

Claude only loads relevant domain file.

Pattern 3: Conditional Details

## Editing documents
For simple edits, modify XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Important Guidelines

• Keep references one level deep from SKILL.md
• Add TOC to files >100 lines
• Keep SKILL.md under 500 lines

Anti-Patterns

Anti-Pattern	Why Bad
Windows-style paths (scripts\helper.py)	Breaks on Unix
Too many options	Confusing - provide default with escape hatch
Narrative examples ("In session 2025-10-03...")	Too specific, not reusable
Multi-language dilution	Mediocre quality, maintenance burden
Generic labels (helper1, step2)	Labels need semantic meaning
Verbose explanations	Wastes tokens - Claude already knows

Quality Checklist

Core:

• Description includes WHAT + WHEN
• Description in third person
• SKILL.md under 500 lines
• No time-sensitive information
• Consistent terminology
• File references one level deep

Scripts:

• Handle errors explicitly (don't punt to Claude)
• No "magic numbers" (all values justified)
• Required packages listed
• No Windows-style paths

Testing:

• Baseline behavior documented (RED)
• Skill addresses specific failures (GREEN)
• Loopholes closed (REFACTOR)

Utility Scripts

Initialize New Skill

python scripts/init_skill.py <skill-name> --path <output-directory>

Validate Skill

python scripts/validate_skill.py <skill-directory>

Package Skill

python scripts/package_skill.py <path/to/skill-folder> [output-directory]

Further Reference

• references/frontmatter-reference.md - Complete frontmatter documentation
• references/patterns.md - Workflow and output patterns
• references/testing-methodology.md - Full TDD testing process