Skip to content
2 changes: 1 addition & 1 deletion docs/CATALOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc

- [`desktop-notification`](../plugins/desktop-notification) — Alert you when Claude Code needs input — an audible terminal bell, an OSC 9 terminal notification, and an OS-native toast (macOS/Linux) on permission and idle prompts.
- [`playbooks`](../plugins/playbooks) — Doctrine and knowledge playbooks as on-demand skills, plus a maintainer-facing update skill. boris — Boris Cherny's Claude Code workflow tips (howborisusesclaudecode.com); skill-authoring — Anthropic's internal skill-authoring playbook; fable-5 — Claude Fable 5's operating doctrine (self-authored, no upstream). The boris and skill-authoring packs vendor a verbatim upstream baseline; /playbooks:update drift-checks and syncs those baselines centrally (maintainers).
- [`claude-config`](../plugins/claude-config) — Five audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), and audit-pass (one coordinated, ordered, resumable pass over a named target — three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate — delegating every check to the plugin that owns it).
- [`claude-config`](../plugins/claude-config) — Six configuration-health skills (plus setup) for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), audit-pass (one coordinated, ordered, resumable pass over a named target — three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate — delegating every check to the plugin that owns it), and unhobble (the empirical bare-baseline experiment: reversibly strip a repo's standing instructions, log real stumbles against the current model, re-add only what evidence earns).
- [`claude-memory`](../plugins/claude-memory) — Keeps a repo's Claude Code memory layer healthy and under your control, against criteria derived from official Claude Code documentation. The audit skill checks the instruction/memory layer (CLAUDE.md, CLAUDE.local.md, .claude/rules/, auto-memory) with a deterministic script-backed spine plus judgment-tier checks. The stateless skill inspects, disables, and (confirm-gated) purges Claude-written auto memory across all settings scopes.
- [`claude-ops`](../plugins/claude-ops) — Claude Code operations toolkit. Seven skills: observability (read locally captured telemetry — OTEL store, collector, hook-event JSONL, ccusage — with trend reports and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand — marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view — queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort, a repo-pull + marketplace-refresh launch step, and a consume-restarts action — an OS-schedulable reader that relaunches stopped lanes whose telemetry carries a restart_request), and a re-runnable setup action that settles where the known-issues registry lives. Plus a family of seven advisory *-audit telemetry-emitter hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures) that emit the shared hook-telemetry envelope, and a reference sink that maps envelopes into the hook-events.jsonl the observability skill reads.
- [`rate-limit-guard`](../plugins/rate-limit-guard) — Shared rate-limit guard for loop lanes: a statusline wrapper tees the subscription rate-limit windows to a fixed machine-scope file, a StopFailure hook records rate-limit stops reactively, and a reader contract fixes how consuming sessions pause and resume.
Expand Down
45 changes: 45 additions & 0 deletions docs/PLUGIN-PHILOSOPHY.md
Original file line number Diff line number Diff line change
Expand Up @@ -460,6 +460,51 @@ path and prerequisite tests, local `--plugin-dir` smoke tests, and the repositor
Apply the standards principles of explicit behavior, fail-fast boundaries, idempotency, one mechanism
per concern, cross-platform operation, and stress-testing before presentation.

## Instruction economy

