Use for `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).
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
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 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
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. On Windows
PowerShell, see Scripts.
Phase 1: Scope, mode, outcomes, boundary
First action: run git rev-parse --show-toplevel and git rev-parse HEAD. List the skills under .claude/skills/ and .github/skills/.
Find the audience and harnesses from the instruction files present, such as AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md.
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.
Choose the mode:
Mode
Gate for a skill
Use when
workflow (default)
Verified friction: corrections, reverts, long review rounds, 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.
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.
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.
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:
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
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
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.
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. Exclude generated mirrors. When reverts_truncated is true, the scan stopped at --max-commits (default 3000); raise it to read older history:
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.
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.
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.
Follow 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. 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 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). 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:
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. 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:
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
Run context-optimizer on each authored skill and its composition. If it is unavailable, report context-optimizer: UNAVAILABLE and skillopt: NOT RUN.
Build and run the capability eval, per references/authoring-and-gates.md. 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:
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.
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
Run the three independent reviews in references/authoring-and-gates.md. Self-authored approval is not review evidence.
Send blocking and important fixes back through Phase 4 and Phase 5.
Prove provenance holds, then prove the boundary held, with the same snapshot path:
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 /.
Deliver the report defined in references/authoring-and-gates.md.
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:
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, writes nothing inside the repository (bootstrap_eval.py freeze writes there only with --allow-in-repo; bootstrap_mine.py --out refuses an in-repo path with no override), and runs on Linux, macOS, and Windows.
bootstrap_friction.py is the miner's imported offline-evidence validator, not a separate CLI. review_clusters.py is the shared review-cluster counting module, not a CLI.
Exit code 0 means success and exit code 1 means findings that need action, for every script. Exit codes 2 and 3 differ by script:
Script
Exit 2: configuration
Exit 3: external
bootstrap_mine.py
Bad arguments; not a repository; bad rev; unreadable TARGET or --prs-json; refused --out; an authored file over the 5 MiB read cap
Git missing, failed, or timed out; a working-tree read failed; --out write failed, including a write race
bootstrap_forms.py
Bad arguments; unreadable or malformed plan
None
bootstrap_eval.py
Bad arguments; unreadable or malformed cases, results, or frozen file; edited frozen file; refused --out, including a write race
Git missing, failed, or timed out; the regex grader child failed; --out write failed; any other I/O error
bootstrap_sweep.py
Bad arguments; malformed or mismatched input; run directory in the repository or not empty; changed judge rubric; git missing or failed; any read or write failure (payload error is io)
None
bootstrap_drift.py
Bad arguments; repo or skills root not a directory; unknown --name
None; an unreadable reverify.json is malformed (exit 1)
bootstrap_boundary.py
See the detail below
Git missing, failed, or timed out; an unreadable working-tree file
The payload error names the cause: config for exit 2, git or io for exit 3. bootstrap_sweep.py exits 2 for both, with config for git failures and io for read or write failures.
Script and subcommand
Phase
Computes
bootstrap_mine.py candidates
2
Reverts; ranked churn, TODO hotspots, review rounds
bootstrap_mine.py claims
4, 6, drift
Repository paths and line references in skill text that are missing, untracked, or out of range, each labeled current or historical
bootstrap_forms.py check
3, 4
Plan violations: computable item without an instrument, script missing, scaffold without a reason
bootstrap_eval.py freeze, score
5
Hash-frozen cases; pass rate per condition, capability delta, gain, no_gap, flat, regression, incomplete
bootstrap_sweep.py plan, index, import, tally
2
Source classes and read tools; evidence checks and batches; judge rows; ranked incidents, knowledge gaps, friction map
bootstrap_drift.py check
6, drift
Each skill's reverify.json checks; update_candidates; timed_out; --require also fails a skill with no reverify.json or only skipped checks
bootstrap_boundary.py plan, snapshot, verify
1, 3, 6
Names and conflicts; the write boundary
bootstrap_boundary.py detail: plan exits 1 on a conflict or an invalid name. verify exits 1 on a path outside the boundary, an existing skill changed without --update, an ignored file written in a skill (it would not ship), HEAD or branch moved, or index flags or info/exclude changed. Exit code 2 covers bad arguments; an output root outside the allowed set; an output root, skill directory, or --also-allow path that git ignores; an --also-allow path outside the repository, under .git, or overlapping a skills root; a symlink in any of those paths; or a snapshot that already exists, is inside the repository, is unreadable, or is from another repository or output root. verify does not see gitignored files outside the output root, empty directories, other writes inside .git/, or tag, config, and push operations. It catches accidental writes by a cooperating run; it is not a sandbox. Only the Phase 1 snapshot counts, so snapshot refuses to overwrite an existing file. An unreadable file in the working tree stops snapshot with exit code 3 before any write.
bootstrap_drift.py runs a command check only with --allow-commands; review the argv first, because it executes repository code. The command gets no stdin, discarded output, and only PATH, HOME, and locale variables from the environment. Never pass --allow-commands in a job that holds secrets or runs on untrusted pull request content.
On Windows PowerShell 7, set the plugin root once, then run the same subcommands with python. The first non-empty value wins, as in the bash form:
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.
1---2name: skill-bootstrap3description: Use for `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).4metadata:5 source: https://skillmd.com/skills/rjmurillo/skill-bootstrap6---78# Skill Bootstrap910> Build tools that build capability. Compute what can be computed; write11> prose only for what cannot. Measure each skill against a no-skill12> baseline. Report what you did not measure.1314A bootstrap run turns a project's unwritten knowledge into skills an agent15depends on. Each piece of knowledge takes one of two **tool forms**:1617| Form | Analogy | Ships as | Use for |18|---|---|---|---|19| **scaffold** | a map | prose the model reasons with | rationale, invariants, failure history, evidence bar, judgment calls |20| **instrument** | a GPS | a deterministic script in the skill's scripts directory | anything computable from repository state: gate lookups, path checks, counts, rankings |21| **both** | map plus GPS | script plus the prose that says why and where its answer stops | most load-bearing knowledge |2223The goal is **capability**: what an agent achieves *with* the skill. It is24not competence without the tool. So every computable claim ships as a25script, and every skill gets a score with and without it. Installing this26skill does nothing; only an explicit request starts a run.2728## Triggers2930- `bootstrap skills`31- `capture project workflow knowledge`32- `build this repo's skill library`33- `project skill library`3435## When Not To Use3637| Request | Route |38|---|---|39| Create or improve one skill | `skillforge` |40| Save a workflow you just finished as a skill | `skillify` |41| Improve a skill against a scored eval set | `skillopt` |42| Decide placement or compress a skill without an eval | `context-optimizer` |43| Scaffold README or architecture templates | `codebase-documenter` |44| Refresh an existing library | This skill: run [drift](#maintenance-drift-loop) and Phase 2 diagnosis; pass verified improvements as `--update` |4546## Prerequisites4748`skillforge` (Phase 4) and `context-optimizer` (Phase 5) are required.49`skill-doctor` diagnoses existing skills (Phase 2). `skillopt` tunes scored50skills (Phase 5); its `mine_sessions.py` also probes session sources.51Record each missing one as `UNAVAILABLE` in the report.5253## Process5455```mermaid56flowchart TD57 A[1. Scope, mode, outcomes, boundary snapshot] --> B[2. Diagnose existing skills, mine, discover]58 B --> C[3. Select skills and sort each item by tool form]59 C --> D[4. skillforge authors scripts and prose, claims check]60 D --> E[5. context-optimizer, capability eval, then skillopt]61 E --> I[6. Independent review]62 I --> K{Blocking or important findings?}63 K -->|Yes| D64 K -->|No| J[Verify boundary and deliver]65```6667In the commands below, `<output-root>` is `.claude/skills` or `.github/skills`. Pass `--name` once per skill. On Windows68PowerShell, see [Scripts](#scripts).6970### Phase 1: Scope, mode, outcomes, boundary71721. **First action:** run `git rev-parse --show-toplevel` and `git rev-parse HEAD`. List the skills under `.claude/skills/` and `.github/skills/`.732. Find the audience and harnesses from the instruction files present, such as `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`.743. Select one `<output-root>`. If the repository generates skills from another source, such as a template directory, stop. Ask the user to choose one:75 - authorize the canonical paths, which you then pass to `verify` as `--also-allow <path>`; or76 - receive proposals only, with no skill files written.774. Choose the **mode**:7879 | Mode | Gate for a skill | Use when |80 |---|---|---|81 | `workflow` (default) | Verified friction: corrections, reverts, long review rounds, corroborated sweep incidents | People or agents lose time on known routes |82 | `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 |8384 Neither mode has a quota. A lens with no gate evidence gets no skill.855. 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.866. 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.877. 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:8889 ```bash90 python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_boundary.py" snapshot --repo . --output-root <output-root> --out "<snapshot path>"91 ```9293**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.9495### Phase 2: Mine candidates, then discover96971. Invoke `skill-doctor` once to diagnose the existing project skills.98 Reuse matching artifacts when doctor supplied this run's initial seed.99 Follow the [existing-skill improvement loop](references/discovery.md#existing-skill-improvement-loop)100 for scope, artifact reuse, unavailable evidence, and recursion prevention.101 Pass its inventory through `--sessions-json`; treat proposed edits as102 candidates for Phase 3, not permission to apply them.1031042. 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. Exclude generated mirrors. When `reverts_truncated` is true, the scan stopped at `--max-commits` (default 3000); raise it to read older history:105106 ```bash107 python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_mine.py" candidates --repo . --top 10 --exclude <generated-prefix>108 ```109110 Optionally add `--sessions-json <inventory.json>` for deterministic111 skill-doctor repeated-tool/error counts, or repeat `--hosted-json <export.json>`112 for offline GitHub PR/issue and Azure DevOps PR/work-item observations.113 Follow the [offline friction-input reference](references/discovery.md#offline-friction-input-reference).114 Imports are `candidate_unverified`, not verified friction. Do not import115 qualitative report grades or bypass verification, authoring or evaluation.116 Judged sweep incidents enter only through `--sweep-json`, as keys and counts.1171183. Sweep friction beyond the repository: inventory every connected server,119 resource, prompt, and skill (no fixed list), gather sanitized evidence to120 files, run each judge rubric twice in independent agents, and tally with121 `bootstrap_sweep.py`. Cover human, agent, tool, and process friction;122 institutional knowledge gaps first. Follow123 [references/friction-sources.md](references/friction-sources.md).1241254. 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.126127### Phase 3: Select skills and sort by tool form128129Decide per outcome or lens. `skillforge` triage in Phase 4 makes the final call; this choice is the proposal you give it.130131| Evidence | Decision | Output |132|---|---|---|133| An existing skill reaches the outcome and no verified gap remains | Reuse | Report row only |134| Verified gap sits inside a skill within the boundary | Improve | `--update <skill>` |135| Two or more skills cover the outcome, but state is lost between them | Compose | One thin `<project>-<lens>` skill that sequences them |136| No skill covers the outcome and the mode's gate holds | Create | One `<project>-<lens>` skill |137138Then 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:139140```bash141python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_forms.py" check --plan "<plan path>"142python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_boundary.py" plan --repo . --output-root <output-root> --project <project> --name <project>-<lens>143```144145To 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.146147### Phase 4: Author through skillforge148149Invoke `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:150151```bash152python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_forms.py" check --plan "<plan path>" --skills-root <output-root> --require-scripts153python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_mine.py" claims --repo . --authored <output-root>/<new-skill> <output-root>/<new-skill>154```155156Pass 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.157158### Phase 5: context-optimizer, capability eval, then skillopt1591601. Run `context-optimizer` on each authored skill and its composition. If it is unavailable, report `context-optimizer: UNAVAILABLE` and `skillopt: NOT RUN`.1612. 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:162163 ```bash164 python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_eval.py" freeze --cases "<cases path>" --out "<frozen path>"165 python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_eval.py" score --frozen "<frozen path>" --results "<results path>"166 ```167168 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`.1693. 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.170171### Phase 6: Review, verify, and deliver1721731. Run the three independent reviews in [references/authoring-and-gates.md](references/authoring-and-gates.md#review). Self-authored approval is not review evidence.1742. Send blocking and important fixes back through Phase 4 and Phase 5.1753. Prove provenance holds, then prove the boundary held, with the same snapshot path:176177 ```bash178 python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_drift.py" check --repo . --skills-root <output-root> --name <new-skill> --require179 python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_boundary.py" verify --repo . --snapshot "<snapshot path>" --output-root <output-root> --name <new-skill>180 ```181182 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.183184 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 `/`.1854. Deliver the report defined in [references/authoring-and-gates.md](references/authoring-and-gates.md#bootstrap-report).186187## Maintenance: drift loop188189Skills 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:190191```bash192python3 "${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/skill-bootstrap/scripts/bootstrap_drift.py" check --repo . --skills-root <output-root>193```194195Exit 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.196197## Scripts198199Each CLI uses only the Python standard library, prints JSON with an `examined` count, writes nothing inside the repository (`bootstrap_eval.py freeze` writes there only with `--allow-in-repo`; `bootstrap_mine.py --out` refuses an in-repo path with no override), and runs on Linux, macOS, and Windows.200201`bootstrap_friction.py` is the miner's imported offline-evidence validator, not a separate CLI. `review_clusters.py` is the shared review-cluster counting module, not a CLI.202203Exit code 0 means success and exit code 1 means findings that need action, for every script. Exit codes 2 and 3 differ by script:204205| Script | Exit 2: configuration | Exit 3: external |206|---|---|---|207| `bootstrap_mine.py` | Bad arguments; not a repository; bad rev; unreadable `TARGET` or `--prs-json`; refused `--out`; an authored file over the 5 MiB read cap | Git missing, failed, or timed out; a working-tree read failed; `--out` write failed, including a write race |208| `bootstrap_forms.py` | Bad arguments; unreadable or malformed plan | None |209| `bootstrap_eval.py` | Bad arguments; unreadable or malformed cases, results, or frozen file; edited frozen file; refused `--out`, including a write race | Git missing, failed, or timed out; the regex grader child failed; `--out` write failed; any other I/O error |210| `bootstrap_sweep.py` | Bad arguments; malformed or mismatched input; run directory in the repository or not empty; changed judge rubric; git missing or failed; any read or write failure (payload `error` is `io`) | None |211| `bootstrap_drift.py` | Bad arguments; repo or skills root not a directory; unknown `--name` | None; an unreadable `reverify.json` is `malformed` (exit 1) |212| `bootstrap_boundary.py` | See the detail below | Git missing, failed, or timed out; an unreadable working-tree file |213214The payload `error` names the cause: `config` for exit 2, `git` or `io` for exit 3. `bootstrap_sweep.py` exits 2 for both, with `config` for git failures and `io` for read or write failures.215216| Script and subcommand | Phase | Computes |217|---|---|---|218| `bootstrap_mine.py candidates` | 2 | Reverts; ranked churn, TODO hotspots, review rounds |219| `bootstrap_mine.py claims` | 4, 6, drift | Repository paths and line references in skill text that are missing, untracked, or out of range, each labeled `current` or `historical` |220| `bootstrap_forms.py check` | 3, 4 | Plan violations: computable item without an instrument, script missing, scaffold without a reason |221| `bootstrap_eval.py freeze`, `score` | 5 | Hash-frozen cases; pass rate per condition, capability delta, `gain`, `no_gap`, `flat`, `regression`, `incomplete` |222| `bootstrap_sweep.py plan`, `index`, `import`, `tally` | 2 | Source classes and read tools; evidence checks and batches; judge rows; ranked incidents, knowledge gaps, friction map |223| `bootstrap_drift.py check` | 6, drift | Each skill's `reverify.json` checks; `update_candidates`; `timed_out`; `--require` also fails a skill with no `reverify.json` or only skipped checks |224| `bootstrap_boundary.py plan`, `snapshot`, `verify` | 1, 3, 6 | Names and conflicts; the write boundary |225226`bootstrap_boundary.py` detail: `plan` exits 1 on a conflict or an invalid name. `verify` exits 1 on a path outside the boundary, an existing skill changed without `--update`, an ignored file written in a skill (it would not ship), HEAD or branch moved, or index flags or `info/exclude` changed. Exit code 2 covers bad arguments; an output root outside the allowed set; an output root, skill directory, or `--also-allow` path that git ignores; an `--also-allow` path outside the repository, under `.git`, or overlapping a skills root; a symlink in any of those paths; or a snapshot that already exists, is inside the repository, is unreadable, or is from another repository or output root. `verify` does not see gitignored files outside the output root, empty directories, other writes inside `.git/`, or tag, config, and push operations. It catches accidental writes by a cooperating run; it is not a sandbox. Only the Phase 1 snapshot counts, so `snapshot` refuses to overwrite an existing file. An unreadable file in the working tree stops `snapshot` with exit code 3 before any write.227228`bootstrap_drift.py` runs a `command` check only with `--allow-commands`; review the argv first, because it executes repository code. The command gets no stdin, discarded output, and only `PATH`, `HOME`, and locale variables from the environment. Never pass `--allow-commands` in a job that holds secrets or runs on untrusted pull request content.229230On Windows PowerShell 7, set the plugin root once, then run the same subcommands with `python`. The first non-empty value wins, as in the bash form:231232```powershell233$root = @($env:COPILOT_PLUGIN_ROOT, $env:CLAUDE_PLUGIN_ROOT, '.claude') | Where-Object { $_ } | Select-Object -First 1234python "$root/skills/skill-bootstrap/scripts/bootstrap_boundary.py" snapshot --repo . --output-root <output-root> --out "<snapshot path>"235```236237## Limits238239- 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.240- `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.241- Per-case `gain` and `regression` have no noise floor. Run each case at least twice and treat a single-run flip with suspicion.242243## Anti-Patterns244245| Avoid | Instead |246|---|---|247| One skill per lens to fill a quota | Author only where the mode's gate holds |248| Prose that asks the model to compute an answer | Ship the script; keep prose for why and for where the script's answer stops |249| Reporting capability `UNMEASURED` by default | Freeze cases and score with and without the skill |250| A skill with no `reverify.json` | Machine-checkable provenance, so drift is detected, not discovered |251| Copying a maintained procedure into a skill | Link to it; add only the hint that prevents a known wrong turn |252| A friction ledger, registry, or per-fact database | Put the lesson in the skill with a source reference |253| Writing generated skill copies when the repo renders from templates | Stop at Phase 1 step 3 and ask |254| Reporting a stage that never ran | Report `UNAVAILABLE` or `NOT RUN` with the reason |255256## Extension Points257258Add 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`.259260## Verification261262- [ ] Every selected skill names its mode gate evidence and the observations that prove its outcome.263- [ ] `bootstrap_mine.py candidates` ran before discovery, or the report says why not.264- [ ] `bootstrap_sweep.py tally` exited 0 with a coverage row per source class, or the report says why not; the run directory was deleted.265- [ ] `bootstrap_forms.py check` exited 0 on the final plan with `--require-scripts`: no computable item is scaffold-only.266- [ ] `bootstrap_mine.py claims` reports no `current` finding in authored skills.267- [ ] `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`.268- [ ] `context-optimizer` ran before `skillopt`, or the report names the skipped stage.269- [ ] Independent factual, doctrine, and usability reviews ran on the final text.270- [ ] `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.271- [ ] The report separates authored, evaluated, and installed states, and lists unmeasured results.
Run npx get-skill add rjmurillo/skill-bootstrap in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Use for `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). It is listed under Productivity on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Capability flags: executes scripts. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
rjmurillo (@rjmurillo) published this skill. Their other Agent Skills are listed on their SkillMD profile.