skill-improver · git:20260915.09d5754 · 2026-09-15 · sha256 f4c4c7b7217c8d5e

skill-improver git:20260915.09d5754A

Immutable. This exact content is served forever at /api/v1/blob/f4c4c7b7217c8d5e.

---
name: skill-improver
description: >-
Autoresearch loop for Claude Code skills — greedy keep/discard hill climbing
on a 10-dimension quality rubric, with blind subagent validation for
self-scoring bias, plus a `freshen` mode that probes external references
(release notes, docs, deprecation signals) and applies verified updates,
plus a `trigger` mode that measures and tunes the skill's frontmatter
description until it reliably fires when it should and stays silent when
it shouldn't (60/40 train/test split, 7 runs/query, blinded test scores),
plus an `ages` mode that prints a fleet-wide table of every skill's
verification age vs last content change, no probes.
when_to_use: >-
Triggers on "improve a skill", "optimize a SKILL.md", "make my skill better",
"run skill autoresearch", "self-improve skills", "evaluate skill quality",
"score my skill", "audit a skill", "rate my skill", "refine skill
description", "iterate on a skill", "freshen skill", "freshen skills",
"update skill references", "check skill staleness", "is my skill out of
date", "refresh skill sources", "skill ages", "how old are my skills",
"list skills by date", "skill not triggering", "skill didn't
fire", "skill won't trigger", "skill not invoked", "tune skill
description", "fix skill triggers", "skill under-triggers",
"skill over-triggers", "false-positive skill", "make skill trigger",
"Claude isn't using my skill", or mentions autonomous skill improvement,
skill quality scoring, skill optimization loops, stale skill content,
or skill activation problems.
argument-hint: '[improve|score|freshen|trigger|philosophy|ages|batch] [<skill-name>|--all|<glob>]'
---

# Skill Improver — Autoresearch for SKILL.md

> **Core Philosophy:** The human programs the researcher, not the research.
> Apply Karpathy's autoresearch methodology — greedy hill climbing with
> keep/discard against a scalar metric — to autonomously improve Claude Code
> skills.

## Invocation

Argument grammar:

```
/skill-improver <mode> <target> [--opts]
```

Examples:

```
/skill-improver ages
/skill-improver ages 'vllm-*'
/skill-improver freshen autoresearch
/skill-improver score gh-cli
/skill-improver improve ~/.claude/skills/helm
/skill-improver trigger vllm-caching
/skill-improver trigger gh-cli --missed "find issue with label X"
/skill-improver batch freshen --all
/skill-improver freshen --group 'vllm-*'
```

If `<mode>` is omitted, default to `improve`. If `<target>` is omitted and mode is not `batch`, prompt the user. For `batch`, the target after `batch` selects the sub-mode (`freshen`, `improve`, `trigger`, or `philosophy`, default `improve`); the target list comes from `scripts/scan-skills.sh`. The `--missed "<phrase>"` flag (trigger mode only, repeatable) seeds the eval set with user-reported failures as gold should-trigger queries.

## The Improvement Loop (default mode)

Greedy hill climbing on the 10-dimension rubric: score the skill, apply ONE
change, re-score cold, keep only what moves the metric (+2, or +1 with net
simplification), revert everything else; stop at 90+ with no dim below 7, a
mapped ceiling (5+ discards across 2+ categories), or the 10-iteration cap.

**A +2 movement is inside the scorer's own noise** (measured 2026-08-20:
re-scoring an unchanged skill moves the total by a median of 2-3 points and up
to 6 on frontier models — `references/blind-validation.md` §Measured scorer
behaviour). Treat a bare +2 as *undecided*, not as a keep: confirm it with a
second cold score, or keep it only when the change also simplifies. Rankings
between skills are stable under that noise; single-iteration totals are not.

The full phase workflow — **Phase 0 Setup → Phase 7 Land it**,
including the cold-score discipline, the hypothesis criteria (simplicity,
weakness, format-only), the keep/discard decision rules with the anomaly
gate and noise zone, and the stop conditions — lives in
**`references/improve-loop.md`**. Read it before starting a run; every rule
that decides keeps and discards is there.

