Skill Curator

Skill Curator

Purpose

Build a small set of high-leverage skills rather than a pile of overlapping Markdown. A skill earns its permanent description only when it changes routing or execution behavior for a distinct, recurring workflow.

For the authoring mechanics and context-load rules, read writing-for-agents first. Use operator-execution when the skill work itself is part of a larger task.

Workflow

1. Inventory the behavior. Search installed skills, project instructions, scripts, and recurring requests for an actual workflow gap.
   • Done when the gap is stated as a trigger → outcome → verification triplet and existing coverage is known.
2. Choose the cheapest shape. Extend a current skill when the trigger and workflow overlap; otherwise create a new SKILL.md. Put long examples, prompt collections, checklists, and branch-only material in references/.
   • Done when the new context load is justified and every file has one job.
3. Write the execution surface. Use YAML frontmatter with a trigger-specific description; then provide an ordered workflow, checkable completion criteria, failure handling, and a verification gate. Prefer concrete verbs, paths, commands, and observable outputs.
   • Done when an unfamiliar agent can execute the workflow without generic advice.
4. Validate and prune. Parse frontmatter, check links, test the trigger phrases against likely user wording, and remove duplicate, stale, or no-op instructions.
   • Done when every rule changes behavior and every reference resolves.
5. Register only what is discoverable. Ensure the intended loader scans the location. Update an index or router only when it is the authoritative discovery surface; avoid repeating the same skill list across global instructions.
   • Done when a fresh session can discover the skill by the intended trigger.

Quality Rules

• The description is a routing contract: lead with Use when, name distinct trigger branches, and state the resulting action.
• One skill has one primary job. Split only when the trigger or execution path is independently reusable.
• Put universal workflow steps in SKILL.md; progressively disclose reference tables and templates.
• End steps with an observable done condition, not "be thorough" or "understand the task."
• Prefer positive instructions describing the desired behavior over large prohibitory lists.
• Add prompts only when they create a reusable, parameterized work order; a prompt must specify outcome, constraints, and proof.

Review Matrix

Apply references/skill-quality-gate.md before keeping a skill. A skill that fails the overlap, trigger, or verification checks is revised or deleted rather than added to the catalog.

Completion Gate

• Existing skills were searched before creating a sibling.
• Frontmatter begins at byte zero and name plus description are present.
• Trigger phrases distinguish the skill from adjacent skills.
• Each workflow step has a checkable completion condition.
• Every Markdown link resolves locally.
• The skill was placed in a directory scanned by its target agent.
• The final reply names every added or changed path and validation performed.

Common Failure Modes

• Taxonomy bloat: consolidate adjacent skills under one strong trigger and use headings or references for branches.
• Generic prompts: replace exhortations with inputs, an expected artifact, and a verification command.
• Stale indexes: point to the canonical skill root instead of copying a catalog into multiple global files.
• Prompt-only skills: write a workflow around the template so the agent knows when and how to validate its output.
• Unverifiable guidance: express the expected observable result or a command that proves it.