capsule-compact — Claude Code skill: what it does and how to install
The capsule-compact Claude Code skill condenses long chains of context capsules. Run it on request or when a chain has grown too long.
MIT ★ 26 updated 2026-11-16
npx skills add wrg32786/aigent-os --skill capsule-compact -a claude-codeWhat capsule-compact does
The skill runs python3 daemons/capsule-compact.py <head_capsule_id> from the vault root, following parent links back from the chosen head. Once a chain reaches five capsules, it combines the three oldest into one summary. The script rewires the links and tags each compacted capsule with compacted_into.
The summary uses structured fields: objectives, live open threads, and held decisions. No LLM is involved, and the original capsules stay on disk. The script does not follow forks or compact automatically at /close; that step only reports the chain length. Set a different threshold or summary size with --threshold N and --summarize-count N. Running it requires python3.
What it helps with
- condense a long context-capsule chain
- combine older capsules into one summary
- update parent links after compaction
- keep source capsules marked with their summary
Example prompts for the agent
- Compact the capsule chain starting at
head_capsule_id. - Summarize the older capsules in this chain.
- Compact the chain at a threshold of five, summarizing three capsules.
How to install capsule-compact
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill capsule-compact -a claude-code2Manually: put the files in place
~/.claude/skills/capsule-compact/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/capsule-compact/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill capsule-compact -a codex2Manually: put the files in place
.agents/skills/capsule-compact/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill capsule-compact -a cursor2Manually: put the files in place
.cursor/skills/capsule-compact/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install wrg32786/aigent-os skills/capsule-compact2Manually: put the files in place
.github/skills/capsule-compact/SKILL.md1Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill capsule-compact -a gemini-cli2Platform CLI
gemini skills install https://github.com/wrg32786/aigent-os --path skills/capsule-compactManually: put the files in place
.devin/skills/capsule-compact/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add wrg32786/aigent-os --skill capsule-compact -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about capsule-compact
How do I install capsule-compact in Claude Code?
Run npx skills add wrg32786/aigent-os --skill capsule-compact -a claude-code. The skill file will be at ~/.claude/skills/capsule-compact/SKILL.md.
What does capsule-compact do?
When a chain has at least five capsules, it combines the three oldest into a structured summary and adjusts the parent links. The original files remain on disk and receive a compacted_into marker.
What does capsule-compact need to run?
It requires python3. Run the script from the vault root with python3 daemons/capsule-compact.py <head_capsule_id>.
Source text
SKILL.md · MIT
--- name: capsule-compact agent: none description: "Compact capsule chains by summarizing older capsules. Use when manually compacting capsules or a context chain grows too long." allowed-tools: Bash, Read user-invocable: true triggers: - capsule compact - compact chain - chain compaction - compact capsules - /capsule-compact - chain too long --- # /capsule-compact Run `python3 daemons/capsule-compact.py <head_capsule_id>` from the vault root. The script: 1. Walks `parent_capsule_id` chain backward from the head 2. If chain length >= 5, summarizes the oldest 3 capsules into a single `chain-summary-<head>-<date>.md` capsule 3. Updates pointers: boundary capsule's parent → summary; summary's parent → original chain root's parent 4. Marks each compacted capsule with `compacted_into: <summary_id>` (they stay on disk for archeology) ## When to run - /close Step 0.5 PART E (v0.4.5) reports the capsule chain length when the threshold is hit - Manually before a session-heavy week to keep /open Step 2.5 fast - After narrative-reconstruction archeology when the chain has grown unwieldy ## Defaults - Threshold: 5 capsules - Summarize-count: 3 oldest Override via `--threshold N` and `--summarize-count N` flags. ## What it does NOT do - Does not auto-compact at /close. Hints, you decide. - Does not delete compacted capsules. Each gets `compacted_into:` marker. - Does not LLM-summarize. Concatenates structured fields (objective, open_threads still live, held decisions). - Does not walk forks. parent_capsule_id is strictly linear. ## Cross-links - [[concepts/Somatic v0.4.5 Chain Compaction]] — spec - [[concepts/context-capsule]] — base capsule schema
© wrg32786 · MIT · wrg32786/aigent-os