Three rules that bind without reading it:

- **One change per iteration, diff minimal.** Bundling attributes the score
lift to the wrong cause, so the next loop pivots to the wrong category.
- **The backlog records blockers, not leftovers.** Persist ceiling findings to
`<skill>/references/improvement-backlog.md` (`references/backlog-format.md`)
— but every Open entry must **name the absent thing** that prevents the work:
a ruling, a credential, an unreleased version, a measurement nobody can run
now. Effort is not a blocker. If the honest answer is "nothing, it is just
work", do it before the pass ends; a pass may not end having added an
unblocked item under any heading.
- **A pass ends with work, not a report of work.** Done = every keep applied +
**both** blind scores on record (baseline at setup on a snapshot, final on
stop — one alone is self-scored) + committed with the backlog in the same
commit + resolved items deleted from Open. Zero discards means no ceiling was
mapped: record that as stopped early, never as finished (Phase 7).

---

## Operating Rules

### Never Stop (Unless Asked)

Run the loop continuously. Do not ask permission between iterations. The user may be away. Print status lines so they can review when they return.

### State the Spend Before a Fan-out

Any wave of subagents or `claude -p` probes — a batch pass, a freshen wave, a
floor fleet, a trigger eval — gets a one-line estimate before it starts: how
many calls, on which model, and the rough dollar size from
`scripts/model-rates.json`. `scripts/run-cost.py` prices a run afterwards, which
is too late to decide against it.

Pin the cheap model on mechanical work — a grader that only checks text
against assertions does not need the strongest model, and a probe that
inherits the session model pays for one. **A cap is a resting state, not a
task** — the unmeasured Dim 10 cap in particular is deliberate; clearing one
is optional work that costs money, so price it first and say the number.

### Git as State Machine

When improving skills in a git-tracked directory:
- Commit each kept improvement individually.
- Use `git diff` to show what changed on discard before reverting.
- The branch tip always represents the best-known version.

### Prioritize Deletion Over Addition

In practice, removing redundant content produces the largest per-iteration score gains. When choosing between an additive improvement (+1 from adding content) and a subtractive one (+1 from deleting content), prefer deletion — it improves simplicity as a side effect.

**But similar is not redundant, and this bias is exactly what gets that wrong.**
Before deleting on the grounds that two passages overlap, classify the overlap:
only `DUPLICATE` is actionable, while `INTENTIONAL_DETAIL` (an overview in
SKILL.md developed in `references/`) and `RELATED_BUT_DISTINCT` (same topic,
different purpose) must be kept — the first of those *is* progressive
disclosure, the structure a good skill is meant to have. Measured across the
whole fleet, **83% of similar-looking content was correct as written**; a
deletion bias would have cut it. `scripts/dedup-fleet.py` produces the table
and `references/improvement-patterns.md` §Pattern 6.1 explains how to read it.

### Fleet Checks — Run These Over the Whole Tree

Six checkers under `scripts/`, all testing something a parser can decide. **Run each
over the entire tree, not only the skill being edited** — every one found defects in
skills nobody was touching. Each exits non-zero on findings and has `--selfcheck`.

| Script | Catches | Expected non-findings |
|---|---|---|
| `check-shell-fences.py` | bash fences that do not parse, plus the backslash-then-comment continuation `bash -n` cannot see | prompt transcriptions, placeholders |
| `check-yaml-fences.py` | YAML fences that do not parse | Go/Jinja templates, placeholders |
| `check-tables.py` | rows whose cell count disagrees with the header, which drops the last column silently | none — a hit is a defect |
| `check-links.py` | dead doc-host URLs and moved GitHub file paths | 403 (fetcher refused), 429 (own rate limit) |
| `check-advisory-floors.py` | a CVE floor that is still vulnerable or outside the advisory's range (needs `--verify`) | per-minor backports, unbounded ranges, negative claims |
| `check-expiring-claims.py` | content dated to become false, especially relative phrases beside a date | lifecycle tables of future EOL dates |

