dvy1987/agent-loom / .agents/skills/compress-skill
compress-skill
VerifiedCompress 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.0 KB |
| references/compression-theory.md | markdown | 2.2 KB |
| references/examples.md | markdown | 2.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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |