Create routable skill

Create Routable Skill

Create the smallest skill that reliably separates its intended requests from neighboring capabilities. Treat routing as a classification contract: metadata selects the skill; the body controls behavior only after selection. Use the system skill-creator for general construction mechanics and this skill for explicit routing design and evaluation.

Workflow

1. Establish concrete usage before creating files.

   • Collect or propose at least three requests that must select the skill.
   • Collect or propose at least three related requests that must reject it.
   • Identify the closest existing skills and state the decisive distinction for each.
   • Ask only for information that materially changes the design. Mark generated examples as assumptions.

2. Read references/routing-contract.md and draft a routing specification using references/spec-template.json.

   • Set mode to create or update.
   • For updates, read the existing frontmatter, record existing_skill_path, and preserve its canonical name unless the user explicitly authorizes a rename.

3. Validate the specification:

   python scripts/validate_routing_spec.py path/to/spec.json
   

4. Analyze installed skills before deciding to add a new one:

   python scripts/analyze_skill_catalog.py --candidate path/to/spec.json --format text
   

   Treat lexical scores as candidate-generation evidence, not semantic proof. Inspect every high-scoring skill. In update mode the analyzer excludes only existing_skill_path; same-name skills elsewhere remain visible as collisions. Prefer updating an existing skill when the proposed capability has no independent workflow, resources, or routing boundary.

5. Plan only reusable resources:

   • Put deterministic or repeatedly rewritten operations in scripts/.
   • Put detailed, conditionally needed knowledge in references/.
   • Put output templates or reusable binary material in assets/.
   • Keep essential execution instructions in SKILL.md; do not create auxiliary documentation.

6. Initialize a new skill with the official skill-creator/scripts/init_skill.py. Use the user-selected location; otherwise use $CODEX_HOME/skills, falling back to ~/.codex/skills. Skip initialization only when updating an existing skill.

7. Write the skill.

   • Use lowercase hyphen-case for the folder and name.
   • Put every pre-trigger signal in the frontmatter description: capability, concrete triggers, and decisive exclusions.
   • Do not rely on a body section named “When to use”; the body is unavailable before routing.
   • Keep the body procedural, concise, imperative, and below 500 lines.
   • Link every optional reference directly from SKILL.md and say when to read it.

8. Generate the executable routing fixture:

   python scripts/generate_routing_tests.py path/to/spec.json --output path/to/routing-tests.jsonl
   

9. Run the official quick_validate.py on the created skill, run every bundled script on representative inputs, and then forward-test realistic routing prompts in fresh contexts. Do not reveal the expected route to the test agent.

10. Iterate on the smallest boundary that explains failures. Do not inflate the description with unrelated synonyms to chase individual tests.

Decision Rules

• Create a distinct skill only when it has a coherent user intent, a repeatable workflow, and a defensible boundary.
• Extend an existing skill when the new behavior shares the same intent and differs only by a minor option or example.
• Defer ordinary Skill creation to skill-creator; own the request when routing reliability, trigger repair, catalog collisions, or routing evaluation is an explicit requirement.
• In update mode, preserve the exact existing lowercase canonical name and folder unless an authorized rename is part of the task.
• Create a plugin instead when the request is primarily packaging multiple skills, MCP servers, apps, or marketplace metadata.
• Treat multi-skill requests as composition: identify the primary skill, supporting skills, and handoff order.
• Separate routing quality from task quality. A successful final artifact does not prove that the correct skill was selected.
• Never claim embedding recall, Top-K ranking, or production router accuracy from the lexical analyzer in this skill.

Evaluation

Read references/evaluation.md when designing or interpreting routing tests. Require positive, negative, confusable, and composition coverage. Record false negatives, false positives, nearest-skill confusions, and the rank of the correct skill when a candidate list exists.

Completion Gate

Deliver a skill only when all of these are true:

• The routing specification validates without errors.
• Existing-skill conflicts were inspected and resolved or explicitly accepted.
• name and description alone express the routing contract.
• The official skill validator passes.
• Bundled scripts run successfully on representative inputs.
• Routing fixtures exist and fresh-context tests cover both selection and rejection.
• UI metadata still matches the final skill.