**Read the expected-non-findings column before acting on output.** Details, measured
hit counts, and the three sweep shapes already tried and abandoned:
`references/fleet-checks.md`.

### One File at a Time

Each iteration targets one file. If the improvement requires touching multiple files (e.g., moving content from SKILL.md to references/), that counts as one atomic change.

**The split test for atomicity.** "Atomic" is not a word — it is a constraint. State the change in 10 words, present-tense, single verb. "Move gotchas section to references/gotchas.md." If the honest sentence needs an "and" — "move content to references/ AND fix second-person AND tighten terminology" — it is three iterations, not one. Pure relocation is allowed; relocation that quietly rewrites prose is not. If a structural move starts editing a sentence's wording, stop, finish the move with the prose unchanged, score, then propose the prose edit as the next iteration. The reason: bundled iterations attribute the score lift to the wrong cause, which means future loops will pick the wrong category to pivot to.

### Preserve the Author's Intent

The skill reflects the author's domain expertise. Improve structure, clarity, and adherence to best practices. Do NOT rewrite the author's domain knowledge or change what the skill teaches — only how it teaches it.

### A Measurement That Failed Is Not a Low Score

Every mode here turns evidence into a number, and every one of them can fail to
collect a piece of it — a `claude -p` probe that times out, a blind scorer that
dies, an eval case that errors, a source row that cannot be reached. **Never let
the gap become a value.** Report it as `NO SCORE`, exclude it from the
denominator, and say what is missing.

Coercing to zero is not the conservative choice; it is a fabricated
measurement, and it biases in whichever direction the metric happens to run:

- A timed-out trigger probe scored as "did not fire" deflates should-trigger
queries *and* inflates should-NOT-trigger ones, so a completely broken probe
reports a plausible mid-range number built out of nothing.
- A floor run whose probes all failed reads as 0% known — the "every claim is
real transfer" row — so the failure *raises* the Dim 10 cap.
- A missing blind score filled in from the self-score reinstates exactly the
bias the blind check exists to remove.

The rule is the same in each case: an incomplete run must not be compared
against a complete one, and a pass that could not measure its own mode's
evidence is **stopped early**, never finished. `freshen` has always worked this
way — "the stamp never lies", a partial pass keeps the old date. This is that
rule everywhere else.

### The Skill Outranks Training Data

Target skills are freshened continuously — their factual claims (versions,
release dates, model names, APIs, flags, pinned SHAs) are often NEWER than the
model's knowledge cutoff. Treat the skill's existing text as more current than
the model's prior, never the reverse. This rule applies in EVERY mode, not just
`freshen`:

- Never mutate an external-world claim from memory. If a hypothesis requires
changing one, verify online first (gh / WebFetch / WebSearch, freshen-style
probe) and cite the source in the iteration log — or drop the hypothesis.
"I know this is wrong" is not evidence; the probe is.
- **Downgrade alarm:** wanting to lower a version, move a date backward, or
revert a claim to an older state is the signature of training-data staleness
— the skill was probably freshened past the cutoff. Mandatory online check
before touching it; expect to find the skill is right.
- This binds blind scorers too — the validation prompt instructs them to check
`sources.md` stamps instead of scoring Dim 9 down from memory, and the loop
must not act on a blind agent's "wrong version" finding without its own probe.
- **A new citation is a claim too — verify it before writing it down.** The rule
above covers *altering* an existing claim; the recurring failure has been
*adding* one. Before a paper, post, issue, or doc URL enters any file, open it
and confirm the title, the author, the date, and that the specific number or
finding being attributed is actually there. A plausible-looking arXiv ID is not
a source. Where a research agent supplied the citation, the check is a separate
step from the research — an agent asked only "is this real?" catches what the
agent that found it will not. If a detail cannot be confirmed on the page,
cite the paper without it rather than repeating the unverified figure.

---

## Blind Validation

