Skip to content

dvy1987/agent-loom / .agents/skills/compress-skill

compress-skill

Verified

Compress an oversized SKILL.md to under 200 lines without losing effectiveness. Load when a skill exceeds 200 lines, when AGENTS.md triggers compression after a skill edit, or when the user asks to compress, shrink, slim down, or optimize a skill. Also triggers on "this skill is too long", "reduce skill size", "make this skill shorter". Applies to all skills including meta skills — the 200-line rule has no exceptions. Preserves hard gates, gotchas, output format, routing triggers, and at least one example. When genuinely CORE content cannot be compressed away, invokes split-skill instead of degrading the skill.

FileKindSize
SKILL.mdskill md9.0 KB
references/compression-theory.mdmarkdown2.2 KB
references/examples.mdmarkdown2.8 KB

references/compression-theory.md

View on GitHub
# Compression Theory — Why Less Is More

Read this if the user asks why compression improves quality, or questions whether compressing a skill will hurt its effectiveness.

---

## The SkillReducer Findings (arXiv:2603.29919, April 2026)

Researchers compressed 600 real-world skills and found:
- **39% average body token reduction**
- **Functional quality improved by 2.8%** on task benchmarks after compression
- **Less-is-more effect**: removing non-essential content reduces distraction in the context window, improving agent focus on what matters
- Skills in the 1–3k token range achieved 79% core reduction; >3k token skills achieved 89%

Key insight from the paper: over 60% of content in typical skill bodies is non-actionable — background, rationale, verbose explanations the LLM already knows from training. This content doesn't help the agent; it dilutes attention away from the rules and workflow steps that do.

## The Vercel Finding (2026)

Vercel benchmarked their Next.js agent on coding tasks:
| Approach | Pass Rate |
|----------|-----------|
| No help | 53% |
| Full 40KB skill docs | 53% |
| Forced instructions | 60–65% |
| **8KB compressed index in AGENTS.md** | **100%** |

The compressed index outperformed 40KB of raw documentation because **the best information is information the agent doesn't have to decide to retrieve**. When critical facts are always present in compressed form, the agent never misses them.

## What This Means for Compression

1. **Don't be afraid to cut.** If you're uncertain whether a line is needed, remove it and check the regression criteria. More often than not, the agent performs equally well or better without it.

2. **Background explanation is almost always cuttable.** The agent already knows why PRDs need clear requirements, why design should precede code, why gotchas matter. It doesn't need to be told.

3. **Workflow steps and hard gates are never cuttable.** These are the procedural knowledge the agent genuinely doesn't have — they're the reason the skill exists.

4. **Moving to references/ is not the same as deleting.** Content in references/ is still available — it just loads only when needed, keeping the active context window clean for the task at hand.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall