skill-bootstrap

Exact captured content · path skills/skill-bootstrap/SKILL.md · sha256 ae7f12faa703d29c… · revision 2c9a48510df3425df469d35f87579ff1817dada6

Download the exact captured file

---
name: skill-bootstrap
version: 1.0.0
description: Mine a repository's history, reviews, and agent sessions to author and evaluate its project skill library. Use when you say `bootstrap skills`, `capture project workflow knowledge`, `build this repo's skill library`, or `project skill library`, including existing-skill improvements. Do NOT use for one skill (use skillforge), scored tuning (use skillopt), or session diagnosis (use skill-doctor).
license: MIT
user-invocable: true
metadata:
  domains: [skill-creation, onboarding, workflow, knowledge-handoff]
  capability:
    kind: orchestrator
    owns:
      - project-workflow-skill-bootstrap
    depends-on: []
    status: active
  inputs:
    target-repository:
      source: user
    output-root:
      source: user
    bootstrap-mode:
      source: user
    accepted-outcomes:
      source: user
    bootstrap-budget:
      source: user
  outputs:
    project-skills:
    project-skill-scripts:
    capability-eval:
    bootstrap-report:
  routing:
    role: front-door
    invoker: autoplan
    trigger: autoplan's long-tail resolver matches a request to build a project's workflow skill library
    user-facing: true
    intents:
      - bootstrap skills
      - capture project workflow knowledge
      - build this repo's skill library
      - project skill library
---

# Skill Bootstrap

> Build tools that build capability. Compute what can be computed; write
> prose only for what cannot. Measure each skill against a no-skill
> baseline. Report what you did not measure.

A bootstrap run turns a project's unwritten knowledge into skills an agent
depends on. Each piece of knowledge takes one of two **tool forms**:

| Form | Analogy | Ships as | Use for |
|---|---|---|---|
| **scaffold** | a map | prose the model reasons with | rationale, invariants, failure history, evidence bar, judgment calls |
| **instrument** | a GPS | a deterministic script in the skill's scripts directory | anything computable from repository state: gate lookups, path checks, counts, rankings |
| **both** | map plus GPS | script plus the prose that says why and where its answer stops | most load-bearing knowledge |

The goal is **capability**: what an agent achieves *with* the skill. It is
not competence without the tool. So every computable claim ships as a
script, and every skill gets a score with and without it. Installing this
skill does nothing; only an explicit request starts a run.

## Triggers

- `bootstrap skills`
- `capture project workflow knowledge`
- `build this repo's skill library`
- `project skill library`

## When Not To Use