Self-evaluation bias is real — the agent that wrote improvements tends to score
them generously. Blind validation uses independent subagents that have never seen
the skill to score it objectively. Run it twice: at baseline (improve-loop
Phase 0 step 6, in the background, parallel with the loop) and after the
loop stops (improve-loop §"On stop") — the spawn points the loop itself
already marks.

### Scorer Agent, Model Rule, and Comparison Table

The scorer is the **`blind-scorer` agent definition** (canonical instruction
text; spawn it with a two-line path tail so every scorer in a run shares the
cached prefix). The spawn mechanics, fallback chain, model rule, parallel-
scoring variant, and bias-check table format live in
**`references/blind-validation.md`**. Read it when spawning either agent.
Three rules bind without reading it. **Omit `model` in the spawn call** — the
agent definition pins it (`model: sonnet`), so baseline and final match by
construction. **Omit effort too** — scorers inherit the session's, and effort
was measured flat. **Print the bias-check table** after each agent returns,
flagging every dimension where self and blind differ by 2 or more.

### The A/B Comparator Decides the Pass

The absolute score answers "how good is this?". It does not reliably answer
"did this pass help?": re-scoring the same skill has a measured 2–4 point
spread, and a pass that kept six correctness fixes came back with an
unchanged blind total. **The pass verdict comes from a comparator, not from
the delta between two absolute scores.**

After the loop stops, materialise baseline and final as two blinded
directories, assign them `DIR A` / `DIR B` by coin flip, and spawn **three
`skill-comparator` agents**; majority vote gives `IMPROVED`, `NO CHANGE`, or
`REGRESSED`. Omit `model` — the agent definition pins it.

Three rules bind without opening the reference. **Blind the pair on disk** —
`git archive` stamps each side with its own commit time, a 13-hour tell.
**Spawn from outside the repo** — a subagent started in the repo inherits an
environment block listing recent commit subjects, which describe the very
diff it is judging; one comparator in three reported that leak having run no
git command. **`REGRESSED` outranks a positive delta** — revert the
responsible iteration rather than recording a lift, and record a `TIE`
majority as `NO CHANGE`.

Exact commands, the vote table, the order-bias check and the two leakage
classes: **`references/blind-validation.md`** §"The A/B comparator".

---

## Batch Mode

To improve multiple skills:

1. Run `scripts/scan-skills.sh` to find all SKILL.md files in scope.
2. Score each skill (baseline only) and print a ranked table.
3. Sort by score ascending (worst first).
4. Run the improvement loop on each, starting from the worst. Cap at 5 iterations per skill in batch mode.
5. Print a final summary table: skill name, baseline score, final score, delta, number of kept changes. The batch is done when **every skill from step 1 has a row** — including skills whose loop was skipped, crashed, or hit the cap (mark the status). A missing row is silent truncation, not a smaller batch.

**Dynamic workflows (Fable 5 / Opus 5, Claude Code v2.1.154+).** Batch mode is multi-agent orchestration — when the user has opted into the `Workflow` tool, reuse the saved driver `scripts/batch-workflow.js` (a recon→apply→blind pipeline, median-of-3 final blind): `Workflow({scriptPath: "${CLAUDE_SKILL_DIR}/scripts/batch-workflow.js", args: ["keda", "helm", ...]})`. `args` takes bare names, absolute dirs, or `{dir, hints}` objects. Per-skill loops keep one change per iteration so cause stays attributable; recon and apply agents inherit the session model and effort; blind scorers are pinned to Sonnet 5, same as a solo run, and no agent does git ops — commit per-skill after review. Without opt-in, run skills sequentially as above.

**Native loops (Claude Code `/loop` v2.1.71+, `/goal` v2.1.139+).** For recurring or goal-driven runs, drive this skill with the harness's loop primitives: `/loop <interval> /skill-improver batch freshen --all` for scheduled passes, or `/goal` with a checkable stop ("every skill scores ≥85, stop after N tries") — `/goal`'s evaluator-checked stop condition maps directly onto this skill's scalar metric. Size batch fan-outs against two live caps: **20 concurrent subagents** (v2.1.217 default, `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`) and the **medium workflow size guideline of <15 agents** (v2.1.219 default, `workflowSizeGuideline`) — a batch wider than these queues silently or trips a guideline warning mid-run. The per-session subagent cap is gone: **v2.1.224 removed it**, so total agent count no longer bounds a `--all` pass; concurrency does. Official guidance: https://claude.com/blog/getting-started-with-loops (2026-06-30).

