Skill library generator

skill-library-generator

The meta-skill that adapts the pack to a concrete repository. Two jobs: bind the portable skills to this project (fill the config block by interview, grounded in what the repo actually contains), and mine the project's own recurring failure modes into project-local skills the pack does not ship. The invoking agent is the runtime: everything below is done with file tools at invocation time — there is no bootstrap script.

When to use

• First-time adoption in a new or existing research repo.
• Re-binding after a restructure (paths in the config block went stale).
• Periodic harvest: "what keeps going wrong here that deserves a skill?"

When NOT to use

• The repo is already bound and the bindings are current — invoke the individual skills directly.
• Mid-incident debugging — adopt discipline calmly, not during a fire.
• A repo you have no mandate to restructure — discovery and interview are fine, but the scaffold step needs an owner's approval by design.

Phase 0 — Discovery (read-only)

Scan before asking. Establish, from the repo itself:

• layout: package dirs, tests, docs, notebooks, scripts, data/results dirs (find . -maxdepth 2 -type d);
• environment: manifest + lockfile present? which manager? (ls pyproject.toml uv.lock poetry.lock environment.yml 2>/dev/null);
• tests: runner, existing correctness-critical tests (ls tests/);
• record surfaces: decision log? build log? existing conventions in README/CLAUDE.md;
• history: git log --oneline -30 — what does work here actually look like? repeated fix-the-fix commits, "oops" reverts, and stale-doc commits are failure-mode evidence.

Label every conclusion observed (with the path/command) or inferred (with the reasoning). Never present an inference as an observation.

Phase 1 — Interview (bindings)

Fill the config block from templates/CLAUDE.md, one proposal at a time: for each key, propose the value discovery suggests, and confirm or correct with the maintainer.

Key	Interview question (propose first, then ask)
critical_modules	"Which modules, if silently wrong, corrupt your results?"
gate_command	"Which single test command must pass before 'done' on those modules?"
canonical_values	"Where do the protected default parameters live?"
evidence_dir	"Where should kept run evidence land?"
doc_layers	"What are your knowledge layers, authority first?"
decision_log / build_log_dir / phase_plan	"Where do decisions / phase evidence / the plan live (or should)?"
env_manifest / data_dir	"Which manifest pins your environment? Where does input data live?"

A key with no honest answer is a gap, not a blank to invent — record it as a recommendation (e.g. "no gate exists yet; candidate: pin these three computations").

Phase 2 — Failure-mode extraction

From discovery + interview, list the project's recurring failure modes ("results only in scratch dirs", "figures nobody can regenerate", "defaults edited during probes"). Sort each into:

• covered by the pack → the binding from Phase 1 activates it; note which skill;
• project-specific → a candidate local skill (e.g. a domain instrument-calibration checklist, a lab-specific data-ingest runbook).

Phase 3 — Draft local skills

For each approved project-specific candidate, draft a project-local SKILL.md in the active harness's skill directory (.claude/skills/<name>/SKILL.md for Claude Code; for Codex CLI, see this pack's docs/install.md Path C for the current verified plugin-root layout) in the pack's house format: frontmatter (name, trigger-rich description), imperative runbook, a "when NOT to use" note, and a "Provenance & maintenance" section whose re-verification commands were actually run in this repo during discovery. Ground-truth-only: a runbook step you could not verify here does not ship; label anything inferred.

Phase 4 — Audit before scaffold

Self-review the drafts: every path exists (test -f / test -d), every command ran, no invented conventions, no duplication of a pack skill under a new name. Present the full plan — bindings, gaps, local skill drafts, files to be created — and stop for approval.

Phase 5 — Scaffold (post-approval only)

Only after explicit approval, and never overwriting an existing file without showing it first:

1. Write the filled config block + routing table into the project's CLAUDE.md (from templates/CLAUDE.md).
2. Create missing record surfaces: {{decision_log}} (from templates/decisions.md, founding entry D01 = the adoption itself), {{build_log_dir}}/, the negative-results ledger, {{evidence_dir}} with its README + gitignore policy, and templates/results-meta.schema.json copied to the project's docs.
3. Install the layout document (templates/project-layout.md → docs/, pruned to reality).
4. For manual installs, copy the pack's leaf skill folders into the active harness's skill directory — .claude/skills/ for Claude Code, flattened; for Codex CLI, follow the plugin-root layout in docs/install.md Path C.
5. Commit only if the maintainer asks; report exactly what was created either way.

Re-audit mode — aletheia-doctor

Trigger: "run aletheia-doctor", "re-audit the bindings", "are the Aletheia bindings still valid?" — used weeks after adoption, when binding rot is the risk (paths renamed, gate command changed, critical modules moved). This is the read-only counterpart to first-time generation: same config block, opposite direction — it checks what generation wrote.

Read-only. Writes nothing; reports. Steps:

1. Read the config block in the repo's CLAUDE.md. If absent → report NOT ADOPTED and stop (suggest the generator, not the doctor).
2. Resolve each binding and mark it:
   • {{critical_modules}} — each path exists? → RESOLVES / MISSING (name it).
   • {{doc_layers}} — each declared doc/layer path exists? → RESOLVES / MISSING.
   • results/ convention — directory present; most recent meta.json parses? → RESOLVES / STALE / MISSING.
3. Re-run the gate on a clean tree. Confirm the working tree is clean (uncommitted changes make the result unattributable — report DIRTY and stop). Run {{gate_command}}. Report the honest outcome:
   • GREEN / RED — the gate ran to a verdict.
   • UNRUNNABLE — the command, interpreter, or a required dependency/license is absent in this environment, so no GREEN/RED verdict is possible here. Treat as MANUAL: the gate is real but must be VERIFY BY HAND on a machine that can run it (e.g. a gate that needs a proprietary-solver license absent from CI — see the adoption transcript for a worked case). Never fabricate GREEN for a gate you could not actually run.
   • MANUAL — VERIFY BY HAND — the binding is a documented by-hand check rather than a shell command at all. Name it.
4. Report, one line per binding + a coverage footer (what was read, what was run). Never "fix" — a MISSING/RED finding is handed to the human.

Rules

1. Ground-truth-only. Every command, path, and claim in anything you generate is verified against this repository during this invocation; inference is labeled. Wrong runbooks are worse than none.
2. Nothing is written before Phase 5, and Phase 5 requires explicit approval of the Phase 4 plan.
3. State is derived, not stored — do not create a status/state file for the adoption; the scaffold's own artifacts (D01 entry, config block) are the record.
4. Bind before inventing. A failure mode the pack already covers gets a binding, not a new near-duplicate skill.
5. Small is honest. A project that needs five bindings and one local skill should get exactly that — adoption size is set by the repo's needs, not the pack's inventory.

Provenance & maintenance

The generator's phase structure (discover → interview → extract → draft → audit → scaffold) generalizes how this pack itself was produced: portable skills were harvested from one working repository's conventions and re-bound through a config block; see the pack's examples/ directory for that worked mapping. The interview table mirrors templates/CLAUDE.md — keep the two in lockstep when either changes.

Re-verify (pack maintainer):

• grep -o '{{[a-z_]*}}' templates/CLAUDE.md | sort -u — the interview table covers every placeholder key.
• ls skills/core skills/extended — the "covered by the pack" sort in Phase 2 reflects the real inventory.