/skill-builder

name: skill-builder
description: 'Create, repair, audit or consolidate agent skills (SKILL.md packages). Use when: writing or fixing a skill, its description or structure. Not for one-off lessons; use Memory.'
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
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. Before writing anything new, decide from evidence whether anything new is warranted: a request for a new skill, gate or tracking file usually ends as a short addition to an existing owner, or as no change.

Decide whether to create anything

Apply these before any creation step, including when the request already names the new skill or file it wants:

1. **Find the existing owner.** Search skills, references, checklists and instruction files for one that already handles the behavior. Extend that owner rather than adding a root. 2. **Count independent occurrences.** A new skill, gate, library or workflow needs three independently evidenced real occurrences and a successful reapplication to a source case without missing context. Fewer occurrences support only a narrow note in an existing owner; one incident is an observation, not a skill. An authoritative source supports only a faithful statement of that source. 3. **Name the consumer of every new artifact.** A proposed process artifact (a report, ledger, counter, dashboard or tracker) needs a concrete consumer, the decision it informs, the observed defect it answers and a retirement condition. If any is missing, leave it out; code written only to consume it is no consumer. 4. **No action is a valid result**, and so is a short addition to an existing owner. Say what the evidence supports before drafting, build only what the caller then authorizes, and return a proposal inline unless a durable one was requested. 5. **A built package proves no benefit.** Route behavioral benefit to [Skill Eval](../skill-eval/SKILL.md) and acceptance judgment to [Validate](../validate/SKILL.md).

The result shows it worked when it names the existing owner it searched, the number of independent occurrences found, and either no new file or exactly the package the caller authorized.

Choose the requested operation

`<skill-dir>` is the directory that contains this SKILL.md. Claude Code shows it as "Base directory for this skill"; Codex lists this skill's SKILL.md path; in an AgentOps source checkout it is `skills/skill-builder`. Replace `<skill-dir>` with that absolute path before running a command. The working directory stays the user's repository. If the host did not show where this skill is installed, use the directory of the SKILL.md you read. If you cannot determine it, do not guess a path or run a same-named script from the current repository; say the bundled script is unavailable and apply the rules and doctrine here to the package by hand and use its repository's own checks.

| Need | Entry point | Runs only with | |---|---|---| | Create a source package | `bash "<skill-dir>/scripts/build.sh" from-scratch <slug>`, `from-template <slug> --like <existing-slug>` or `absorb-external <slug> --from <path>` | an AgentOps source checkout with Go | | Check package structure | `bash "<skill-dir>/scripts/heal.sh" --check [--strict] skills/<slug>` | Go in a source checkout, or `ao` 3.9 or later elsewhere | | Repair the skill mesh | `bash "<skill-dir>/scripts/heal.sh" --fix skills/<slug>` | an AgentOps source checkout with Go | | Inspect audit evidence | `bash "<skill-dir>/scripts/audit.sh" [--profile canonical\|portable\|external-observation] [--json <path>] skills/<slug>` | Go in a source checkout, or `ao` 3.9 or later elsewhere | | Merge overlapping skills | [Consolidate](#consolidate) | nothing bundled | | Export to another platform | [Conversion](#conversion) | Bash 4.3 or later | | Make repeated expertise reusable | [Distill expertise](#distill-expertise) | nothing bundled |

Run only the selected operation. A plugin install ships these scripts but no `ao` binary or Go source: without `ao` on PATH, `audit.sh` exits 127 with `ao: not found` and `heal.sh` exits 2. Then apply the [source template](references/skill-template.md) and [authoring doctrine](references/authoring-doctrine.md) by hand and use the target repository's own checks. `build.sh` and `heal.sh --fix` work on `skills/` of an AgentOps source checkout and refuse with exit 2 elsewhere, such as from a plugin install, instead of writing into its cache; `heal.sh --fix` checks the source first, so a target with findings exits 1 before that refusal. `heal.sh` in either mode checks only its own root's `skills/` and resolves a relative target there, not in the current directory. For a skill in another repository or a user's skills directory, apply the rules and doctrine here to that directory and use its own checks; with `ao` installed, `audit.sh` resolves targets from the current directory and has `portable` and `external-observation` profiles, so it is the bundled check there. Roots, inputs, report destinations, exit codes and recovery from partial creation are in [build and check mechanics](references/build-mechanics.md).

Create and ma