---

## Standalone Evaluation (No Loop)

When the user only wants a quality score without iterating:

1. Read the target skill and `references/quality-rubric.md` from the skill-improver directory.
2. Run `python3 ${CLAUDE_SKILL_DIR}/scripts/eval-evidence.py <skill-dir>` and take Dim 10's cap from it — never judge the delta's sign by eye. It also prints the case count and noise floor.
3. Score all 10 dimensions using the scoring template from the rubric.
4. Print the results table. Highlight the lowest dimension and recommend the single highest-impact improvement.
5. If Dim 9 is capped by sources.md staleness (see rubric §Dim 9), recommend running `freshen <skill>` as the single highest-impact next step.
6. If step 2 reported fewer than 8 cases, recommend `scripts/grow-evals.py` — a corpus that small cannot resolve a delta and quietly defends the skill it tests. No eval set at all is a different finding: the cap is correct and needs no fix.
7. Stop. Do not enter the improvement loop unless asked.

**`/doctor` is the first-party sibling, not a substitute.** Anthropic ships
`claude doctor` / `/doctor` to "rightsize your skills, and CLAUDE.md files"
([context-engineering blog](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models),
2026-07-24; bundled skill since v2.1.205). It is a one-shot simplification pass
with no metric, no keep/discard, and no blind check — run it first for free
hypotheses, then use this skill when the question is *did the change measurably
help*. Do NOT report `/doctor` output as a score.

**Dim 10 is capped until net value is measured** — apply the rubric's
§"Negative-Transfer Gate" (8 unmeasured, 2 when the skill loses to no-skill;
measuring means `delta_pass_rate`, not a judgement about the text).

