/skill-builder

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 incomplete source package containing only SKILL.md; helpers, references and assets are conditional on the actual behavior. An inline answer needs no output file. State applicability, inputs, authority, result, completion and failure in the layout that makes them clear.

The shell entrypoints delegate creation and source checks to ao skills build and ao skills check-source. Development checkouts run their Go source; installed packages need an ao built from this version. Tests can set AO_SKILL_BUILDER_BIN to an explicit binary. Build JSON goes to stdout. To save it, pass --report /absolute/external/directory/build.json in an existing protected non-Git directory. Existing report paths are never replaced. The build-report schema retains its old fields, permits a one-file source list, and adds authoring_state: scaffold and semantics_evaluated: false. structure_check_pass describes mechanical creation/projection only, even when true. There is no default workspace report; consumers of the former .agents/scratch/skill-builder/ path must select a report destination or read stdout. Creation wrapper syntax errors remain exit 2; Go rejects invalid creation inputs and existing destinations with exit 1. This includes invalid slugs and missing template/external inputs that the old initializer classified as usage errors. Successful creation remains exit 0 and always reports scaffold state. Check/heal target errors remain exit 2; strict source findings remain exit 1.

Replace placeholders and remove metadata.authoring_state: scaffold only after authoring the behavior. Strict source checks reject that explicit incomplete state. Removing it is an author assertion, not proof of semantic completeness; a fresh reviewer must judge the actual behavior.

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.

Creation is staged, not atomic across source, catalogs, projections and reports. If a later stage fails, retain the created source and any report, capture the command's exit and diagnostic, and inspect which outputs exist. Report source creation separately from projection/check completion. structure_check_pass: false does not mean no files were created; a report-write failure can also leave source behind. Never call that partial result a completed package or remove it just to rerun creation. An existing target is deliberately rejected.

Recover from the observed stage within existing authority: repair the named obstruction, finish authoring the retained source if it is still a scaffold, then run the strict source check, owning projection commands and audit above. Retain the failed report as evidence and use a new authorized report path if one is needed. Verify the retained source and final generated output; report remaining failures instead of resetting completion history. Missing required scripts, references or runtime support block their dependent operation; name that resource and continue only work that does not depend on it.

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 defaults to skill-audit.v2: separate static conformance, located effect observations, behavioral evidence and non-gating authoring suspicions. There is no total, rating or aggregate quality verdict. Effects and behavior remain NOT_PROVEN: this command runs no skill or trial. Profile selection follows package location, or explicit --profile; canonical source metadata is not portable host metadata. Installed host behavior and invocation policy still need their own checks.

Exit 0 means the selected static checks found no conformance defect, not that the skill is safe or effective. Exit 1 means a concrete conformance failure; exit 2 means invalid invocation, input or report destination. --strict does not promote wording suspicions to failures. Default output is JSON on stdout. --json creates a new report only in an existing external non-Git directory, never overwrites one.

Consumers needing the old verdict, pass1, pass2, density, rubric, craft and authoring fields must explicitly use --legacy and audit-report-legacy.json. That opt-in preserves the accepted old schema, scores and exit behavior, including nonblocking canonical lexical WARNs under --strict and the external-observation strict behavior. Do not use legacy scores to rank or optimize packages. Shared trigger CI remains unchanged. Remove compatibility only when the remaining field consumers migrate.

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.