/skill-builder — Scaffold or absorb a new SKILL.md

Materializes a new skill against the unified template at references/skill-template.md (extracted from anthropics/financial-services). Runs skill-auditor on the new skill as a self-check before declaring success.

If unsure whether the work should be a skill, a Workflow, or an NTM swarm, run /automation-shape-routing first — it is the front door that decides the shape and hands off to the right builder.

⚠️ Critical Constraints

Template is canonical. All four modes produce SKILL.md files conforming to references/skill-template.md. Do not invent ad-hoc structures. Why: skill-auditor validates against this template; drift creates auditor false-fails.
Self-audit is mandatory. After every successful build, the build script invokes /skill-auditor against the new skill directory. A FAIL verdict aborts the build. Why: PR-002 (external validation gate) — the builder must not declare its own work complete.
Codex parity is day-1, not later. from-scratch, from-template, and absorb-external modes must produce both skills/<name>/SKILL.md AND skills-codex/<name>/SKILL.md + skills-codex/<name>/prompt.md. Why: finding 2026-05-03-codex-skill-shape-is-dual-file — codex SKILL.md uses slim frontmatter (no skill_api_version); prompt.md is mandatory; audit-codex-parity.sh is a content scanner that won't catch frontmatter drift.
Editing an EXISTING skill also needs a manual twin mirror. When you change skills/<name>/references/*.md or SKILL.md, manually mirror the content into skills-codex/<name>/ (runtime-native), THEN run scripts/regen-codex-hashes.sh --only <name>. make regen-all only refreshes the twin's hash record, not its prose — a green ✓ codex hashes over a stale twin looks handled but isn't. Verify with a content diff (grep -c <new-token> on both copies), not the hash exit code. Why: finding 2026-06-16-codex-twin-content-not-auto-mirrored (age-aqu/age-yxl) — regen made the marker self-consistent with a stale twin (0-vs-2 token divergence) and nothing complained. The parity gate now blocks an un-mirrored references/** edit, but the mirror is still a manual step.
250-line ceiling on new SKILL.md. Use references/ for overflow. Why: finding f-2026-05-01-025 — every Skill() invocation reloads 5-15KB; multi-lifecycle sessions compound to 150-200KB+ pure scaffolding.
Clean-room factory inputs only. When using lessons learned from external corpora, read references/agentops-skill-factory.md and use only AgentOps-owned summaries, scripts, and rubrics. Why: productization must improve structure without copying protected third-party skill content.
Real gate means exit code. Validate with heal-skill --check --strict <skill-dir> and skill-auditor; never infer green from grep/regex output. Why: regex presence checks created false-greens during the 2026-06 scale build.
One skill directory = one writer. Bulk builds fan out only when each worker owns a distinct new skills/<name>/ plus skills-codex/<name>/; edits to existing skill dirs run in a later serial wave. Why: concurrent writers deleted untracked work and flipped HEAD mid-task.
Trust repository state, not subagent reports. Before declaring success, inspect git status, generated hashes, final files, and gate exit codes. Why: sandbox-overlay and stale self-reports can claim work that never persisted.
Clean-room includes names. Do not reuse exact third-party skill names; mint AgentOps-owned names before source skills, Codex mirrors, or wrappers are keyed. Why: provenance/IP safety applies to labels as well as prose and scripts.
Do not use the Workflow tool as the skill factory. For scale authoring, use deterministic wave scripts or NTM/Agent Mail lanes with one worker per skill. Why: skill creation needs file ownership and durable git evidence, not opaque background self-reporting.