**Scope boundary — every metric here scores the skill's *text*, never its
outputs.** SkillLens measured text-only judging at 46.4% accuracy against real
utility, so a rising rubric score is not evidence the skill's results improved.
To measure that, run the official skill-creator plugin's eval loop (`/plugin
install skill-creator@claude-plugins-official`): assertions in `evals/evals.json`,
one clean-context subagent per case, with-skill vs without-skill `benchmark.json`,
blind A/B between versions. Methodology:
https://agentskills.io/skill-creation/evaluating-skills

---

## Freshen Mode

Probe a skill's external references for staleness and apply verified updates in
place — same keep/discard loop as `improve`, but hypotheses come from online
evidence (release notes, doc commits, deprecation signals), not rubric scores.
A pass verifies **every** sources.md row (delegated to cheap subagents —
`web-searcher` for web/gh rows, `Explore` for local-clone rows — in one
background wave) and ends by writing the single `Freshened: <date>` header
stamp; unverifiable rows get inline exception notes. No per-row dates.

**Invocation:** `freshen <skill-path>` · `--all` · `--group <glob>`. Defaults to
**apply**. For a read-only staleness readout — "how old are my skills?", which
to freshen first — use `ages` mode instead (fleet-wide table in one command,
no probes); Standalone Evaluation covers the single-skill case (Dim 9 tracks
`sources.md`).

Full phase workflow (F0→F6), batch mode, and anti-patterns live in
**`references/freshen-patterns.md` §"Freshen Mode Workflow"** with the extraction
heuristics, probe templates, and classification rules. Read it when running `freshen`.

---

## Trigger Mode

Measure and tune a skill's frontmatter `description` (and `when_to_use`) so it
fires when it should and stays silent when it shouldn't. Same keep/discard
hill-climbing as `improve`, but the metric is **trigger rate against an eval
set** — the methodology Anthropic's `skill-creator` uses (60/40 train/test,
7 runs/query for decisions, blinded test scores, ≤1024-char cap).

**Use trigger mode when:** a user reports "the skill didn't fire" / "Claude isn't
using my skill", or a description is too vague, narrow, or keyword-collision-y.
Trigger-mode measures Dim 1 empirically via `claude -p` (`scripts/probe-trigger.py`).

Full phase workflow (T0 Setup → T7 Apply/persist), batch mode, and anti-patterns
live in **`references/trigger-patterns.md` §"Trigger Mode Workflow"** with the
eval-set construction rules, probe mechanism, and mutation patterns. Read it when
running `trigger`.

---

## Ages Mode

Read-only fleet readout — no probes, no scoring, no mutation. Run
`scripts/staleness-report.py` and print its table verbatim, then one
sentence naming the stalest bucket and the suggested next `freshen` target.
That is the whole mode; do not start scoring or freshening from it.

**Invocation:** `ages` (whole fleet) · `ages <glob>` (e.g. `ages 'vllm-*'`) ·
`ages <root-dir>`. Two date tracks per skill: `oldest`/`age` = when the
skill's external claims were last verified — the sources.md `Freshened:`
header stamp (rows shows `full`), or for legacy files the oldest per-row
date — vs `changed` = last content change on disk (newest file mtime). A
skill can be freshly edited yet stale on verification — and vice versa; the
`cap` column shows the Dim 9 staleness cap the verification age implies.

The `cases` column counts outcome eval cases and marks `!` below 8. **A skill
with an eval set is not the same as a skill that can be measured**: one case
flipping moves the pass rate by `1/n`, so a 3-case corpus resolves nothing under
0.33 and quietly defends the skill it exists to test. This is the only place the
fleet reports that gap — `eval-evidence.py` computes the same floor per skill,
but nothing would ever run it on a corpus nobody had flagged. Act on `!` rows
with `scripts/grow-evals.py`, then re-run the benchmark.

The `open` column counts items under `## Open` in each
`improvement-backlog.md`, with a fleet total in the footer. Read it as a
deferral signal, not a workload: an entry earns its place there only when
something external blocks the work, so a count that only ever rises is
recording work that was parked rather than blocked. Report it in the `ages`
summary sentence whenever the fleet total moved since the last run.

---

## Floor Mode

Measure what a **bare** model already knows about the skill's subject — no
skills loaded, no tools, no web — and bucket each claim `KNOWS` / `UNKNOWN` /
`CONFLICTS`. Whatever the model knows unaided does not need to be in the
skill; `CONFLICTS` is worth more than a filled blank, because unaided the
model does not hesitate — it proceeds, wrong. Read-only: surfaces candidates,
never edits. Re-run on each model release — the movement in `KNOWS` is the
delete list.

**Invocation:** one skill — `python3 ${CLAUDE_SKILL_DIR}/scripts/knowledge-floor.py --skill <name> [--extract]`
· whole fleet — `python3 ${CLAUDE_SKILL_DIR}/scripts/floor-fleet.py --root <dir>`.

Two rules bind without reading the reference. **Classify the skill first** —
probe capability-uplift skills; on an encoded-preference skill (a house order
for things the model already knows how to do) a high floor is the expected
reading, not a delete list. **`KNOWS` is a candidate, never a licence to cut**
— recall is not application, and a conflict never means the skill is wrong
(§"The Skill Outranks Training Data").

The classification test, the bucket table, the two limits in full, and how
floor results move the Dim 10 cap into one of three skill profiles live in
**`references/floor-patterns.md`**. Read it when running the probe or reading
its leaderboard.

---

## Philosophy Mode

Cheap weekly check that runs the three Boris-derived signals as one
pass without spinning up the full 10-dim rubric or the trigger eval set.
Sibling to `freshen` and `trigger`. All three signals are grounded in
the first-party context-engineering blog (2026-07-24); the podcast
origin the name comes from is **unverified** (`sources.md`). Output is a
Boris score (0-3 anti-patterns flagged) plus the existing dim caps that
fire as a side-effect.

**Invocation:** `philosophy <skill-name>` · `batch philosophy --all`.
Surfaces findings only — never auto-applies mutations; the operator decides.

