skill-creator

What this skill does

# Skill Creator

Create, evaluate, and iterate on high-quality agent skills. This skill guides the entire lifecycle: planning what the skill should do, writing SKILL.md and reference files, scoring quality against a rubric, and iterating until the skill meets production standards.

**Philosophy:** A great skill is not a long skill. It is a *precise* skill: exhaustive triggers, explicit defaults, clear steps with exit gates, deferred complexity via reference files, and a structured output template.

**Core rule — always dynamic, never static:** Skills MUST detect what tools, libraries, and auth are available at runtime and adapt their behavior accordingly. Never hardcode a single method. Always provide a detection flow with a decision tree and fallback paths. See `references/dynamic-calling.md` for the complete pattern catalog.

---

## Step 1: Understand What the User Wants

Classify the request into one of these modes:

| User Intent | Mode | Jump To |
|---|---|---|
| Create a brand-new skill | **Create** | Step 2 |
| Improve / fix an existing skill | **Improve** | Step 6 |
| Evaluate / score a skill's quality | **Evaluate** | Step 7 |

If ambiguous, ask: "Do you want to create a new skill, improve an existing one, or evaluate one?"

### Gather Requirements (for Create mode)

Before writing anything, answer these questions (ask the user if unclear):

| Question | Why it matters |
|---|---|
| What task does the skill automate? | Defines the core workflow |
| Who is the target user? | Determines complexity and terminology level |
| What tools/APIs/CLIs does it use? | Determines dependencies and platform restrictions |
| What does the user provide as input? | Defines parameters and defaults |
| What should the output look like? | Defines the response template |
| Does it need API keys or credentials? | Determines `required_environment_variables` |
| Should it work on Claude.ai or only CLI? | Determines platform field and dynamic commands |

---

## Step 2: Plan the Skill Architecture

Before writing SKILL.md, plan the structure. Read `references/architecture-patterns.md` for detailed guidance on each pattern.

### Choose a Structural Pattern

| Pattern | When to use | Steps | Example |
|---|---|---|---|
| **Linear** | Single workflow, no branching | 5-7 | earnings-preview, etf-premium |
| **Router** | Multiple sub-tasks under one umbrella | 3 + sub-skills | stock-correlation (4 sub-skills) |
| **Methodology** | Complex domain framework with sequential gates | 7-9 | sepa-strategy (9-step trading methodology) |
| **Widget** | Generates interactive UI output | 4-5 | options-payoff (extract + compute + render) |
| **API Wrapper** | Wraps an external API with many endpoints | 3-5 + heavy references | funda-data (5 steps, 8 reference files) |

### Plan the Step Outline

Write out the step names before writing content. Every skill should have:

1. **Detection flow** (Step 1) -- dynamically detect available tools, auth state, and runtime environment; build a decision tree for which method to use
2. **Core methodology** (Steps 2-N) -- the actual work, with pass/fail gates; each step that calls an external tool should have method alternatives based on what Step 1 detected
3. **Respond to user** (Final step) -- structured output template

Target **5-9 steps** total. More than 9 means the skill should be split or use a router pattern.

### Plan the Detection Flow

Every skill that touches external tools MUST start with a runtime detection flow. Read `references/dynamic-calling.md` for all patterns. The detection flow answers:

| Question | How to detect | Decision |
|---|---|---|
| Is the CLI tool installed? | `command -v tool` | CLI path vs Python fallback |
| Is the user authenticated? | `tool auth status` / `echo $API_KEY` | Skip auth setup vs guide through it |
| Which runtime has the library? | `import lib` in terminal vs execute_code | Route to correct runtime |
| Is a richer tool available? | `gh --version` vs `git --version` | Rich path vs minimal path |
| Is live data reachable? | `curl -s endpoint` | Live data vs cached/default |

The detection output feeds into a **decision tree** that the rest of the skill follows. Never assume — always check.

### Plan Reference Files

Decide what goes in SKILL.md vs references/:

| In SKILL.md (under ~250 lines) | In references/ |
|---|---|
| Step-by-step workflow | Detailed API documentation |
| Routing/decision tables | Code templates (>20 lines) |
| Parameter defaults table | Formulas and edge cases |
| Output format template | Troubleshooting database |
| Quick examples (1-3) | Comprehensive examples (4+) |

---

## Step 3: Write the SKILL.md

Read `references/writing-guide.md` for detailed instructions on writing each section. Read `references/frontmatter-guide.md` for the complete YAML field reference.

### Key Rules

1. **Frontmatter first**: `name` (lowercase-hyphenated, max 64 chars) and `description` (exhaustive trigger list, max 1024 chars) are required. Description needs 5+ triggers including sideways entry points.

2. **Step 1 = detection flow**: Use `!`command`` with fallbacks to detect available tools, auth state, and runtime. Build a decision tree with multiple method paths (e.g., CLI preferred, Python fallback, built-in tools last resort). Never hardcode a single tool — always detect and adapt. See `references/dynamic-calling.md`.

3. **Core steps with method alternatives**: Each step that calls an external tool should offer at least 2 paths based on what Step 1 detected. Use pattern: "If `TOOL_A` detected → Method 1, otherwise → Method 2." Each step gets `## Step N: [Verb] [Object]`, a decision table if routing, a pass/fail gate if evaluative, and a reference pointer for deep content.

4. **Defaults table**: Every parameter MUST have an explicit default. No skill should ever stall waiting for input.

5. **Final step = output template**: Number every output section. Specify exactly what data goes in each. Include a verdict/grade system if evaluative.

See `references/skill-examples.md` for annotated examples of each pattern.

---

## Step 4: Write Reference Files

Read `references/writing-guide.md` for the full reference file authoring guide.

### Key Rules

1. **Naming**: `lowercase-hyphenated.md`, one file per concept-cluster
2. **Size**: Quick lookup 50-150 lines, deep guide 150-400 lines, catalog 400-900 lines
3. **Structure**: H1 title, H2 sections, code blocks, tables, edge cases section at end
4. **Linking**: Use backtick paths in SKILL.md steps and a `## Reference Files` section at the end

---

## Step 5: Quality Check Before Delivery

Run the skill through the quality rubric in `references/quality-rubric.md`. Score each dimension.

### Quick Checklist

- [ ] Frontmatter has `name` and `description` (both required)
- [ ] Description has 5+ distinct trigger phrases
- [ ] Description includes sideways entry points
- [ ] SKILL.md is under 300 lines (ideally under 250)
- [ ] Every parameter has an explicit default
- [ ] Steps are numbered (## Step N: ...)
- [ ] Each step has a clear exit condition or deliverable
- [ ] Final step specifies exact output structure with numbered sections
- [ ] Complex content is in reference files, not inline
- [ ] Reference file pointers use backtick paths
- [ ] Step 1 has a detection flow with `!`command`` checks and fallbacks (`|| echo "..."`)
- [ ] Detection flow produces a decision tree with 2+ method paths
- [ ] Core steps adapt behavior based on detection results (not hardcoded to one tool)
- [ ] Separate runtimes treated as separate environments (terminal vs execute_code)
- [ ] Legal/ethical disclaimers included where appropriate
- [ ] No hardcoded ticker lists, tool paths, or static data that will go stale

If any item fails, fix it before delivering to the user.

---

## Step 6: Improve an Existing Skill

When the user asks to improve a skill:

### 6a: Read the Current Skill

Load the skill with `skill_view(name)` or read the SKILL.md directly. Also rea