create-skill

Create Skill

Create new agent skills with specification-driven generation, live documentation fetching, and interactive planning.

Writing Philosophy

Apply these when drafting the generated skill's description and body in Phase 4: they make the difference between a skill that works once vs. one that works reliably across varied inputs:

Descriptions lead with use case. Open with the concrete use case, then the trigger phrases a user would actually type: third person, WHAT the skill does + WHEN to use it. If a sibling skill covers adjacent territory, add one "Not for X (use )" clause per real overlap: that single clause prevents more wrong triggers than three extra trigger phrases. Cap at 1024 chars (the bundled validator enforces it).

Explain WHY only at hard boundaries. Add reasoning only where an agent would otherwise plausibly do the wrong thing (e.g. "fetch live specs: cached docs go stale within weeks"). Everywhere else, a plain imperative ("Run the validator.") is faster to read and no less correct. Justifying every line is noise, not guidance.

Keep it lean; reserve ALL-CAPS for true invariants. Remove instructions that aren't pulling their weight: a 100-line skill often beats a 500-line skill diluted with edge cases that never occur. CRITICAL/MUST/ALWAYS/NEVER should mark the handful of things that really are non-negotiable; a word repeated ten times protects nothing.

Generalize, don't overfit: Skills designed only around their own test examples fail in practice. Design for the pattern, not the specific instance. Ask: "Would this instruction still apply if the user's request looked different?"

Mine conversations first: Users rarely articulate needs perfectly upfront. Extract information they've already provided before asking more questions.

Refusal and precondition paths end at the question. When the generated skill needs the user to resolve an ambiguity or confirm before a destructive step, its instruction should stop at asking: never "ask, then proceed anyway if there's no reply." A non-interactive eval run can't pause mid-task; a skill written to assume it can either hangs or silently guesses.