| Request | Route |
|---|---|
| Create or improve one skill | `skillforge` |
| Save a workflow you just finished as a skill | `skillify` |
| Improve a skill against a scored eval set | `skillopt` |
| Decide placement or compress a skill without an eval | `context-optimizer` |
| Scaffold README or architecture templates | `codebase-documenter` |
| Refresh an existing library | This skill: run [drift](#maintenance-drift-loop) and Phase 2 diagnosis; pass verified improvements as `--update` |

## Prerequisites

`skillforge` (Phase 4) and `context-optimizer` (Phase 5) are required.
`skill-doctor` diagnoses existing skills (Phase 2). `skillopt` tunes scored
skills (Phase 5); its `mine_sessions.py` also probes session sources.
Record each missing one as `UNAVAILABLE` in the report.

## Process

```mermaid
flowchart TD
    A[1. Scope, mode, outcomes, boundary snapshot] --> B[2. Diagnose existing skills, mine, discover]
    B --> C[3. Select skills and sort each item by tool form]
    C --> D[4. skillforge authors scripts and prose, claims check]
    D --> E[5. context-optimizer, capability eval, then skillopt]
    E --> I[6. Independent review]
    I --> K{Blocking or important findings?}
    K -->|Yes| D
    K -->|No| J[Verify boundary and deliver]
```

In the commands below, `<output-root>` is `.claude/skills` or `.github/skills`. Pass `--name` once per skill. Add an optional flag inside a command, before its `; fi`; words after the closing `)` run as a separate command. On Windows
PowerShell, see [references/scripts.md](references/scripts.md#windows-powershell).

### Phase 1: Scope, mode, outcomes, boundary

1. **First action:** run `git rev-parse --show-toplevel` and `git rev-parse HEAD`. List the skills under `.claude/skills/` and `.github/skills/`.
2. Find the audience and harnesses from the instruction files present, such as `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`.
3. Select one `<output-root>`. If the repository generates skills from another source, such as a template directory, stop. Ask the user to choose one:
   - authorize the canonical paths, which you then pass to `verify` as `--also-allow <path>`; or
   - receive proposals only, with no skill files written.
4. Choose the **mode**:

   | Mode | Gate for a skill | Use when |
   |---|---|---|
   | `workflow` (default) | Verified friction: corrections, reverts, long review rounds, review failures, missed items, corroborated sweep incidents | People or agents lose time on known routes |
   | `knowledge` | A lens has verified content AND a frozen baseline case shows a model without the skill gets it wrong | Knowledge handoff: domain theory, architecture rationale, research method, with no friction record yet |

   Neither mode has a quota. A lens with no gate evidence gets no skill.
5. Choose 1 to 3 accepted outcomes (workflow) or the lenses to cover (knowledge). Ask the user first. If the user has none, take them from the Phase 2 `candidates` ranking. For each, write the observations that prove it meets project standards. A green check or a merged change is an intermediate result, not proof.
6. Respect explicit budgets. Ask at most five questions in total, and only for facts that evidence cannot supply. One may confirm sweep scope and consent for private channels and mailboxes.
7. Record the boundary before any write. Put the snapshot in the system temp directory or a session scratch directory, and keep the same path for Phase 6:

   ```bash
   ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_boundary.py snapshot --repo . --output-root <output-root> --out "<snapshot path>"; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
   ```

**Authority.** Write only inside `<output-root>` and the paths the user authorized in step 3. The snapshot, plan, doctor artifacts, sweep run directory (new, deleted at run end), `bootstrap_mine.py --out` file, frozen eval cases file, eval cases, and eval results are the only writes outside the repository. Run no mutating git command, deployment, publication, tracker mutation, message, or platform-setting change; call only read tools on connected servers. Evaluation grants no extra write authority. Modify an existing skill only when it is inside the boundary and passed with `--update`; otherwise compose it or report the proposed change.

### Phase 2: Mine candidates, then discover

1. Invoke `skill-doctor` once to diagnose the existing project skills.
   Reuse matching artifacts when doctor supplied this run's initial seed.
   Follow the [existing-skill improvement loop](references/discovery.md#existing-skill-improvement-loop)
   for scope, artifact reuse, unavailable evidence, and recursion prevention.
   Pass its inventory through `--sessions-json`; treat proposed edits as
   candidates for Phase 3, not permission to apply them.

2. Mine before you browse. The script lists reverts and ranks churn hotspots, TODO and FIXME hotspots, and (with `--prs-json` from the host API) review rounds, review failures, and missed items. Exclude generated mirrors. When `reverts_truncated` is true, the scan stopped at `--max-commits` (default 3000); raise it to read older history:

   ```bash
   ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_mine.py candidates --repo . --top 10 --exclude <generated-prefix>; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
   ```

   Optionally add `--sessions-json <inventory.json>` for deterministic
   skill-doctor repeated-tool/error counts, or repeat `--hosted-json <export.json>`
   for offline GitHub PR/issue and Azure DevOps PR/work-item observations.
   Follow the [offline friction-input reference](references/discovery.md#offline-friction-input-reference).
   Review fields in `--prs-json` add `review_failures` (a rule or file area on 3 or more pull requests in 90 days, or a disposition category on 3 `--dispositions-json` entries) and `missed_items` (fixes naming their introducer). One cluster or missed item, once read, satisfies the workflow gate. The script proves a marker recurred, not a shared cause. [Method](references/discovery.md#review-friction-repeated-failures-and-missed-items); arXiv:2610.32313, CRBugBench.
   Imports are `candidate_unverified`, not verified friction. Do not import
   qualitative report grades or bypass verification, authoring or evaluation.
   Judged sweep incidents enter only through `--sweep-json`, as keys and counts.

3. Sweep friction beyond the repository: inventory every connected server,
   resource, prompt, and skill (no fixed list), gather sanitized evidence to
   files, run each judge rubric twice in independent agents, and tally with
   `bootstrap_sweep.py`. Cover human, agent, tool, and process friction;
   institutional knowledge gaps first. Follow
   [references/friction-sources.md](references/friction-sources.md).

4. Follow [references/discovery.md](references/discovery.md) from the mined cases: repository and discourse, the 17 discovery lenses, workflow gaps, and session and memory sources. When an outcome touches PRs, pipelines, trackers, or releases, also follow [references/hosted-platforms.md](references/hosted-platforms.md). Finish discovery before any authoring. In `knowledge` mode, freeze the baseline cases with `bootstrap_eval.py freeze` before the baseline run, so the hash covers them before any result exists. Cases carry skill names, so check each name with `bootstrap_boundary.py plan` before the freeze; see [Knowledge mode](references/discovery.md#knowledge-mode) for what a later rename costs.

### Phase 3: Select skills and sort by tool form

Decide per outcome or lens. `skillforge` triage in Phase 4 makes the final call; this choice is the proposal you give it.

| Evidence | Decision | Output |
|---|---|---|
| An existing skill reaches the outcome and no verified gap remains | Reuse | Report row only |
| Verified gap sits inside a skill within the boundary | Improve | `--update <skill>` |
| Two or more skills cover the outcome, but state is lost between them | Compose | One thin `<project>-<lens>` skill that sequences them |
| No skill covers the outcome and the mode's gate holds | Create | One `<project>-<lens>` skill |

Then sort every verified item by tool form and write the plan file (schema in [references/authoring-and-gates.md](references/authoring-and-gates.md#plan-file)). Ask one question per item: **can a program compute this from repository state?** If yes, it is `instrument` or `both`, never scaffold-only. Validate the plan, then names and conflicts:

```bash
( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_forms.py check --plan "<plan path>"; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_boundary.py plan --repo . --output-root <output-root> --project <project> --name <project>-<lens>; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
```

To improve an existing skill, pass it twice: `--name <skill> --update <skill>`. Exit code 1 from either command means a violation, a conflict, or an invalid name: fix the plan, rename, get authorization for `--update`, or drop the skill. Never overwrite blindly.

### Phase 4: Author through skillforge

Invoke `skillforge` once per selected skill with the brief in [references/authoring-and-gates.md](references/authoring-and-gates.md). Every `instrument` or `both` item ships its script and tests; every skill ships `reverify.json`. Run independent skills in parallel agents when the harness supports it. If `skillforge` is unavailable, report `skillforge: UNAVAILABLE` and stop authoring. After authoring, prove the scripts exist and the text is grounded:

```bash
( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_forms.py check --plan "<plan path>" --skills-root <output-root> --require-scripts; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_mine.py claims --repo . --authored <output-root>/<new-skill> <output-root>/<new-skill>; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
```

Pass each skill this run wrote or updated with `--authored`, so its uncommitted files count. A `claims` finding with context `current` is a defect to fix. A `historical` one is a hint: read the line and decide.

### Phase 5: context-optimizer, capability eval, then skillopt

1. Run `context-optimizer` on each authored skill and its composition. If it is unavailable, report `context-optimizer: UNAVAILABLE` and `skillopt: NOT RUN`.
2. Build and run the capability eval, per [references/authoring-and-gates.md](references/authoring-and-gates.md#capability-eval). Score against the same frozen file that was frozen before the knowledge-mode baseline run (for any other mode, freeze before the first run). Run each case without the skill (`baseline`) and with it (`with_skill`), then score:

   ```bash
   ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_eval.py freeze --cases "<cases path>" --out "<frozen path>"; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
   ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_eval.py score --frozen "<frozen path>" --results "<results path>"; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
   ```

   A skill whose cases are all `no_gap` adds nothing measurable: drop it or report why it stays. A skill whose cases are all `flat` does not transfer: `score` exits 1 in every mode, names it under `flat_skills`, and lists its cases in `failing_cases`. Fix the skill or the cases. One `flat` case among other statuses does not fail. A `regression` is a blocking finding. In `knowledge` mode, add `--mode knowledge` to `score`: a skill whose cases are all `no_gap` then also exits 1, with its cases in `failing_cases`. A regex result that times out is left ungraded, so its case is `incomplete`.
3. Run `skillopt` only after steps 1 and 2, on the frozen cases as its held-out set. Otherwise report `skillopt: NOT RUN` with the missing input. Never invent an optimization result.

### Phase 6: Review, verify, and deliver

1. Run the three independent reviews in [references/authoring-and-gates.md](references/authoring-and-gates.md#review). Self-authored approval is not review evidence.
2. Send blocking and important fixes back through Phase 4 and Phase 5.
3. Prove provenance holds, then prove the boundary held, with the same snapshot path:

   ```bash
   ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_drift.py check --repo . --skills-root <output-root> --name <new-skill> --require; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
   ( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_boundary.py verify --repo . --snapshot "<snapshot path>" --output-root <output-root> --name <new-skill>; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
   ```

   Run the drift check without `--allow-commands` unless the user approved the argv list of each `command` check; a skill whose checks were all skipped reports `skipped`, which proves nothing, so `--require` fails it.

   Add `--update <skill>` for each authorized improvement and `--also-allow <path>` for each path the user authorized in Phase 1. A file grant covers that exact path; end a directory grant with `/`.
4. Deliver the report defined in [references/authoring-and-gates.md](references/authoring-and-gates.md#bootstrap-report).

## Maintenance: drift loop

Skills decay as the repository moves. Run the drift check on a schedule, after a large merge, or before relying on a library you did not author:

```bash
( for d in "${CLAUDE_PLUGIN_ROOT}" "${COPILOT_PLUGIN_ROOT}" .claude; do if [ -n "$d" ] && [ -f "$d/lib/ptk_run.py" ]; then exec python3 "$d/lib/ptk_run.py" skills/skill-bootstrap/scripts/bootstrap_drift.py check --repo . --skills-root <output-root>; fi; done; echo "ptk_run: no plugin root holds lib/ptk_run.py" >&2; exit 2 )
```

Exit code 1 lists `update_candidates` and gives `update_args` as a JSON list of argv tokens. Pass those tokens as separate arguments to a new bootstrap run; never paste them into a shell string. A skill directory whose name is not kebab-case is reported `malformed` and is left out of `update_args`. A skill whose checks hit a timeout (a slow command, or the 900 s total deadline) and none failed is `incomplete`: it exits 1 and is listed under `timed_out`, not in `update_candidates`. Re-run the check for it; do not rebuild it. For a library authored before `reverify.json` existed, run `bootstrap_mine.py claims` on it instead.

## Scripts

Each CLI uses only the Python standard library, prints JSON with an `examined` count, and writes nothing inside the repository unless you pass `bootstrap_eval.py freeze --allow-in-repo`. Exit code 0 means success and exit code 1 means findings that need action, for every script. `bootstrap_friction.py`, `bootstrap_review.py`, and `review_clusters.py` are modules the miner imports, not CLIs. [references/scripts.md](references/scripts.md) holds the exit 2 and 3 table per script, the subcommand table, the `bootstrap_boundary.py` detail, and the Windows PowerShell form.

`bootstrap_drift.py` runs a `command` check only with `--allow-commands`, which executes repository code. Never pass it in a job that holds secrets or runs on untrusted pull request content.

## Limits

- The instrument-first rule has not yet shown a capability gain. Run `20261017T164000Z-2e1e279c` found no F1 gain on T1 to T4 (T1 0.867 to 0.872; T2 to T4 stayed at 1.000) at 1.4x to 2.5x cost per run (the report is at `evals/skill-bootstrap-capability/reports/20261017T164000Z-2e1e279c/REPORT.md` in the rjmurillo/ai-agents repository, not in this skill). Untested hypotheses: reproducibility across runs, and repositories where ad hoc scripts are hard to write.
- `bootstrap_forms.py check --require-scripts` stays a blocking gate (owner decision D18, 2026-10-24). It loosens only when a named consumer needs it.
- Per-case `gain` and `regression` have no noise floor. Run each case at least twice and treat a single-run flip with suspicion.

## Anti-Patterns

| Avoid | Instead |
|---|---|
| One skill per lens to fill a quota | Author only where the mode's gate holds |
| Prose that asks the model to compute an answer | Ship the script; keep prose for why and for where the script's answer stops |
| Reporting capability `UNMEASURED` by default | Freeze cases and score with and without the skill |
| A skill with no `reverify.json` | Machine-checkable provenance, so drift is detected, not discovered |
| Copying a maintained procedure into a skill | Link to it; add only the hint that prevents a known wrong turn |
| A friction ledger, registry, or per-fact database | Put the lesson in the skill with a source reference |
| Writing generated skill copies when the repo renders from templates | Stop at Phase 1 step 3 and ask |
| Reporting a stage that never ran | Report `UNAVAILABLE` or `NOT RUN` with the reason |

## Extension Points

Add a discovery lens in `references/discovery.md`, the plan-file lens table in `references/authoring-and-gates.md`, and `bootstrap_forms.py`. Add a hosting provider section in `references/hosted-platforms.md`. Add a grader kind in `bootstrap_eval.py`. Add a check kind in `bootstrap_drift.py`. Change the report shape in `references/authoring-and-gates.md`.

## Verification

- [ ] Every selected skill names its mode gate evidence and the observations that prove its outcome.
- [ ] `bootstrap_mine.py candidates` ran before discovery, or the report says why not.
- [ ] `bootstrap_sweep.py tally` exited 0 with a coverage row per source class, or the report says why not; the run directory was deleted.
- [ ] `bootstrap_forms.py check` exited 0 on the final plan with `--require-scripts`: no computable item is scaffold-only.
- [ ] `bootstrap_mine.py claims` reports no `current` finding in authored skills.
- [ ] `bootstrap_eval.py score` ran on frozen cases; the report gives each skill's capability delta, and no case is `regression` or `incomplete`, and no skill has every case `flat`.
- [ ] `context-optimizer` ran before `skillopt`, or the report names the skipped stage.
- [ ] Independent factual, doctrine, and usability reviews ran on the final text.
- [ ] `bootstrap_drift.py check --require` and `bootstrap_boundary.py verify` exited 0. The verify examined count is above zero unless the run wrote only proposals.
- [ ] The report separates authored, evaluated, and installed states, and lists unmeasured results.