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

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.

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. Interpret static scores as structure and authoring signals, not proof that a skill works. Exact checks live in audit checks, authoring doctrine, and Codex parity.

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 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 source substitutes only for a faithful statement of that source, not a wider generalization. Use Research's pattern mode when the claim needs exemplars and a holdout before packaging.

A proposed process artifact must have a concrete consumer, a subject or release decision it informs, an observed defect and a retirement condition. If any is missing, omit the artifact. Code written only to consume it supplies no consumer. Minimal recovery state needs a named evidence-loss or corruption risk. Show a negative/holdout case and how the proposed rule returns the right decision.

Return the proposal inline unless a durable proposal was requested. Respect Memory's source and destination rules for mined material. Evidence cannot publish itself as policy. Build an artifact only when the caller's authorization includes adoption; a proposal-only request ends with the proposal. Repair ordinary known defects within existing authority; tool failures remain explicit facts for the native caller, not an automatic helper chain.

For an actual package edit, use the source template for required fields and context density guidance when deciding which prose earns a place. Neither requires adding a new skill.