/skill-creator

name: skill-creator
description: >
  Create, improve, and evaluate agent skills (SKILL.md plus reference files). Use this
  skill whenever the user wants to build, scaffold, or design a new skill, improve or
  fix an existing skill that isn't working well, score or benchmark a skill's quality
  or run evals on it, or turn a repeated manual workflow into a skill ("I keep doing
  X manually", "can you remember how to do X", "turn this into a skill").

Skill Creator

Create, evaluate, and iterate on high-quality agent skills. This skill covers the whole 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 precise, not long. Its description routes the right requests to it. Its body gives the model the context it can't get anywhere else — the environment, tool contracts, defaults, domain judgment, and the reasons behind each constraint — and leaves out what a capable model already does on its own. Current Claude models follow instructions closely and literally, so every line gets acted on: an over-scripted or shouting skill produces rigid, over-cautious output, while a clear goal and quality bar let the model plan the work itself. `references/writing-guide.md` covers this in detail.

**Runtime adaptation:** Skills that touch external tools should detect what is installed, authenticated, and reachable at runtime and adapt, rather than assuming a single method. Offer fallback paths where real alternatives exist. See `references/dynamic-calling.md` for the 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 output contract | | 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 | Shape | Example | |---|---|---|---| | **Linear** | Single workflow, no branching | Setup → fetch → analyze → respond | earnings-preview | | **Router** | Multiple sub-tasks under one umbrella | Setup + routing table + sub-skills | stock-correlation (4 sub-skills), etf-premium | | **Methodology** | Formal domain framework with real gates | Ordered checks, each able to stop the analysis | sepa-strategy | | **Widget** | Generates interactive UI output | Extract → compute → render → explain | options-payoff | | **API Wrapper** | Wraps an external API with many endpoints | Auth + endpoint map + heavy references | fintel-data |

Plan the Outline

Every skill has three parts:

1. **Setup / detection** — detect available tools, auth state, and runtime environment, and decide which method to use. Skills with no external dependencies can skip this. 2. **The work** — numbered steps where the order genuinely matters (fetch before compute, a gate that can end the analysis), plus the judgment the model has to exercise, stated as goals, criteria, and domain heuristics rather than a script. 3. **Respond to the user** — the output contract: what the answer leads with, what it must contain, which caveats apply, and any verdict scale.

If a skill needs more than about nine steps, split it or use the Router pattern.

Plan the Detection Flow

Skills that touch external tools should 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 a **decision tree** that the rest of the skill follows — check rather than assume.

Plan Reference Files

Decide what goes in SKILL.md vs references/:

| In SKILL.md (under ~250 lines) | In references/ | |---|---| | Workflow and decision points | Detailed API documentation | | Routing/decision tables | Code templates (>20 lines) | | Parameter defaults table | Formulas and edge cases | | Output contract | Troubleshooting database | | Quick examples (1-3) | Comprehensive examples (4+) and dated datasets |

---

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` (max 1024 chars, no angle brackets) are required. The description is routing text that rides along