Full phase workflow (P0 Setup → P4 Persist), Boris score interpretation,
batch leaderboard, and anti-patterns live in
**`references/philosophy-patterns.md`**. Read it when running `philosophy`,
along with the three check sections P0 uses: `quality-rubric.md` §"Boris
Alignment Check", `freshen-patterns.md` §"4b. Scaffolding Decay Probes",
`trigger-patterns.md` §"Minimalism test (Boris alignment)".

---

## Additional Resources

### Reference Files

- **`references/improve-loop.md`** — The full **Improvement Loop workflow** (Phases 0–7): setup, cold scoring, hypothesis criteria, keep/discard decision rules, stop conditions, backlog persistence, landing the pass. Load when running `improve` (the default mode).
- **`references/quality-rubric.md`** — Full scoring rubric with sub-criteria, examples of each score level, and common failure patterns. Load this before scoring.
- **`references/improvement-patterns.md`** — Catalog of common improvements organized by dimension, with before/after examples.
- **`references/freshen-patterns.md`** — The full **Freshen Mode workflow** (F0–F6) plus reference-extraction heuristics, probe templates (gh CLI / WebFetch / WebSearch), and classification rules. Load when running `freshen`.
- **`references/trigger-patterns.md`** — The full **Trigger Mode workflow** (T0–T7) plus eval-set construction, mutation patterns by failure type, decision rules, and worked example. Load when running `trigger`.
- **`references/philosophy-patterns.md`** — The full **Philosophy Mode workflow** (P0–P4) plus Boris score interpretation, batch leaderboard, and anti-patterns. Load when running `philosophy`.
- **`references/floor-patterns.md`** — The full **Floor Mode** reference: the capability-uplift vs encoded-preference classification, the KNOWS / UNKNOWN / CONFLICTS bucket table, the two limits, and how floor evidence moves the Dim 10 cap. Load when running `knowledge-floor.py` / `floor-fleet.py` or reading a floor leaderboard.
- **`references/blind-validation.md`** — The blind-scorer agent, the `skill-comparator` A/B pass that decides the run verdict, model rule, fallback chain, parallel-scoring variant, and bias-check table format. Load when spawning a baseline or final blind agent, or the end-of-run comparator.
- **`references/fleet-checks.md`** — The six fleet checkers in detail: what each one
found when written, which of its hits are expected non-findings, and the three
sweep shapes already tried and abandoned. Load before running or proposing a sweep;
the SKILL.md table is the index, this is how to read the output.
- **`references/backlog-format.md`** — The `Open` / `Resolved this pass` section shapes, admission rules, and append-only history rule. Load when writing a target skill's `improvement-backlog.md` in Phase 6.
- **`references/anthropic-skill-design.md`** — Anthropic's skill design practices, complete frontmatter reference, Agent Skills standard, and platform constraints. Consult when scoring Dimensions 1, 2, 8, and 9.
- **`references/sources.md`** — Index of official docs, specs, changelogs, and blog posts, one row per URL with an optional `Pinned:` version or git ref. Freshen Mode probes every row and writes the single `Freshened: <date>` header stamp; per-row dates are legacy.
- **`<skill>/references/improvement-backlog.md`** (per-target, not in skill-improver's own dir) — Carries ceiling findings across skill-improver runs. Read in Phase 0 step 3; updated in Phase 6. Each target skill that has ever been through skill-improver should have one.
- **`<skill>/references/trigger-evals.json`** (per-target) — Persistent eval set for Trigger Mode. Built on first `trigger` run; reused and extended on subsequent runs. Schema: `[{"query": str, "should_trigger": bool, "source": str, "bucket": "explicit"|"implicit"|"contextual"|"negative"}, ...]`. The bucket splits positives by how the user phrases the request — see `trigger-patterns.md` §Phase T1 for the target mix and why `contextual` is the one that goes missing.

### Scripts

Every script, what it measures, and the failure it prevents:
**`references/scripts.md`**. Load it when choosing a tool for a phase.