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
- Run
scripts/build.sh with one mode and one new slug.
- Fill the generated placeholders with the skill's actual behavior.
- Run
scripts/heal.sh --check --strict skills/<slug>.
- Run
scripts/generate-skill-mesh.py to derive the catalog, registry,
router, graph, maps, counts, and runtime image manifests from SKILL.md
metadata.
- Run
scripts/codex-sync.sh --only <slug> and
scripts/regen-codex-hashes.sh --only <slug> to derive the Codex twin.
- 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
- Resolve and contain all requested target directories.
- Parse each
SKILL.md frontmatter.
- Check the path/name match, description, API version, disposition metadata,
and linked local references.
- Print every finding once.
- 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 quality 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
