skill-builder

name	skill-builder
description	Use when bootstrapping leverage-point skills in a target repo, or when the user asks to "create skills" or "set up leverage skills" in a project

Skill Builder (templated mode, POC)

Runtime requirement

Invoke this skill via claude -p, not as a sibling skill in an existing session. This skill dispatches 17 sub-skill generation subagents in parallel; Claude Code's subagent-dispatch budget is one level deep, so an orchestrator that is itself a subagent cannot fan out. Running as claude -p gives this skill its own top-level session with a fresh dispatch budget.

Concretely:

claude -p "<bootstrap-prompt>" --dangerously-skip-permissions \
  --output-format stream-json --verbose \
  --add-dir /path/to/plugin --add-dir /path/to/target-repo

The cost (~$10) and wall time (~5 min) are bounded; once invoked, the run is autonomous.

When to Use

• The user wants to bootstrap repo-specific (L2) leverage-point skills in a target repo
• An automation step needs to instantiate L1 meta-skills as L2 repo skills

When NOT to Use

• For greenfield (one-off) skill creation (deferred to post-POC)
• For drift detection on an existing L2 skill (use skill-auditor)

Input

• target_repo: absolute path to the repo to install L2 skills into
• software_leverage_point_subset (optional): list of software leverage point names. Default: all sibling skills that are leverage points (exclude software-leverage-review, skill-builder, skill-auditor).

Workflow

1. Resolve software_leverage_point_subset by listing sibling skill directories under ../ and filtering out operator skills.
2. For each software leverage point, compute:
   • L1_SKILL_PATH = <this skill's parent>/<software-leverage-point>/SKILL.md
   • OUTPUT_PATH = <target_repo>/.claude/skills/<software-leverage-point>/SKILL.md
3. For each software leverage point, dispatch a subagent using prompt_template-one-skill.md. Run dispatches in parallel.
4. Collect confirmation messages.

L2 SKILL.md shape

An L2 SKILL.md is a context document about how the L1 principles land in this specific repo. It is NOT a self-contained reviewer. Severity is assigned by the orchestrator (software-leverage-review) at review time when it composes L1 + L2 + a target diff. The L2 must not emit error / warn / info labels.

Each generated L2 SKILL.md MUST include, in order:

1. Frontmatter (name, description) plus the portable L1 backlink line (see ## L1 backlink format below) plus the living-skill banner (see ## Living-skill banner below).
2. ## Repo Context: facts inspected from the target (paradigm, ADRs, registries, inventories the lens cares about). Prefer durable signals (shape, presence, named conventions) over values that drift (specific version numbers, exact commit counts, last-week deploy stats). Cite a specific value only when the value itself is the calibrating fact (e.g. "pre-1.0, accepting breakage" where pre-1.0 is the signal).
3. ## Maturity Assessment: current level (POC, growing, stable, legacy, safety-critical), the signals the assessment is based on, and the date last reviewed. The assessment is per-lens, not per-repo: an otherwise-growing repo may legitimately rate at POC for a specific lens (e.g. logging discipline lagging behind testing).
4. ## Growth Direction: the natural next step for this lens, the trigger that would force the step, and what is premature at this maturity.
5. ## Repo-Specific Notes: local conventions, hard rules the repo has already taken a position on, deliberate deferrals, and known gaps. Phrased as observations, NOT as severity-tagged findings. No error / warn / info headings or bullet prefixes. Three useful groupings: "Hard local rules (the repo has already taken a position)", "Conventions in place", "Known gaps the orchestrator should weight against the maturity rating."
6. ## Workflow: a short note that the orchestrator reads this file plus L1 plus a target, and that severity is the orchestrator's call. No "emit findings per L1's output schema" instruction here.

Maturity Assessment + Growth Direction are what skill-auditor later inspects for drift, so the bullets must be concrete.

L1 backlink format

The L2 file is committed into a target repo and used on any machine; absolute filesystem paths are not portable. Use the namespaced skill invocation form:

Generic principles: see L1 meta-skill /software-leverage-points:<software-leverage-point>.

Do not write /Users/..., ~/.claude/..., or any path under the plugin author's filesystem.

Living-skill banner

L2 SKILL.md files reflect repo state at the moment they were generated; the repo evolves and the L2 will drift. The banner makes that contract visible to anyone reading the file (human or agent), names the regeneration path, and points at the drift watchdog. Emit it verbatim immediately after the L1 backlink, with the date stamp filled in to the generation day:

Living skill. This file is generated by /software-leverage-points:skill-builder and reflects repo state as of YYYY-MM-DD. Code changes that affect this lens (new ADRs, renamed registries, changed conventions, maturity shifts) should trigger a regeneration. /software-leverage-points:skill-auditor watches for drift between this file and current repo state.

Output

{
  "target_repo": "<path>",
  "skills_created": ["testing", "documentation"],
  "outputs": ["<path>/.claude/skills/testing/SKILL.md", ...]
}

References

• prompt_template-one-skill.md (subagent prompt)

Continual improvement

This skill is maintained at: https://github.com/syntropic137/software-leverage-points/blob/main/skills/skill-builder/SKILL.md

To improve it, edit the file directly and follow the chassis discipline in maintaining-software-leverage-points: regenerate catalogs, run just qa, then commit.