Squid Clean Docs: A Skill That Deletes Words, Not Behavior

Where this fits

Your agent just finished a refactor and left comments that explain what the code already says—or a docs pass added three paragraphs where one sentence would do. You want cleaner prose, but you don't want to review a diff that might have changed a conditional or broken a docstring import. squid-clean-docs is a skill that strips redundant prose from docs, READMEs, comments, and docstrings while keeping runtime behavior identical.

Why agents benefit

• The skill gives the agent a clear zero-behavior-diff contract: deletions that could alter runtime are out of scope.
• A scope-path argument lets the agent work on docs/ or src/ingest/ instead of scanning an entire repository.
• The built-in exclusion table protects ADRs, notes, and changelogs without hand-written ignore rules.
• It explicitly separates executable code from prose, reducing the risk of generated edits touching logic.
• The README defines a deterministic workflow an agent can follow without guessing what “clean” means.

Practical scenarios

Docs cleanup after a feature branch

After a large PR, the README and docs/ are full of duplicate explanations. The agent runs the skill with the default scope, deletes redundant prose, and leaves the human to review a docs-only diff.

Tightening code comments before a library release

The package uses docstrings to generate API docs. Before publishing, the agent runs the skill on src/, removes stale or repetitive comments, and keeps every function signature and default value untouched.

Repo-wide consistency pass

A maintainer wants concise documentation across the whole repo. Running with an empty scope cleans everything except protected paths, giving a consistent tone while preserving historical ADRs and personal notes.

Add it to your agent workflow

Install the skill with:

npx skills add iusztinpaul/squid --skill squid-clean-docs

Then invoke it in an agent prompt or workflow step:

Run squid-clean-docs on docs/. Only delete redundant prose; do not change code.

The optional scope argument controls blast radius. Empty means the whole repo, and protected paths are skipped automatically.

Compare before adopting

Before adopting, compare these signals:

• Quality signals: Does the skill produce diffs that are purely deletions? Does it respect its own exclusions?
• Maintenance freshness: Check recent commits and issue responses, not just star count.
• Alternatives: Generic cleanup prompts or linters like markdownlint can catch style issues, but they don’t reason about semantic redundancy the way an agent can.
• Workflow fit: The skill works best when a human or CI already reviews docs diffs, so the zero-behavior contract has an extra safety net.

Why it is worth tracking

squid-clean-docs is a compact, well-scoped skill with a clear contract and an explicit exclusion table. At 184 stars, the community signal is modest but real; the strongest signal is that its “zero behavior diff” rule makes agent output predictable. Track it in OpenAgentSkill here and evaluate it whenever your agent touches prose around code—especially if docs debt is accumulating faster than humans can review it.