Every standing instruction this marketplace ships — a CLAUDE.md line, a hook that corrects model
behavior, a skill's always-loaded listing text — is a per-session tax on every consumer, paid
whether or not the instruction ever fires. Official doctrine is explicit: "CLAUDE.md is loaded
every session, so only include things that apply broadly… For each line, ask: 'Would removing this
cause Claude to make mistakes?' If not, cut it," and "If Claude already does something correctly
without the instruction, delete it or convert it to a hook"
([best-practices](https://code.claude.com/docs/en/best-practices), verified 2026-08-08). Anthropic
applied the same doctrine to Claude Code itself, removing over 80% of its system prompt for the
Opus 5 / Fable 5 generation with no measurable loss on its coding evaluations
([The new rules of context engineering for Claude 5 generation models](https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models),
verified 2026-08-08). Four rules follow:

- **Evidence-gated additions.** A new standing instruction requires observed, repeated stumble
evidence against the current model — the same failure seen more than once — never anticipation
of a failure a past model had. Name the evidence where the instruction is added (PR body or an
adjacent comment). Anticipatory instructions are the veteran-engineer failure mode: they encode
the last model's weaknesses as the next model's ceiling.
- **Generation-triggered ablation.** Instructions are disposable per model generation. At each
frontier model release, re-audit standing instruction surfaces against the new model
(`claude-config:audit-instructions` for the static text-vs-doctrine pass;
`claude-config:unhobble` for the empirical bare-baseline experiment) and delete what the model no
longer needs. The trigger is the model release, not the calendar.
- **Evals outlive instructions.** Per-skill evals are the durable asset across this churn: keep and
extend them until a model generation saturates them, then replace them with evals derived from
newly observed struggles. Expect an eval to outlive the instructions it graded by roughly one to
three model generations. Deleting an instruction never deletes its eval; the eval is how the next
deletion round proves itself safe.
- **The durable tier is exempt.** Deterministic policy hooks (gates that enforce team or safety
policy regardless of model capability) and team conventions checked into git are the officially
carved-out durable instruction tiers. Classify a hook honestly before keeping it: a hook that
enforces policy survives ablation; a hook that corrects model behavior is an ablation candidate
like any prose instruction.

Model-capability claims never relax the security posture. Injection resistance in current models is
measurably better but bounded and hedged in the primary sources; the plugin-acceptance security
review's deny-by-default stance on egress and trust delegation is policy, not a model-era
workaround, and stays regardless of model generation.

The complementary task-design doctrine — describe the task, guardrails, and exit criteria, give the
model a way to verify its own work, and skip step-by-step procedure — is already this marketplace's
encoded practice: the `verification`, `planning` (goal conditions), `tdd`, and `testing` plugins are
its implementation, and need no new mechanism on its account.

## Fresh-eyes checkpoints

A context that produced work is structurally the weakest place to judge that work: the reasoning that
Expand Down
1 change: 1 addition & 0 deletions docs/SKILL-CHEAT-SHEET.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,7 @@ owned by [docs/CATALOG-TAXONOMY.md](CATALOG-TAXONOMY.md).
| [`/claude-config:audit-instructions`](../plugins/claude-config/skills/audit-instructions/SKILL.md) | `claude-config` | Find instructions current models no longer need across CLAUDE.md, rules, and skill bodies |
| [`/claude-config:audit-pass`](../plugins/claude-config/skills/audit-pass/SKILL.md) | `claude-config` | Run one coordinated, resumable audit pass over a repo with a single human gate |
| [`/claude-config:audit-permission-grants`](../plugins/claude-config/skills/audit-permission-grants/SKILL.md) | `claude-config` | Audit permission grants for portability and auto-mode durability |
| [`/claude-config:unhobble`](../plugins/claude-config/skills/unhobble/SKILL.md) | `claude-config` | Strip instructions to a bare baseline, log real stumbles, re-add only what evidence earns |
| [`/claude-memory:audit`](../plugins/claude-memory/skills/audit/SKILL.md) | `claude-memory` | Audit CLAUDE.md, rules, and auto-memory against the official-docs checklist |
| [`/claude-memory:stateless`](../plugins/claude-memory/skills/stateless/SKILL.md) | `claude-memory` | Inspect, disable, or purge Claude Code's per-repo auto memory |
| [`/claude-ops:changelog`](../plugins/claude-ops/skills/changelog/SKILL.md) | `claude-ops` | Ingest a Claude Code release changelog and integrate its changes into the repo |
Expand Down
4 changes: 2 additions & 2 deletions plugins/claude-config/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
"name": "claude-config",
"version": "0.22.1",
"description": "Five audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), and audit-pass (one coordinated, ordered, resumable pass over a named target — three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate — delegating every check to the plugin that owns it).",
"version": "0.23.0",
"description": "Six configuration-health skills (plus setup) for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs, and detects cross-surface instruction conflicts), audit-pass (one coordinated, ordered, resumable pass over a named target — three-scope inventory, run-time-derived exclusion set, stable finding identity, suppression memory, resume, one human gate — delegating every check to the plugin that owns it), and unhobble (the empirical bare-baseline experiment: reversibly strip a repo's standing instructions, log real stumbles against the current model, re-add only what evidence earns).",
"author": {
"name": "Melodic Software",
"email": "info@melodicsoftware.com"
Expand Down
18 changes: 18 additions & 0 deletions plugins/claude-config/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,24 @@
All notable changes to the `claude-config` plugin are documented here. Format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.

## [0.23.0]

### Added

- **New `unhobble` skill — the empirical bare-baseline experiment.** Reversibly strips a project's
standing instruction surfaces (CLAUDE.md, rules, behavioral hooks, skills, enabled plugins) on a
dedicated experiment branch, has the operator work normally against the bare model while logging
observed stumbles to a ledger, then re-adds only instructions with repeated same-cause evidence —
each restore citing its ledger rows. Policy-classified hooks and managed settings are never
stripped; every mutation is human-gated; state persists under `${CLAUDE_PLUGIN_DATA}/unhobble/`
for resume. The canonical trigger is a frontier model release. Operationalizes the
delete-and-re-add doctrine from official best-practices ("Would removing this cause Claude to
make mistakes? If not, cut it") and Anthropic's own 80% system-prompt reduction for the
Opus 5 / Fable 5 generation; `audit-instructions` remains the static text-vs-doctrine
counterpart and receives routed rewrite judgments. Tracked-file stripping is delete-with-net
(`git rm` on the experiment branch) rather than in-place disable — a deliberate choice: git is
the restore mechanism, and a renamed-but-present file could still be read.

## [0.22.1]

### Fixed
Expand Down
28 changes: 26 additions & 2 deletions plugins/claude-config/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
# claude-config

A Claude Code plugin bundling five audit skills for one cohesive capability: keeping a repo's Claude
Code configuration healthy. Each skill answers a different question about the same surface:
A Claude Code plugin bundling six configuration-health skills (plus a `setup` skill) for one
cohesive capability: keeping a repo's Claude Code configuration healthy. Each skill answers a
different question about the same surface:

| Skill | Question it answers |
|---|---|
Expand All @@ -10,6 +11,7 @@ Code configuration healthy. Each skill answers a different question about the sa
| `/claude-config:audit-permission-grants` | Are the permission GRANTS (`allowed-tools`, `permissions.allow`) portable and durable — do they survive auto mode, work across machines, and live where they can take effect? |
| `/claude-config:audit-instructions` | Are the INSTRUCTIONS you wrote (CLAUDE.md, rules, skill bodies, agents, hooks, output styles) still earning their context cost against current model capability, or is prior-model scar tissue holding the model back? |
| `/claude-config:audit-pass` | Can all of that run as ONE ordered, resumable pass over a named target — every scope inventoried before any check, one reconciled findings artifact, one human gate — instead of several separate runs whose results nobody reconciles? |
| `/claude-config:unhobble` | What does the CURRENT MODEL actually still need — measured, not reasoned: reversibly strip the project's standing instructions to a bare baseline, log real stumbles, and re-add only what the evidence earns back? |

The instruction/memory-layer *hygiene* question (is `CLAUDE.md` too long, well-placed, free of
inferable content) is owned by the `audit` skill in the separate `claude-memory` plugin;
Expand Down Expand Up @@ -118,6 +120,28 @@ delegated skills accept no target of their own, so a run pointed elsewhere would
while every delegated finding came from the active project. Audit another repository by opening it
as the project.

### unhobble

The empirical counterpart to `audit-instructions`: instead of judging instruction *text* against
doctrine, it measures the *model* against the repo with the instructions gone. Four resumable
phases: **snapshot** (inventory the live project surfaces on a dedicated experiment branch, classify
hooks policy-vs-behavioral), **bare** (reversibly strip the behavioral tier — tracked files via git,
settings entries via manifest-recorded backups; policy gates and managed settings are never
touched), **observe** (work normally in fresh sessions, logging real stumbles to a ledger), and
**readd** (restore only instructions with at least two same-cause ledger rows, each restore citing
its evidence; everything else stays deleted, with git history as the archive). The canonical trigger
is a frontier model release — instructions written for the previous generation are the experiment's
subject. Human-gated at every mutation; state persists under `${CLAUDE_PLUGIN_DATA}` for resume.

```shell
/claude-config:unhobble # guided full flow
/claude-config:unhobble snapshot # inventory + classify + strip plan
/claude-config:unhobble bare # apply the confirmed strip plan
/claude-config:unhobble observe # ledger instructions for the observation window
/claude-config:unhobble readd # evidence-gated restores; close the experiment
/claude-config:unhobble status # manifest summary: phase, ledger rows, candidates
```

## Consumer conventions

The skills read the consuming repo's own `CLAUDE.md` / `.claude/rules/` for project-specific policy:
Expand Down
6 changes: 5 additions & 1 deletion plugins/claude-config/skills/audit-instructions/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ concerns its siblings already cover — route rather than re-answer:
- Token brevity for its own sake is `docs-hygiene:compress`.
- Config-file mechanics (settings.json, .mcp.json, hooks wiring) is `claude-config:audit`; grant
portability is `claude-config:audit-permission-grants`.
- The empirical bare-baseline experiment — strip the surfaces, observe the bare model, re-add on
repeated stumble evidence — is `unhobble` (same plugin): this skill judges instruction *text*
against doctrine; unhobble measures the *model*.

On **memory-layer surfaces** (CLAUDE.md, CLAUDE.local.md, `.claude/rules/`, `~/.claude/rules/`),
this skill runs only the model-era checks I6–I22. It never runs or reports the hygiene checks
Expand Down Expand Up @@ -354,7 +357,8 @@ End with a **Routing** subsection listing every excluded upstream-owned
or memory-layer surface and where its findings should go, and a **Recommended follow-through**
subsection: apply an accepted change, then observe whether Claude's behavior actually shifts;
re-add on the next mistake as the compounding safety net; for example blocks, A/B against the
no-example default. That loop is prose guidance — this skill ships no eval tooling.
no-example default. The full delete-and-watch loop is operationalized by `/claude-config:unhobble`
(same plugin) — route there when the operator wants the experiment run rather than described.

Open the Sources line with the two official pages the paths and doctrine derive from
(code.claude.com memory + `.claude`-directory docs; the prompting pages cited per check in the
Expand Down
Loading
Loading