Skill Creator
Core Principle
Skills are onboarding guides for AI agents. They transform a general-purpose agent into a specialized one with procedural knowledge no model fully possesses. The context window is a shared resource — every token must earn its place.
Anatomy of a Skill
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter: name + description (required)
│ └── Markdown body: instructions and guidance
└── Bundled Resources (optional)
├── scripts/ — Executable code for deterministic tasks
├── references/ — Documentation loaded into context as needed
└── assets/ — Files used in output (templates, images, fonts)
SKILL.md Front Matter (Required)
---
name: kebab-case-name
description: What the skill does and when to use it. Include trigger
conditions — this is the primary mechanism for skill activation.
---
The description field is what the AI reads to decide whether to activate the skill. Put ALL "when to use" information here — not in the body (the body is only loaded after triggering).
SKILL.md Body
Instructions for using the skill. Written for an AI agent, not a human user.
Default assumption: The AI is already very smart.
Only add context it doesn't already have.
Challenge each piece of information:
→ "Does the AI really need this explanation?"
→ "Does this paragraph justify its token cost?"
Degrees of Freedom
Match specificity to fragility:
| Freedom | When | Example |
|---|---|---|
| High (text instructions) | Multiple valid approaches, context-dependent | "Choose a testing strategy appropriate for the project" |
| Medium (pseudocode/scripts with params) | Preferred pattern exists, some variation OK | Template with configurable sections |
| Low (specific scripts, few params) | Fragile operations, consistency critical | Exact XML manipulation steps for .docx editing |
Think of the AI exploring a path: narrow bridge with cliffs needs guardrails (low freedom), open field allows many routes (high freedom).
Progressive Disclosure
Skills use three levels to manage context efficiently:
Level 1: METADATA (always in context)
→ name + description (~100 words)
→ Used to decide if skill triggers
Level 2: SKILL.md BODY (loaded when skill triggers)
→ Core instructions (<500 lines)
→ Workflows, decision trees, essential examples
Level 3: BUNDLED RESOURCES (loaded as needed)
→ scripts/ — can be executed without reading into context
→ references/ — loaded only for relevant sections
→ assets/ — used in output, never loaded into context
Splitting Patterns
When SKILL.md approaches 500 lines, split content:
# Main Skill
## Quick Start
[Essential workflow here]
## Advanced Features
- **Form filling**: See [FORMS.md](FORMS.md)
- **API reference**: See [REFERENCE.md](REFERENCE.md)
For skills with multiple domains or variants:
skill-name/
├── SKILL.md (overview + navigation)
└── references/
├── aws.md — loaded only for AWS tasks
├── gcp.md — loaded only for GCP tasks
└── azure.md — loaded only for Azure tasks
Skill Creation Process
Step 1: Understand with Concrete Examples
Ask:
→ What functionality should this skill support?
→ What are 3-5 example prompts that would trigger it?
→ What would a user say that should activate this skill?
→ What does the AI need to know that it doesn't already?
EXIT: Clear sense of the skill's scope and trigger conditions.
Step 2: Plan Reusable Contents
For each example prompt, ask:
→ What code would I write from scratch each time?
→ Put in scripts/
→ What reference material would I look up each time?
→ Put in references/
→ What templates or assets would I start from each time?
→ Put in assets/
Most skills only need SKILL.md. Don't create empty directories.
Step 3: Write the Skill
FRONT MATTER:
→ name: kebab-case, matches directory name
→ description: comprehensive trigger conditions
BODY STRUCTURE (Solo Unicorn Builder convention):
## Core Principle — One sentence philosophy
## [Main Sections] — Workflows, patterns, examples
## Anti-Patterns — Table: Anti-Pattern | Why | Do This Instead
## Power Move — A prompt that showcases the skill's full power
STYLE:
→ Imperative/infinitive form ("Use X" not "You should use X")
→ Concise examples over verbose explanations
→ Tables for structured comparisons
→ Code blocks for anything copy-pasteable
Step 4: Test and Iterate
1. Use the skill on 2-3 real tasks
2. Note where the AI struggles or guesses wrong
3. Add the missing context to SKILL.md or references/
4. Remove anything the AI didn't need
5. Repeat until the skill reliably produces good results
What NOT to Include
DO NOT create:
→ README.md (the skill IS the documentation)
→ INSTALLATION_GUIDE.md
→ CHANGELOG.md
→ Test files for the skill itself
→ User-facing documentation (skills are for AI agents)
The skill contains only what an AI agent needs to do the job.
Anti-Patterns
| Anti-Pattern | Why It Hurts | Do This Instead |
|---|---|---|
| "When to use" in the body instead of description | AI never sees it before triggering | Put ALL trigger conditions in the YAML description |
| Explaining things the AI already knows | Wastes context window tokens | Only add knowledge the AI doesn't have |
| One massive SKILL.md with everything | Context window bloat on every activation | Progressive disclosure — split into references/ |
| Empty scripts/, references/, assets/ dirs | Clutter, confusing | Only create directories you need |
| Deeply nested reference files | Hard for AI to discover and navigate | Keep references one level deep from SKILL.md |
| Writing for human users | Wrong audience — skills are for AI agents | Write instructions the AI can follow, not tutorials |
Power Move
"Create a new skill for [domain/task]. Start by listing 5 example prompts that should trigger it. Then identify what knowledge the AI needs that it doesn't already have. Write the SKILL.md with front matter, core sections, anti-patterns table, and a power move prompt. Keep it under 300 lines."
The agent becomes your skill architect — packaging expert knowledge into reusable AI capabilities.