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
| Excluded | Why |
|---|---|
resources/datasets/ | Data the skills operate on, not logic. Never in scope. |
Memory files (AGENTS.md, CLAUDE.md) | → /squid-clean-memory. |
| Docs, READMEs, comments, docstrings | → /squid-clean-docs. |
| Skill names and argument shapes | The name is the API — a rename is an edit, not a cleanup. |
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.
Step 4 — Dangling artifacts
A reference, script, agent, or resources/ doc is dead only with zero references outside its
own definition:
shgrep -rn "helper.py" <harness-root> <project-root> # prove it, don't assume
- A rule dangles by staleness, not references — nobody cites a rule, they read it. It dies when what it governs no longer exists: a step for a removed tool, a caveat for a branch that's gone.
- Referenced but missing → a broken contract, not a deletion: flag it and ask.
- Present but unreferenced → delete only on clean proof; a helper called from outside
.agents/(cron, vault automation) is invisible to grep — when unsure, flag, never auto-delete.
Done only when every artifact is proven dead, alive, or flagged.
Step 5 — Plan of attack (the output artifact)
Print one table in chat. Do not write it to disk unless the user asks.
| File | Cut (Step 2–4) | Why | ~Words |
|---|---|---|---|
skills/search/SKILL.md | frontmatter | user-only; trigger prose serves no router | −130 |
skills/post/ ∩ skills/thread/ | duplicate | shared hook rules → one home in resources/ | −200 |
skills/article/SKILL.md | verbose | Step 2 restated three ways | −90 |
skills/publish/SKILL.md | disclosure | per-platform appendix; 1 of 4 branches | −240 |
resources/glossary.md | verbose | each term defined twice, prose + table | −150 |
Stop and wait for explicit approval. Do not edit before it.
Step 6 — Execute
Apply the approved plan, one commit per category (frontmatter, cuts, dangling) so any revert is
surgical.
Step 7 — Verify
Logic must be provably unchanged before hand-off:
- Every
SKILL.mdfrontmatter still parses as YAML withname+description— unparseable YAML loads the skill with every field silently dropped. - Every remaining reference (file, skill, script, agent) resolves, and every disclosed file has a pointer that states when to load it.
- Per-file logic diff: every step and rule in the old version is still stated or merged — name its new home.
- No skill or argument was renamed.
Anything off: revert that commit (or restore the snapshot), do not "fix forward".
Step 8 — Hand-off
Report wc -w before → after per file, what moved into resources/, and every flagged dangling
item. Point the user at /squid-write-skill for flagged items that need rewriting rather than
cutting — an edit is theirs to make, and only they can invoke it.
