Squid Clean Harness

Clean harness — same logic, minimum tokens

You are the cleaner. You shrink the skills and resources a harness loads; you do not change what they make the agent do. Zero logic diff is the contract — every capability, step, and rule that holds before must hold after; only tokens die.

$ARGUMENTS is an optional .agents/ path (e.g. ~/Vaults/Second-Brain/.agents). Empty means the repo's ./.agents.

When NOT to use — out of scope, no exceptions

Step 1 — Resolve the target set

Inventory skills/*/SKILL.md and resources/** minus resources/datasets/ under the target .agents/. Everything must be revertible: clean in git, or snapshot first (cp -R .agents .agents.bak) when the tree isn't tracked.

Step 2 — Audit the contract (frontmatter)

Two questions per skill:

• Invocation type — auto-fired by the model, or only typed by the user? User-only → disable-model-invocation: true, keeping its description out of the always-loaded skill list. Flipping also cuts reach from other skills — grep the set for the skill's name first (Step 4's proof); one referrer means it stays model-invoked.
• Description — must match what the body does. Model-invoked → triggers only, one per branch: synonyms naming the same branch are duplication ("build with TDD" / "asks for test-first development" is one branch written twice). User-only → one sentence of what it does; trigger prose serves no router — delete it.

Done only when every skill in the set has both answers recorded — no sampling.

Step 3 — Apply the keep/delete test

An instruction survives only if deleting it would change what the agent does. The cuts apply to every file in the set — skill bodies and resources/ docs alike. Five cuts:

Duplicates — the same rule twice in one skill, repeated across skills, or restating a resources/ doc the skill already points at (a skill body repeating glossary.md definitions) — the resource is the home, the skill keeps the pointer. Two resources repeating each other collapse to one home the same way.

Baked-in claims — would the agent already behave this way with the line deleted (harness default, system-prompt rule)? Dead weight. "Read the file before editing it" dies; "write posts in the voice defined in resources/branding/" stays. The test is harness-relative — .agents/ serves non-Claude agents too: delete only defaults universal to whatever loads the skill; flag the Claude Code-specific ones. Test sentence by sentence; a failing sentence dies whole — never trim words from it.

Verbose logic — the exact same logic in the minimum words: collapse restatements, prefer a table row to a paragraph, caveman-terse wording. Collapse a restated quality into one pretrained leading word ("fast, deterministic, low-overhead" → a tight loop). If the caveman plugin is installed, /caveman-compress per file is a good first draft — re-check afterwards that the frontmatter is still parseable YAML.

Merges — steps or sections nobody reads apart become one; reorder so each idea appears once, at the point the agent needs it.

Disclosure — a skill body is paid for on every invocation, including the branches that never read it. Inline what every branch needs; push what only some branches reach — a lookup table, a per-platform appendix, a rare edge-case procedure — into a resources/ doc loaded on demand. Same home for a block ≥2 skills share. Size decides: ~20+ lines earns its own file, below that indirection costs a Read for less than it saves. The pointer must say when to load it, not just where it lives ("for the Slack variants, read platforms.md", not "see platforms.md"). Theory: /squid-write-skill.

Done only when every file in the set is read whole and judged against all five cuts.