Distillation for Agents
Claude Code Plugin
Codex Plugin
CI
Latest Release
A shared simplification skill for Claude Code and Codex. It finds the essential structure of an explanation, model, decision, process, design, or piece of writing, then simplifies it without losing the distinctions, evidence, and uncertainty the task depends on.
The procedure has six steps: frame what the work must accomplish, establish what has to survive, examine the structure before cutting anything, build a candidate and count its full cost, test it against the cases most likely to break it, then deliver the result and stop. Removal, recombination, a new representation, a corrected premise, and no change at all are all valid outcomes. Simple tasks get three quick questions instead of the full procedure.
Installation
Claude Code
Run these commands inside Claude Code:
/plugin marketplace add kylehughes/distillation-for-agents
/plugin install distillation-for-agents@distillation-for-agents
Start a new session after installation.
For a team repository, merge the following into .claude/settings.json:
{
"enabledPlugins": {
"distillation-for-agents@distillation-for-agents": true
},
"extraKnownMarketplaces": {
"distillation-for-agents": {
"source": {
"source": "github",
"repo": "kylehughes/distillation-for-agents"
}
}
}
}
Claude Code prompts team members to install the plugin when they trust the repository's marketplace configuration. See Claude Code's marketplace documentation.
Codex
With a Codex CLI version that supports plugin marketplaces, run:
codex plugin marketplace add kylehughes/distillation-for-agents
codex plugin add distillation-for-agents@distillation-for-agents
Start a new session after installation. Codex gets the same skill as Claude Code.
These commands use Codex's plugin marketplace support. The repository includes a portable plugin.json, a compatible .codex-plugin/plugin.json, and a Codex marketplace catalog.
Standalone skill
Download distill-skill.zip from the releases page. Extract it into a directory named distill in your host's skills directory. The archive has SKILL.md at its root and includes its references, UI metadata, icon, and license.
For the Claude apps, download distill.skill instead and upload it under Settings → Capabilities → Skills. It holds the same files inside a distill/ folder.
For Codex, a user-level skill can live at ~/.agents/skills/distill/. Install either the standalone skill or the plugin, not both, so the skill isn't discovered twice. Other Agent Skills hosts can use the same directory.
Usage
Ask in plain language:
Distill this design doc down to the decisions that actually matter.
We keep adding exceptions to this onboarding process. Find the rule underneath them.
Explain how TCP congestion control works from first principles, without leaning on the jargon.
The skill can be selected automatically when its description matches your task. It stays out of the way for simple lookups, mechanical edits, and instructions that are already clear. To select it explicitly in Codex, type $ and choose distillation-for-agents:distill from the skill picker. A standalone installation uses $distill. In Claude Code, use /distillation-for-agents:distill.
Distill delivers the requested result, not a worksheet. It reports consequential tradeoffs and the checks it actually ran. When a simplification would drop a necessary distinction or overstate a claim, it keeps the complexity or narrows the claim.
The skill contains the procedure. Its references are loaded on demand: operators for choosing a technique, validation for testing losses, examples, and the foundations and sources behind the method. No extra tools, credentials, or runtime dependencies are needed to use the skill.
Development
Use Python 3.10 or later for the repository checks and packaging:
python3 scripts/check.py
python3 -m unittest discover -s scripts -p 'test_*.py'
python3 scripts/package.py
The checks verify manifest consistency, skill metadata against the .skill upload rules, local references, and the license. Packaging creates three archives in dist/: distill-skill.zip for manual installation, distill.skill for upload to the Claude apps, and distill-plugin.zip, which contains the shared skill, runtime manifests, and license.
Validate a local checkout with Claude Code:
claude plugin validate .claude-plugin/plugin.json
claude plugin validate .claude-plugin/marketplace.json
claude --plugin-dir .
Claude's validator warns that the checkout's CLAUDE.md is not installed plugin context. It imports maintainer instructions from AGENTS.md; both files are excluded from the plugin archive. Validate the extracted plugin archive with --strict to check the shipping contents without that repository-only warning.
To test the local marketplace in Codex, run codex plugin marketplace add "$PWD", install the plugin with the command above, and start a new session. When switching between a local checkout and the GitHub marketplace, remove the existing source with codex plugin marketplace remove distillation-for-agents before adding the replacement.
Source updates
Record any new or changed research claim in sources.md with its passage, edition, and caveat, and keep existing source IDs stable. Check every worked example against its stated premises. Keep the entrypoint short and put detailed guidance in the references.
Releases
From a clean main branch, check a proposed release without changing the repository:
./release.sh --dry-run 1.0.1
Run ./release.sh 1.0.1 to update all manifest versions, validate and package the content, commit, tag, and push the branch and new tag together. The release workflow checks that the tag matches the manifests and publishes all three archives.
Contributions
Not accepting source contributions. Bug reports are welcome.
Author
License
Distributed under the MIT License.