/skill-builder

name: skill-builder
description: 'Create, adapt, consolidate or repair skill packages and projections. Use when: authoring guidance, descriptions or structure; Skill Eval measures behavioral benefit.'
practices:
- pragmatic-programmer
- refactoring
hexagonal_role: supporting
consumes: []
produces:
- skill-source-package
- skill-hygiene-report
- converted-skill
- operationalization-proposal
context_rel: []
skill_api_version: 1
user-invocable: true
context:
  window: fork
  intent:
    mode: questions
  sections:
    exclude:
    - HISTORY
metadata:
  capabilities: [skill_builder, heal_skill, export_skill, distill_expertise]
  effects: [write_skill_source, write_build_report, regenerate_skill_projections, repair_skill_projections, write_converted_skill_projection, write_advisory_proposal]
  canonical_status: canonical
  disposition: keep_specialist
  tier: meta
  dependencies: []
  stability: experimental
output_contract: build-report.json for creation, audit-report.json for audit, target-valid exported files for conversion, or an advisory expertise proposal

Skill Builder

Create, repair, audit or export one canonical skill package, or turn supported expertise into a small authoring proposal. Search existing owners before adding a root. Extend the owner that already handles the behavior.

Choose the requested operation

| Need | Entry point | |---|---| | Create a source package | `scripts/build.sh` with `from-scratch`, `from-template` or `absorb-external` | | Check package structure | `scripts/heal.sh --check [--strict] skills/<slug>` | | Repair owned projections | `scripts/heal.sh --fix skills/<slug>` | | Audit authoring quality | `scripts/audit.sh [--strict] [--json <path>] skills/<slug>` | | Export to another platform | [Conversion](#conversion) | | Make repeated expertise reusable | [Distill expertise](#distill-expertise) |

Run only the selected operation. Skills remain optional tools within the native caller's authorized outcome; this skill does not add execution phases, own work, operate Git, validate a software candidate, or decide delivery and retries.

Create and maintain

Treat external skills as structural signals only. Clean-room output must not copy their names, prose, prompts, scripts or examples. `from-template` reuses metadata defaults; `absorb-external <slug> --from <path>` verifies an input and creates a blank source package. Neither imports another skill's content.

For creation, supply one input to `scripts/build.sh`, then replace placeholders with the actual behavior. The caller can supply `SKILL_TIER`, `SKILL_DEPENDENCIES`, `SKILL_CAPABILITIES` and `SKILL_EFFECTS`; lists are JSON arrays. The result is one source package with `SKILL.md` and `scripts/validate.sh`. The builder's report is `.agents/scratch/skill-builder/<slug>-build.json` under [build-report.json](schemas/build-report.json).

Edit `skills/<slug>/` as the source owner. Check the completed source with `scripts/heal.sh --check --strict skills/<slug>`, then regenerate its owned projections through the repository's owning commands. `scripts/regen-all.sh` is the integrated projection recipe; `scripts/generate-skill-mesh.py`, `scripts/codex-sync.sh --only <slug>` and `scripts/regen-codex-hashes.sh --only <slug>` are the existing scoped surfaces. Do not repeat work already performed by `build.sh` unless source changes require it. Inspect the generated diff; hand-edit no projection.

Check/heal targets must be real direct children of `skills/`; reject missing paths, traversal and symlink spellings. Check mode is read-only. Fix mode regenerates owned projections for explicit targets and does not invent source behavior. Findings name their code, target and concrete issue; `--strict` returns nonzero for findings. Check the slug/name match, description, API version, metadata, live dependencies and linked resources.

Deep audit reports structural and advisory authoring findings; it is not a candidate verdict. Its optional JSON follows [audit-report.json](schemas/audit-report.json). Interpret static scores as structure and authoring signals, not proof that a skill works. Exact checks live in [audit checks](references/audit-checks.md), [authoring doctrine](references/authoring-doctrine.md), and [Codex parity](references/codex-parity.md).

Conversion

Use `bash skills/skill-builder/scripts/converter/convert.sh <skill-dir> <target> [output-dir]` for an explicit out-of-tree export. Targets are `codex`, `cursor` and `test`; `--all` selects all source packages, and `--codex-layout inline` selects the legacy inline Codex layout. Read [SkillBundle](references/converter/skill-bundle-schema.md) when format details matter. Parse the source once, render the target, then validate resource parity and target format. Report layout and any omitted Cursor references.

The default export is `.agents/projections/converter/<target>/<skill-name>/`. The exporter clean-writes its output directory, so use only the explicit derived target: refuse a source package, its ancestor, or the repository root. Preserve the source unchanged and fix the source or adapter instead of editing output. A parse, write, format or required-resource failure leaves an incomplete export. The shipped `skills-codex/**` remains owned by `scripts/codex-sync.sh` through `scripts/regen-all.sh`; this ad-hoc exporter never replaces that authority.

Distill expertise

When the caller wants a reusable rule, begin with cited occurrences or a named authoritative source. State the trigger, desired behavior, inputs, outputs, negative example and limits. Prefer an addition to an existing reference or skill over a new root, library, gate or workflow; no action is a valid result.

An abstraction needs three independently evidenced real occurrences and a successful reapplication to a source case without missing context. Preserve short source excerpts or command results with resolvable citations. Fewer occurrences support a narrow reference note; an authoritative