massimodeluisa/recursive-decomposition-skill

52 stars Quality 66 Trend 37MIT

Claude Code skill for handling long-context tasks through recursive decomposition

Overview

Decompose long-context tasks while keeping the context small. An Agent Skill for Claude Code, Codex, Cursor and compatible agents, based on the Recursive Language Models research Install · Usage · How it works · Eval · Structure · Acknowledgments Large codebases, dozens of documents, long reports: as the context grows, models miss details, link distant parts by guesswork and lose accuracy. The Recursive Language Models paper calls it context rot. When a task is codebase-wide, multi-document, a pile of PDFs, or a dense aggregate, even if it fits the window, the skill makes the agent treat the input as an environment to query instead of text to swallow: 1. the input before reading anything. 2. the search space with searches, not reads. 3. what remains into batches of 5 to 10 files or natural units. 4. at depth 1 with one sub-agent per batch, each with a self-contained brief. Sub-agents do not spawn sub-agents. 5. the merged answer on a small window against the sources. 6.

README

Recursive Decomposition Skill

Decompose long-context tasks while keeping the context small. An Agent Skill for Claude Code, Codex, Cursor and compatible agents, based on the Recursive Language Models research

Install · Usage · How it works · Eval · Structure · Acknowledgments

The problem

Large codebases, dozens of documents, long reports: as the context grows, models miss details, link distant parts by guesswork and lose accuracy. The Recursive Language Models paper calls it context rot.

What it does

When a task is codebase-wide, multi-document, a pile of PDFs, or a dense aggregate, even if it fits the window, the skill makes the agent treat the input as an environment to query instead of text to swallow:

Size the input before reading anything.
Filter the search space with searches, not reads.
Chunk what remains into batches of 5 to 10 files or natural units.
Recurse at depth 1 with one sub-agent per batch, each with a self-contained brief. Sub-agents do not spawn sub-agents.
Verify the merged answer on a small window against the sources.
Synthesise programmatically, with file and line references.

PDFs go through anydoc first (npx -y @firecrawl/anydoc FILE -o .firecrawl/out.md), then grep the markdown. Cloud firecrawl parse is for OCR, -Q, or -S. A one-page convert job is not this skill.

Install

With the skills CLI:

npx skills add massimodeluisa/recursive-decomposition-skill

Add -g for a user-level install, -a claude-code (or another agent) to target one agent.

As a Claude Code plugin:

claude plugin marketplace add massimodeluisa/recursive-decomposition-skill
claude plugin install recursive-decomposition@recursive-decomposition-skill

Manual: copy skills/recursive-decomposition into ~/.claude/skills/ (or your agent’s skills directory) and restart the agent.

Usage

/recursive-decomposition applies the protocol to the current task.
/recursive-decomposition src/ sizes that input first, then runs the protocol.

The skill also activates on its own for prompts like:

Analyze error handling patterns across this entire codebase
Find all TODO comments in the project and categorize by priority
What API endpoints are defined across all route files?
Summarize the key decisions from all meeting notes in docs/
Find security issues across all Python files

How it works

Situation	Approach
One file, one function, or a single needle	Read directly
Linear aggregate or list-everything, and completeness matters	Decompose
Pairwise, quadratic, or multi-hop across scattered sources	Decompose, even under 30k tokens
10+ files or 50k+ tokens	Decompose
Under 30k tokens and a localised answer	Read directly

Results reported in the paper:

Task	Direct model	With RLM
Multi-hop QA (6 to 11M tokens)	70%	91%
Linear aggregation	baseline	+28 to 33%
Quadratic reasoning	under 0.1%	58%
Context scaling	2^14 tokens	2^18 tokens

RLM runs were about 3x cheaper than summarisation baselines.

Eval

Fixture is a git submodule, not files copied into this repo: tccao/mortgage-doc-rag (MIT), 131 public-domain mortgage PDFs, about 63 MB. Thanks to that project for the corpus.

git submodule update --init --depth 1 skills/recursive-decomposition/evals/files/mortgage-doc-rag
bash .github/scripts/eval-skill.sh check

Pre/post on that tree, same prompt (count, 10 largest, titles from at most three files):

Path	What ran	Time	Titles from the 3 largest
With skill	size first, anydoc on 2 digital PDFs, `firecrawl parse` on 1 scan (anydoc exit 3)	size 0.02 s; anydoc 1.64 s; OCR parse 15.45 s	APPRAISAL OF REAL PROPERTY; TILA RESPA Integrated Disclosure; Uniform Residential Appraisal Report
Without skill	`pdftotext` on all 131 PDFs	1.65 s	two titles from digital PDFs; empty on the largest file (scan, 4 bytes)

The naive path is faster and blind on scans. The skill is slower because it OCRs one file, and that is the file pdftotext cannot read. Details: evals/README.md.

Repository structure

recursive-decomposition-skill/
├── .claude-plugin/          plugin.json, marketplace.json (the repo is the plugin)
├── .github/                 bash validator and CI workflow
├── skills/recursive-decomposition/
│   ├── SKILL.md             protocol, rules, patterns
│   ├── references/          rlm-strategies, cost-analysis, codebase-analysis, document-aggregation
│   └── evals/               trigger queries, mortgage PDF submodule, bash scorer
├── assets/                  social preview, logo (light and dark)
├── AGENTS.md · CONVENTIONS.md · CONTRIBUTING.md · CHANGELOG.md
└── LICENSE

Acknowledgments

This skill is based on the Recursive Language Models paper. Thanks to the authors:

Recursive Language Models, Alex L. Zhang, Tim Kraska, Omar Khattab, arXiv:2512.24601, December 2025. Abstract · PDF

Eval corpus: tccao/mortgage-doc-rag (MIT), public-domain mortgage PDFs. Thanks to that project.

PDF conversion: Firecrawl anydoc and firecrawl-parse. Thanks to Firecrawl.

This skill is an independent project and is not affiliated with the paper authors, MIT, tccao, or Firecrawl.

Author

Massimo De Luisa: massimo.deluisa.bio

License

MIT, see LICENSE.

View this README on GitHub

Recommended Tools

Try a different keyword or remove a filter.

Install

npx skillfish add massimodeluisa/recursive-decomposition-skill