AGENTS.md · diff
git:20260116.eab3cdb to git:20260125.5174201
221 added, 22 removed. Audit A to A.
- # Recursive Decomposition Skill
+ # Recursive Decomposition Skills Repository
- This repository contains a Claude Code skill for handling long-context tasks through recursive decomposition strategies.
+ This repository contains Claude Code plugins for handling long-context tasks through recursive decomposition strategies. It serves as a marketplace for distributing these skills.
- ## Key Concept
+ ## Repository Structure
- Instead of loading all context into the processing window, treat inputs as environmental variables accessible through code. Decompose problems recursively, process segments independently, aggregate results programmatically.
+ ```
+ .claude-plugin/
+ marketplace.json # Marketplace catalog - lists all plugins
+ plugins/
+ recursive-decomposition/ # Plugin for recursive decomposition strategies
+ .claude-plugin/
+ plugin.json # Plugin manifest
+ skills/
+ recursive-decomposition/
+ SKILL.md # Main skill file
+ references/ # Supporting documentation
+ examples/ # Walkthrough examples
+ README.md
+ ```
- ## When This Skill Activates
+ ## Creating Claude Code Plugins
- - Tasks involving 10+ files
- - Input exceeding ~50k tokens
- - Phrases like "analyze all", "aggregate from", "search across"
- - Multi-document QA or codebase-wide analysis
+ ### Plugin Directory Structure
- ## Core Strategies
+ Each plugin follows this structure:
- 1. **Filter** — Use Grep/Glob to narrow before deep analysis
- 2. **Chunk** — Partition by size, semantics, or keywords
- 3. **Recurse** — Launch parallel sub-agents via Task tool
- 4. **Verify** — Re-check on smaller windows
- 5. **Synthesize** — Aggregate with deduplication
+ ```
+ my-plugin/
+ ├── .claude-plugin/
+ │ └── plugin.json # Required: Plugin manifest (only file in this dir)
+ ├── skills/ # Skill directories
+ │ └── skill-name/
+ │ ├── SKILL.md # Required: Main skill file
+ │ ├── references/ # Optional: Supporting docs
+ │ └── scripts/ # Optional: Utility scripts
+ └── README.md # Optional: Plugin documentation
+ ```
- ## File Structure
+ ### Plugin Manifest (`plugin.json`)
+ ```json
+ {
+ "name": "my-plugin",
+ "version": "1.0.0",
+ "description": "Brief description of the plugin",
+ "author": {
+ "name": "Your Name",
+ "email": "you@example.com"
+ }
+ }
```
- plugins/recursive-decomposition/skills/recursive-decomposition/
- ├── SKILL.md # Core instructions (always loaded when triggered)
- ├── references/ # Detailed strategies (loaded as needed)
- └── examples/ # Concrete walkthroughs (loaded as needed)
+
+ Required fields:
+ - `name`: Unique identifier in kebab-case
+
+ Optional fields:
+ - `version`: Semantic versioning (e.g., `"1.0.0"`)
+ - `description`: Brief explanation shown in plugin manager
+ - `author`: Object with `name` and optionally `email`
+
+ ### Skill Files (`SKILL.md`)
+
+ Skills teach Claude how to perform specific tasks. Each skill has a `SKILL.md` file with YAML frontmatter:
+
+ ```markdown
+ ---
+ name: skill-name
+ description: What the skill does and when to use it. Claude uses this for auto-discovery.
+ ---
+
+ # Skill Title
+
+ Skill content goes here...
```
- ## Based On
+ **Frontmatter fields:**
- [Recursive Language Models](https://arxiv.org/abs/2512.24601) — Zhang, Kraska, Khattab (2025)
+ | Field | Required | Description |
+ |-------|----------|-------------|
+ | `name` | Yes | Skill identifier (lowercase, hyphens, max 64 chars) |
+ | `description` | Yes | When to use this skill (max 1024 chars) - crucial for auto-discovery |
+ | `allowed-tools` | No | Tools Claude can use without permission (e.g., `"Read, Grep, Bash(node:*)"`) |
+ | `version` | No | Skill version |
+ | `license` | No | License identifier |
+
+ **Best practices:**
+ - Keep `SKILL.md` under 500 lines
+ - Use `references/` subdirectory for detailed documentation
+ - Write descriptions that match what users naturally say
+ - Include keywords users would search for
+
+ ### Supporting Files
+
+ Skills can include supporting files:
+
+ ```
+ skills/my-skill/
+ ├── SKILL.md # Main skill (required)
+ ├── references/ # Detailed documentation
+ │ ├── setup.md
+ │ └── examples.md
+ └── scripts/ # Utility scripts
+ ├── fetch.js
+ └── validate.js
+ ```
+
+ Reference these in your SKILL.md:
+ ```markdown
+ ## References
+
+ Consult these resources as needed:
+ - ./references/setup.md -- Setup and configuration guide
+ - ./references/examples.md -- Usage examples
+ ```
+
+ ## Marketplace Configuration
+
+ The `.claude-plugin/marketplace.json` file catalogs all plugins:
+
+ ```json
+ {
+ "name": "marketplace-name",
+ "owner": {
+ "name": "Owner Name",
+ "email": "owner@example.com"
+ },
+ "metadata": {
+ "description": "Marketplace description"
+ },
+ "plugins": [
+ {
+ "name": "plugin-name",
+ "source": "./plugins/plugin-name",
+ "description": "What the plugin does."
+ }
+ ]
+ }
+ ```
+
+ **Plugin entry fields:**
+ - `name` (required): Plugin identifier in kebab-case
+ - `source` (required): Relative path to plugin directory
+ - `description`: Brief description for the plugin list
+
+ ## Adding a New Plugin
+
+ 1. Create the plugin directory structure:
+ ```bash
+ mkdir -p plugins/my-plugin/.claude-plugin
+ mkdir -p plugins/my-plugin/skills/my-skill
+ ```
+
+ 2. Create `plugins/my-plugin/.claude-plugin/plugin.json`:
+ ```json
+ {
+ "name": "my-plugin",
+ "version": "1.0.0",
+ "description": "What the plugin does",
+ "author": {
+ "name": "Your Name",
+ "email": "you@example.com"
+ }
+ }
+ ```
+
+ 3. Create `plugins/my-plugin/skills/my-skill/SKILL.md`:
+ ```markdown
+ ---
+ name: my-skill
+ description: When to use this skill and what it does.
+ ---
+
+ # My Skill
+
+ Content...
+ ```
+
+ 4. Create `plugins/my-plugin/README.md`:
+ ```markdown
+ # My Plugin
+
+ Brief description.
+
+ ## License
+
+ MIT
+ ```
+
+ 5. Add to `.claude-plugin/marketplace.json`:
+ ```json
+ {
+ "name": "my-plugin",
+ "source": "./plugins/my-plugin",
+ "description": "What the plugin does."
+ }
+ ```
+
+ 6. Add to `README.md` installation examples:
+ ```
+ /plugin install my-plugin
+ ```
+
+ ## Testing Plugins
+
+ Test plugins locally before publishing:
+
+ ```bash
+ # Load plugin for testing
+ claude --plugin-dir ./plugins/recursive-decomposition
+
+ # Validate plugin structure
+ claude plugin validate ./plugins/recursive-decomposition
+ ```
+
+ ## User Installation
+
+ Users install plugins from this marketplace:
+
+ ```bash
+ # Add the marketplace
+ /plugin marketplace add recursive-decomposition-skill
+
+ # Install a plugin
+ /plugin install recursive-decomposition
+ ```
+
+ ## Conventions in This Repo
+
+ - **Plugin names**: Use kebab-case (e.g., `recursive-decomposition`)
+ - **Skill names**: Use kebab-case (e.g., `recursive-decomposition`)
+ - **File names**: Use kebab-case for all files
+ - **License**: MIT for all plugins
+ - **README.md**: Include in each plugin with brief description and license