# Squid Clean Harness

> Shrink an agent harness (.agents/ skills + resources) to the minimum tokens that keep the exact same logic. Never touches resources/datasets/.

- Skill: `iusztinpaul/squid-clean-harness` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iusztinpaul/squid-clean-harness`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iusztinpaul/squid-clean-harness/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: iusztinpaul (https://skillmd.com/u/iusztinpaul)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iusztinpaul/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

| 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:

```sh
grep -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.md` frontmatter still parses as YAML with `name` + `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.