Skill Builder — Create, heal, and audit skill packages

skill-builder owns the full structural lifecycle of one skills/<slug>/ source package: create it, verify its structure, repair owned projections, and audit its content discipline. It does not schedule work, allocate writers, operate Git, validate a software candidate, promote learnings, or decide what happens after a failure.

Before creating a new root, search skills/*/SKILL.md for an existing owner. Extend an existing skill when it already owns the requested behavior.

Modes

Trigger phrases	Mode	Entry point
"create a skill", "scaffold skill", "new skill"	create (build)	scripts/build.sh
"absorb external skill"	create (absorb-external)	scripts/build.sh
"check skill package"	check	scripts/heal.sh --check [--strict]
"heal skill", "repair skill hygiene"	heal	scripts/heal.sh --fix
"audit skill structure"	audit	scripts/audit.sh

Constraints

• Create exactly one source package because metadata must have one canonical owner.
• Treat external skills as structural signals only because clean-room output must not copy names, prose, prompts, scripts, or examples.
• Regenerate projections once and stop because validation, revision, Git, and delivery remain caller-owned.
• Check and audit modes never mutate files; fix mode changes only an explicit source target and its owned projections, because source behavior remains human-authored.

Create mode

Choose exactly one build input:

• from-scratch <slug> creates a blank source package.
• from-template <slug> --like <existing-slug> uses the existing skill only for metadata defaults; it does not copy its prose.
• absorb-external <slug> --from <path> verifies the source exists, then creates a clean-room blank package without copying names, prose, prompts, scripts, or examples.

The caller may set SKILL_TIER, SKILL_DEPENDENCIES, SKILL_CAPABILITIES, and SKILL_EFFECTS. Values that represent lists must be JSON arrays.

Procedure

1. Run scripts/build.sh with one mode and one new slug.
2. Fill the generated placeholders with the skill's actual behavior.
3. Run scripts/heal.sh --check --strict skills/<slug>.
4. Run scripts/generate-skill-mesh.py to derive the catalog, registry, router, graph, maps, counts, and runtime image manifests from SKILL.md metadata.
5. Run scripts/codex-sync.sh --only <slug> and scripts/regen-codex-hashes.sh --only <slug> to derive the Codex twin.
6. Inspect the generated diff. Validation and delivery remain caller-owned.

build.sh performs steps 1, 3, 4, and 5 once. It never retries or chooses a next action.

Heal and check modes

bash skills/skill-builder/scripts/heal.sh --check [skills/<slug> ...]
bash skills/skill-builder/scripts/heal.sh --check --strict [skills/<slug> ...]
bash skills/skill-builder/scripts/heal.sh --fix [skills/<slug> ...]

Every explicit target must be a real, direct child of skills/ or skills-codex/. Missing paths, traversal, and symlink spellings are rejected.

Procedure

1. Resolve and contain all requested target directories.
2. Parse each SKILL.md frontmatter.
3. Check the path/name match, description, API version, disposition metadata, and linked local references.
4. Print every finding once.
5. In --fix mode only, regenerate metadata-owned projections and scoped Codex twins, then stop.

--check is read-only. --strict makes any finding produce exit 1. A failed fix is returned to the caller; the skill does not retry or select another action. Structural findings are printed as:

[FINDING_CODE] skills/example: concrete explanation

Generated Codex parity follows codex-parity.md. A second identical fix is idempotent, and remaining non-fixable findings stay explicit.

Audit mode

The optional read-only deep content audit is:

bash skills/skill-builder/scripts/audit.sh [--strict] [--json <path>] skills/<slug>

It combines the structural result with deterministic authoring checks and an advisory static package-readiness score. It is not the core Validate phase, does not write a verdict.v2, and has no delivery authority. Check definitions live in audit-checks.md; density scoring is described in context-density-checks.md.

Output

A created source package contains:

skills/<slug>/
├── SKILL.md
└── scripts/validate.sh

The build report is .agents/scratch/skill-builder/<slug>-build.json and conforms to schemas/build-report.json. Deep audit JSON conforms to schemas/audit-report.json. Generated inventories and runtime projections are not additional sources of truth. The caller owns any subsequent edit or invocation.

Checks

• The slug and frontmatter name match.
• Metadata declares tier, dependencies, capabilities, effects, canonical_status, and disposition.
• Every hard dependency names a live skill.
• The generated package contains no Git, tracker, queue, retry, release, or delivery behavior.
• External material is treated only as a signal that a clean-room skill may be useful; its content is not copied.
• Check mode never mutates files; fix mode changes only an explicit source target and its owned projections.

Failure behavior

Any invalid input, structural failure, projection failure, or Codex sync failure exits nonzero after one attempt. The caller decides whether to revise or invoke the builder again.

References

• skill template
• authoring doctrine — prose-quality principles behind the advisory authoring audit block
• heal.feature
• skill-auditor.feature