Codex plugin skills
Capsule bundles map-token-context as the control-plane skill for large or reasoning-heavy Codex work. It compiles finite branching decisions outside model generation, routes virtualized specialist skills on demand, and keeps model-visible input and output bounded across tools, files, history, images, subagents, search, and recall.
Use the Capsule action surface and its deterministic decision helpers to settle finite covers, assignments, paths, or other branch-heavy choices before asking the model to narrate them. The model still supplies judgment that is not encoded in the input.
A short English intent is matched against installed SKILL.md descriptions. The default route returns one domain-anchored match with a compact description and a real skill_file path; the selected skill is read only when it is relevant.
Terminal, file, project, web, memory, and subagent results can use bounded views with exact local recovery. Compression is a local context decision, not a promise about provider-side billing, hidden reasoning, or cache behavior.
The bundled source is skills/map-token-context/, with its contract in SKILL.md, the default Codex-facing prompt in agents/openai.yaml, and recovery details in references/capsule-contract.md. These are ordinary repository files: the router does not copy the entire skill catalog into every turn.
The Codex plugin manifest points at the bundled skill root and the single MCP configuration. Keep these paths relative to the plugin root when registering a local checkout.
// .codex-plugin/plugin.json
{
"name": "capsule",
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}
// .mcp.json
{"mcpServers":{"capsule":{"command":"node","args":["--no-warnings","./mcp/server.cjs"],"cwd":"."}}}Compare the exact files in the plugin manifest and MCP manifest. The skills pointer means a normal install discovers skills/map-token-context/SKILL.md; it does not mean every optional or personal skill is automatically activated.
Call the one capsule MCP tool with a public query that paraphrases the literal task. The query is required; keep it specific enough to identify a domain rather than repeating generic status or context-control language.
{"action":"skills","payload":{"operation":"route","query":"Audit an API authorization bypass"}}A successful response contains a short matches array. Each match can include the skill name, bounded description, score, and a real skill_file path. Read that selected file, not every candidate. The default is one result; pass a larger limit only when the task genuinely needs multiple independent specialists. The route never moves or edits the installed catalog.
If the MCP transport is unavailable, the bundled implementation has the same dispatch behavior through scripts/skill-router.cjs:
node scripts/skill-router.cjs route "Audit an API authorization bypass"When no installed specialist clears the relevance floor, Capsule returns matches: [] with a no-relevant-match reason. Continue on the normal Capsule route; do not guess a skill or treat abstention as an installation failure.
Phrase overlap alone cannot clear the floor, and adjacent phrases do not bridge removed stopwords. A generic word such as “status” or “continue” is not mailbox, architecture, presentation, PDF, or security intent.
Token, context, routing, compaction, and other generic Capsule control-plane questions cannot accidentally load an unrelated specialist. Ask for the specialist domain explicitly when you really need one.
Security-oriented specialists require explicit security intent. A normal product, mailbox, or documentation request that happens to contain “audit” should remain on the base route.
This abstention behavior is deliberate: a false positive injects irrelevant instructions and consumes context, while a no-match leaves the core task available. The router also returns at most the requested bounded metadata; it does not re-inject a large specialist description.
Use the same local plugin workflow as the Capsule installation guide. Node.js 18 or newer and a Codex build with local plugin/MCP support are required.
git clone https://github.com/hakiyaka/capsule.git
cd capsule
npm test
npm run verifynode -e "const p=require('./.codex-plugin/plugin.json'); if(p.skills!=='./skills/'||p.mcpServers!=='./.mcp.json') process.exit(1); console.log(p.skills,p.mcpServers)"node scripts/skill-router.cjs route "Compile a branch-heavy token task and route specialist skills"{"action":"doctor","payload":{}}. For documentation and public-link regressions, run npm run audit:public, npm run audit:docs, and npm run audit:seo.For a reproducible checkout, pin a release such as v1.0.7 and verify its SHA-256 sidecar before unpacking. The repository is clone/release based; it is not the unrelated public npm package named capsule.
| Boundary | What to expect |
|---|---|
| Catalog size | Routing is a compact selector, not a full specialist index. A match points to a file; reading and following that file still costs context. |
| Ambiguous intent | Low-confidence, generic, unsafe, or token-negative requests pass through or return no match. Make the query more domain-specific instead of raising limit blindly. |
| Provider visibility | Local characters, token estimates, hashes, and recovery IDs describe model-facing exposure. Capsule cannot see hidden provider reasoning, provider cache keys, subscription limits, latency, or billing counters. |
| Hook scope | Codex hooks can rewrite allowed tool input, replace eligible tool results, and add bounded context. They cannot remove the base system/developer/user prompt, make waits event-driven, or retract an answer after generation. |
| Recovery and privacy | Exact expansion requires a real capsule ID returned by an earlier call; IDs are never invented. Local state is bounded and content-addressed, but captured files and session logs can contain sensitive material—use the documented privacy controls and explicit full-read modes carefully. |
Read the README, security policy, and privacy policy for the complete contracts. Skill routing is a conservative convenience layer; it is not an authorization boundary or a substitute for reviewing the selected skill.