Skill Builder

Design and maintain Claude/Codex skills as small, portable routers with clear triggers and minimal duplication.

Use This For

• Creating a new skill.
• Refactoring an overgrown SKILL.md.
• Auditing trigger wording, layout, or duplication.
• Migrating capability into or out of a skill layer.
• Deciding when stable workflow logic belongs in scripts/, a skill-local CLI in cli/, or a repo-owned CLI under tools/.

First Pass

1. Classify the request: create, update, audit, or migrate.
2. Run the confidence check: confident, partial, or not ready.
3. Name the evidence basis, procedural burden, and risk tier using references/skill-quality.md.
4. Choose scope: global or project-local, Claude or Codex or both.
5. Choose the operating surface:
   • skill prose
   • extracted reference
   • skill-local script
   • skill-local CLI in cli/
   • repo-owned CLI under tools/
6. If the surface is a skill-local CLI, hand off command contract, safety, and verification design to skill-cli-authoring.
7. Add lightweight eval cases from references/skill-evals.md when risk or behavior warrants it.
8. For mature or drifting skills, run the self-evolution checklist in references/self-evolution.md.

Router Rule

• Keep SKILL.md as the entrypoint and routing table, not the whole knowledge base.
• Prefer SKILL.md under 200 lines. Above 400 lines means refactor now.
• Keep the portable core to name + description.
• Put runtime-specific metadata beside the portable core, not inside it.
• Keep one source of truth for each fact or rule.
• Move deterministic, repeated logic into code once the pattern is verified.

Mode Selection

See references/workflows.md for the concrete workflow for each mode.

Confidence Gate

If the domain is only partially understood, prefer the Q&A-driven path in references/workflows.md.

Non-Negotiables

• The description must say when to use the skill, not summarize the workflow.
• Codex trigger quality depends heavily on description; make trigger phrases explicit.
• Do not duplicate the same rules across SKILL.md and references.
• Keep repo-specific operating rules out of the portable core when a local reference or wrapper skill is enough.
• A skill should externalize procedure, heuristics, and constraints; if it only stores context, route that context elsewhere.
• Higher-risk skills need stronger approval points, eval cases, and evidence before promotion.
• If capability moves into a skill layer, remove stale docs, workflows, or Task targets in the same change.
• If repo behavior changes, name the verification gate explicitly.
• If a skill-local CLI is warranted, first use skill-cli-authoring to design the command contract, safety model, and verification loop; then bootstrap it with your Go CLI scaffolder of choice and keep Task wrappers thin.

Choosing Code Instead Of Prose

Use prose when judgment is required. Use code when the pattern is deterministic and repeated.

• Repeated logic inside a skill: see references/pattern-to-script.md
• Skill-local operations with one skill boundary and a small command surface: see references/repo-owned-clis.md, then use skill-cli-authoring
• Shared repo operations with policy or verification requirements: see references/repo-owned-clis.md

References

Boundaries

• This skill designs and refactors skills; it does not make every repeated workflow a skill automatically.
• harness-router owns the cross-surface decision about whether a learning should become a skill at all.
• Do not keep repo-operating logic in the portable core when a repo-local reference or CLI is the correct owner.
• For destructive migrations or unclear ownership changes, confirm scope before rewriting multiple surfaces.