From 6d6f5be97e2a4287720acaf1194f191467396f2c Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 18 Jun 2026 22:14:45 +0200 Subject: [PATCH 01/22] feat(aidd-context): add research and apply actions to cook skill Extend 12-cook from author-only to a fuller loop: - 03-research: refine the target recipe via a checklist, fan out one agent per scouting angle, then present alternatives / coverage gaps / counter-intuitive wins plus a recommendation. Ephemeral, never writes. - 04-apply: execute an existing recipe against the project via an agent that tracks the steps as a todo list and confirms before mutating. - upsert: qualitative overlap guard (none/partial/high) that suggests updating an existing recipe instead of creating a duplicate. - recipe-template: steps become "#### N)" headings with what/why, actionable how-bullets, and a mandatory concrete example (command with output, snippet, or screenshot/video). New references/assets: research-playbook, refine-goal-checklist, research-checklist. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 7 +++- plugins/aidd-context/skills/12-cook/README.md | 14 ++++---- plugins/aidd-context/skills/12-cook/SKILL.md | 20 +++++++---- .../skills/12-cook/actions/02-upsert.md | 6 ++-- .../skills/12-cook/actions/03-research.md | 30 ++++++++++++++++ .../skills/12-cook/actions/04-apply.md | 23 ++++++++++++ .../skills/12-cook/assets/recipe-template.md | 35 ++++++++++++++++--- .../12-cook/assets/refine-goal-checklist.md | 12 +++++++ .../12-cook/assets/research-checklist.md | 9 +++++ .../12-cook/references/research-playbook.md | 28 +++++++++++++++ 10 files changed, 165 insertions(+), 19 deletions(-) create mode 100644 plugins/aidd-context/skills/12-cook/actions/03-research.md create mode 100644 plugins/aidd-context/skills/12-cook/actions/04-apply.md create mode 100644 plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md create mode 100644 plugins/aidd-context/skills/12-cook/assets/research-checklist.md create mode 100644 plugins/aidd-context/skills/12-cook/references/research-playbook.md diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 3ce4b47f..70007010 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -196,7 +196,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-list.md](skills/12-cook/actions/01-list.md) | - | | `actions` | [02-upsert.md](skills/12-cook/actions/02-upsert.md) | - | +| `actions` | [03-research.md](skills/12-cook/actions/03-research.md) | - | +| `actions` | [04-apply.md](skills/12-cook/actions/04-apply.md) | - | | `assets` | [recipe-template.md](skills/12-cook/assets/recipe-template.md) | - | +| `assets` | [refine-goal-checklist.md](skills/12-cook/assets/refine-goal-checklist.md) | - | +| `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.md) | - | | `-` | [README.md](skills/12-cook/README.md) | - | -| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes/ how-to sheets: list them as a table, or create and update one from the canonical template. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe".` | +| `references` | [research-playbook.md](skills/12-cook/references/research-playbook.md) | - | +| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes/ how-to sheets: list them as a table, create or update one from the canonical template, research modern alternatives for a recipe, or apply a recipe to the project. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe", "research a recipe", "modernize a recipe", "apply a recipe", "run a recipe".` | diff --git a/plugins/aidd-context/skills/12-cook/README.md b/plugins/aidd-context/skills/12-cook/README.md index d4d04135..11a903c6 100644 --- a/plugins/aidd-context/skills/12-cook/README.md +++ b/plugins/aidd-context/skills/12-cook/README.md @@ -2,11 +2,13 @@ # 12 - cook -Maintain the project's `recipes/` how-to sheets: list them, or create and update one from the canonical template. The recipes are the short runbooks at the root of whatever project the skill runs in. - -| # | Action | Purpose | -| --- | ------------------------------ | ---------------------------------------------- | -| 01 | [list](actions/01-list.md) | List every recipe as a table. | -| 02 | [upsert](actions/02-upsert.md) | Create or update one recipe from the template. | +Maintain the project's `recipes/` how-to sheets: list, create or update, research, or apply. The recipes are the short runbooks at the root of whatever project the skill runs in. + +| # | Action | Purpose | +| --- | ---------------------------------- | --------------------------------------------------------- | +| 01 | [list](actions/01-list.md) | List every recipe as a table. | +| 02 | [upsert](actions/02-upsert.md) | Create or update one recipe from the template. | +| 03 | [research](actions/03-research.md) | Survey alternatives, gaps, and counter-intuitive wins. | +| 04 | [apply](actions/04-apply.md) | Execute a recipe on the project as a confirmed todo list. | See [`SKILL.md`](SKILL.md) for the router and [`assets/recipe-template.md`](assets/recipe-template.md) for the recipe shape. diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index e0b61a88..d1d1b8b6 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/plugins/aidd-context/skills/12-cook/SKILL.md @@ -1,6 +1,6 @@ --- name: 12-cook -description: Manage the project's recipes/ how-to sheets: list them as a table, or create and update one from the canonical template. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe". +description: Manage the project's recipes/ how-to sheets: list them as a table, create or update one from the canonical template, research modern alternatives for a recipe, or apply a recipe to the project. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe", "research a recipe", "modernize a recipe", "apply a recipe", "run a recipe". --- # Cook @@ -9,13 +9,21 @@ Maintains the project's `recipes/` how-to sheets, the short runbooks that live a ## Actions -| # | Action | Role | Input | -| --- | -------- | --------------------------------------------- | --------------------- | -| 01 | `list` | List every recipe as a table | none | -| 02 | `upsert` | Create or update one recipe from the template | recipe topic + fields | +| # | Action | Role | Input | +| --- | ---------- | ----------------------------------------------------------- | --------------------- | +| 01 | `list` | List every recipe as a table | none | +| 02 | `upsert` | Create or update one recipe from the template | recipe topic + fields | +| 03 | `research` | Survey modern alternatives, gaps, and counter-intuitive wins | recipe or topic | +| 04 | `apply` | Execute a recipe on the project as a confirmed todo list | recipe | -Run `list` to survey recipes, `upsert` to author one. Run `list` first when the user wants to update a recipe but hasn't named which. +Run `list` to survey recipes, `research` to gather insights, `upsert` to author one, `apply` to run an existing one against the project. Always run `research` before authoring or substantially updating a recipe — never draft from memory alone. Run `list` first when the user names no recipe. + +## References + +- `references/research-playbook.md`: the scouting angles and per-candidate criteria `research` applies (freshness, community signal, tips). ## Assets - `assets/recipe-template.md`: the canonical recipe scaffold `upsert` renders from, and the shape `list` parses. Its header comment carries the field rules. +- `assets/refine-goal-checklist.md`: the checklist `research` fills with the user to define the target recipe. +- `assets/research-checklist.md`: the done-when gate `research` clears before drafting. diff --git a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md index 62e87015..64777f2d 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -9,9 +9,11 @@ The recipe topic. Ask for any missing field (level, time, prerequisites, steps, ## Process 1. Derive a kebab-case `` from the topic → `recipes/.md`. -2. If it exists, update in place; else scaffold from the template. -3. Fill every placeholder, then add or refresh the recipe's row in the `recipes/README.md` index. The index table is `| Recipe | Goal | Level |`: link the title to `.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. +2. If `recipes/.md` is new, run `list` and rate each near match in an overlap table `| Existing recipe | Shared scope | Overlap |`, where `Overlap` is none, partial, or high. On any `high`, recommend updating that recipe instead, and ask update-or-create before scaffolding. +3. If it exists, update in place; else scaffold from the template. +4. Fill every placeholder, then add or refresh the recipe's row in the `recipes/README.md` index. The index table is `| Recipe | Goal | Level |`: link the title to `.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. ## Test - `recipes/.md` exists and matches the template, every section present, no `<...>` placeholder left. +- A new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding. diff --git a/plugins/aidd-context/skills/12-cook/actions/03-research.md b/plugins/aidd-context/skills/12-cook/actions/03-research.md new file mode 100644 index 00000000..3f700028 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -0,0 +1,30 @@ +# 03 - Research alternatives + +Refine the target recipe with a checklist, then scout for the highest-value insights and propose them as sorted lists. + +## Input + +The recipe or topic to modernize. If a recipe, its `recipes/.md` holds the current approach and coverage. + +## Output + +Three parts, then a recommendation: + +1. An alternatives table `| Alternative | What it is | Pros | Cons | Source |`, sorted by value. +2. A coverage-gaps list: important sub-topics the recipe omits, each with why it matters. +3. A counter-intuitive wins list: surprising tips, each with the result it produces. + +Ephemeral: nothing is written under `recipes/`. + +## Process + +1. **Refine.** Fill `@assets/refine-goal-checklist.md` with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/.md` first when the recipe exists. Run `list` when it is unnamed. +2. **Fan out.** Spawn one agent per angle in `@references/research-playbook.md` via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources. +3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear `@assets/research-checklist.md`: gaps filled, unknowns surfaced, claims corroborated. +4. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, then state a recommendation and why. +5. **Hand off.** If the user picks insights to keep, route to `upsert` to fold them into the recipe. + +## Test + +- The output has an alternatives table with pros and cons, a coverage-gaps list, and a counter-intuitive wins list, plus an explicit recommendation, and nothing is written to disk. +- The research checklist clears (gaps filled, unknowns surfaced, claims confirmed) before any hand-off to `upsert`. diff --git a/plugins/aidd-context/skills/12-cook/actions/04-apply.md b/plugins/aidd-context/skills/12-cook/actions/04-apply.md new file mode 100644 index 00000000..45e00c4f --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -0,0 +1,23 @@ +# 04 - Apply recipe + +Execute an existing recipe against the current project by spawning an agent that works through its steps as a tracked todo list, confirming with the user. + +## Input + +The recipe to apply, named by slug or topic. + +## Output + +The recipe's `## Steps` carried out on the project, tracked as a todo list, ending with its `## Verify` checks run and reported. + +## Process + +1. **Locate.** Resolve the recipe to `recipes/.md` and read it. Run `list` first when the recipe is unnamed. +2. **Plan.** Turn each `## Steps` item into one todo entry. +3. **Confirm.** Show the user the plan and ask for confirmation before any change. +4. **Execute.** Spawn an agent via the `Task` tool to work the todo list in order. It marks each item done as it lands, and pauses for confirmation on any step that mutates the project. +5. **Verify.** Run the recipe's `## Verify` checks and report pass or fail. + +## Test + +- Applying a recipe produces a todo list mirroring its `## Steps`, asks for confirmation before executing, and runs the `## Verify` checks at the end. diff --git a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md index cdf37fd3..bf3f98e9 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -1,4 +1,4 @@ - + # @@ -16,9 +16,36 @@ ## Steps -1. 📋 **** — -2. 🔧 **** — -3. ✅ **** — +#### 1) + + + +- +- + +```bash +$ + +``` + +#### 2) + + + +- +- + +``` + +``` + +#### 3) + + + +- + +![]() ## Verify diff --git a/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md b/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md new file mode 100644 index 00000000..ba2e17f4 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md @@ -0,0 +1,12 @@ + + +# Refine the goal + +Fill this with the user before scouting. A vague goal returns vague insights. + +- [ ] **Goal** — one sentence naming the precise outcome the recipe delivers. +- [ ] **Audience and level** — who it is for, mapped to Beginner / Intermediate / Advanced. +- [ ] **Scope** — what is in and explicitly out, so the search stays bounded. +- [ ] **Actionable insights** — every item is a concrete action with an observable result, never theory alone. +- [ ] **Grouping** — how insights are categorized: by level, by sub-topic, or by use-case. +- [ ] **Counter-intuitive wins** — leave room for surprising tips that outperform the obvious default. diff --git a/plugins/aidd-context/skills/12-cook/assets/research-checklist.md b/plugins/aidd-context/skills/12-cook/assets/research-checklist.md new file mode 100644 index 00000000..89a99785 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/assets/research-checklist.md @@ -0,0 +1,9 @@ + + +# Research checklist + +A pass is done only when all three clear. Never draft from memory alone. + +- [ ] **Fill gaps** — cover what the starting list missed. +- [ ] **Surface unknowns** — search past what you already know; assume blind spots exist. +- [ ] **Confirm claims** — corroborate every assertion you would write, or mark it unverified. diff --git a/plugins/aidd-context/skills/12-cook/references/research-playbook.md b/plugins/aidd-context/skills/12-cook/references/research-playbook.md new file mode 100644 index 00000000..24c16242 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -0,0 +1,28 @@ + + +# Research playbook + +Guidance for `03-research`: the angles to scout and the criteria each candidate must clear. Define the target with `assets/refine-goal-checklist.md` first, and clear `assets/research-checklist.md` before drafting. + +## Angles to cover + +Spawn one agent per angle so coverage stays wide: + +- **Alternatives** — competing tools, libraries, or methods that could replace the current approach. +- **New methods** — techniques that emerged since the recipe was written. +- **Coverage gaps** — important sub-topics the recipe omits entirely. A masterclass that forgets a core feature has a gap. +- **Counter-intuitive wins** — surprising practices that beat the obvious default, with evidence of the result. +- **Deprecations** — what the recipe still recommends that is now discouraged or dead. + +## Criteria for every candidate + +- **Freshness** — prefer sources from the last 12 months. Record release or publish dates. Flag anything stale. +- **Community signal** — weigh what practitioners actually say: GitHub activity, open issues, Reddit, Hacker News, discussions. Separate real adoption from hype. +- **Tips and gotchas** — capture practical advice, common pitfalls, and migration notes worth keeping. +- **Credibility** — corroborate across sources. Trust official docs over a single blog post. + +## Reporting + +- Return each candidate with its angle, level, value, and a one-line source. +- Push for the most insights possible, then drop anything that neither beats nor extends the recipe. +- `03-research` sorts them into three buckets: alternatives (with pros/cons), coverage gaps, and counter-intuitive wins. From e30e0b8060704f4f3d0ea56c23782f9fe1b2c1eb Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 07:45:45 +0200 Subject: [PATCH 02/22] feat(aidd-context): verify each research candidate before presenting Add a Verify step to cook's 03-research: after curation, spawn one agent per surviving candidate to confirm it exists, capture its official link, and record its latest state. Drop anything that cannot be confirmed against an official source. This makes the checklist's "Confirm claims" real and guards the recipe against hallucinated tools or methods. Co-Authored-By: Claude Opus 4.8 --- .../skills/12-cook/actions/03-research.md | 15 ++++++++------- .../12-cook/references/research-playbook.md | 15 ++++++++++++--- 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/actions/03-research.md b/plugins/aidd-context/skills/12-cook/actions/03-research.md index 3f700028..e5b67568 100644 --- a/plugins/aidd-context/skills/12-cook/actions/03-research.md +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -1,6 +1,6 @@ # 03 - Research alternatives -Refine the target recipe with a checklist, then scout for the highest-value insights and propose them as sorted lists. +Refine the target recipe with a checklist, scout for the highest-value insights, verify each one exists, and propose them as sorted lists. ## Input @@ -10,21 +10,22 @@ The recipe or topic to modernize. If a recipe, its `recipes/.md` holds the Three parts, then a recommendation: -1. An alternatives table `| Alternative | What it is | Pros | Cons | Source |`, sorted by value. +1. An alternatives table `| Alternative | What it is | Pros | Cons | Official link |`, sorted by value. 2. A coverage-gaps list: important sub-topics the recipe omits, each with why it matters. 3. A counter-intuitive wins list: surprising tips, each with the result it produces. -Ephemeral: nothing is written under `recipes/`. +Every presented item is confirmed to exist, with its latest state and official link. Ephemeral: nothing is written under `recipes/`. ## Process 1. **Refine.** Fill `@assets/refine-goal-checklist.md` with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/.md` first when the recipe exists. Run `list` when it is unnamed. 2. **Fan out.** Spawn one agent per angle in `@references/research-playbook.md` via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources. -3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear `@assets/research-checklist.md`: gaps filled, unknowns surfaced, claims corroborated. -4. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, then state a recommendation and why. -5. **Hand off.** If the user picks insights to keep, route to `upsert` to fold them into the recipe. +3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. +4. **Verify.** Spawn one agent per surviving candidate via the `Task` tool to confirm it exists, capture its official link, and record its latest state (version or date). Drop any candidate that cannot be confirmed against an official source. This clears the checklist's `Confirm claims`. +5. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, each item carrying its official link, then state a recommendation and why. Clear `@assets/research-checklist.md`: gaps filled, unknowns surfaced, claims confirmed. +6. **Hand off.** If the user picks insights to keep, route to `upsert` to fold them into the recipe. ## Test - The output has an alternatives table with pros and cons, a coverage-gaps list, and a counter-intuitive wins list, plus an explicit recommendation, and nothing is written to disk. -- The research checklist clears (gaps filled, unknowns surfaced, claims confirmed) before any hand-off to `upsert`. +- Every presented item carries an official link and was confirmed to exist; unverifiable candidates are dropped. diff --git a/plugins/aidd-context/skills/12-cook/references/research-playbook.md b/plugins/aidd-context/skills/12-cook/references/research-playbook.md index 24c16242..062d45f1 100644 --- a/plugins/aidd-context/skills/12-cook/references/research-playbook.md +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -1,8 +1,8 @@ - + # Research playbook -Guidance for `03-research`: the angles to scout and the criteria each candidate must clear. Define the target with `assets/refine-goal-checklist.md` first, and clear `assets/research-checklist.md` before drafting. +Guidance for `03-research`: the angles to scout, the criteria each candidate must clear, and the verification each must pass. Define the target with `assets/refine-goal-checklist.md` first, and clear `assets/research-checklist.md` before drafting. ## Angles to cover @@ -21,8 +21,17 @@ Spawn one agent per angle so coverage stays wide: - **Tips and gotchas** — capture practical advice, common pitfalls, and migration notes worth keeping. - **Credibility** — corroborate across sources. Trust official docs over a single blog post. +## Verify each candidate + +After curating, confirm every surviving candidate before presenting it. Spawn one agent per candidate to check: + +- **Exists** — confirm it is real and current, not invented or abandoned. +- **Official link** — capture the canonical source: official docs, repository, or release page. +- **Latest state** — record the current version or release date. +- Drop any candidate that cannot be confirmed against an official source. + ## Reporting -- Return each candidate with its angle, level, value, and a one-line source. +- Return each candidate with its angle, level, value, and a source; verified ones carry an official link. - Push for the most insights possible, then drop anything that neither beats nor extends the recipe. - `03-research` sorts them into three buckets: alternatives (with pros/cons), coverage gaps, and counter-intuitive wins. From df602d7e62d0b3a6b1122be3b5614ec28c104688 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 07:48:45 +0200 Subject: [PATCH 03/22] docs(framework): add token optimization recipe Add recipes/token-optimization.md: a ranked list of token-saving tips for AI coding assistants (measure first, trim CLAUDE.md, caveman, RTK/SNIP, CLI over MCP, progressive disclosure, compact, model routing, cap thinking), each tip in the new template format with a concrete example and an official link verified to exist. Register it in the recipes index. Co-Authored-By: Claude Opus 4.8 --- recipes/README.md | 3 +- recipes/token-optimization.md | 132 ++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 recipes/token-optimization.md diff --git a/recipes/README.md b/recipes/README.md index fbdb5c80..26099c7c 100644 --- a/recipes/README.md +++ b/recipes/README.md @@ -5,8 +5,9 @@ Task-oriented how-to sheets for the AIDD Framework. Each recipe is a self-contai | Recipe | Goal | Level | | --- | --- | --- | | [MCP installations](mcp-installation.md) | Decide when to use an MCP server vs a CLI, and wire up the recommended ones | Beginner | +| [Token optimization for AI IDEs](token-optimization.md) | Cut token usage and cost in AI coding assistants without losing output quality | Intermediate | -> More coming — token optimisation, custom plugins, and others. +> More coming — custom plugins, and others. ## Contributing a recipe diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md new file mode 100644 index 00000000..b5483264 --- /dev/null +++ b/recipes/token-optimization.md @@ -0,0 +1,132 @@ +# Token optimization for AI IDEs + +> **Goal:** Cut token usage and cost in AI coding assistants without losing output quality. + +| | | +| ----------------- | ---------------------------------------------------------------------------- | +| **Level** | Intermediate | +| **Time** | ~15 min | +| **Prerequisites** | An AI coding assistant (Claude Code, GitHub Copilot, Codex, Cursor, …); a terminal | + +## Why + +Tokens are the bill. Every turn re-sends your context window — instructions, file reads, command output, the model's own narration — and you pay for all of it, every time. Most of it is waste: filler prose, noisy logs, stale context, oversized instruction files. The tips below attack each source. Stack them and large savings are realistic; every percentage here is **as reported by the tool**, not an independent benchmark. + +> **Measure before you optimise.** You cannot cut what you do not see. + +## Best tips + +Ranked by impact-to-effort. Start at the top. + +#### 1) Measure first + +You cannot improve what you do not track, and the bill is rarely where you think — cache reads usually dominate, not generation. + +- In Claude Code: `/context` shows what fills the window, `/cost` shows the session cost and plan usage, `/insights` reports your session patterns and friction points. +- For a per-prompt breakdown across every session, use [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code). + +```bash +$ uvx --from prompt-analytics-for-claude-code prompt-analytics summary +# per-prompt tokens & cost from your local logs — cache reads dominate the total +``` + +#### 2) Trim your instruction file + +`CLAUDE.md` (or `.github/copilot-instructions.md`) ships in **every** turn, so each wasted line is taxed on every message. + +- Keep it short; add explicit conciseness rules. +- Drop-in ruleset: [`drona23/claude-token-efficient`](https://github.com/drona23/claude-token-efficient) (savings vary by model; measure your own). + +```md +# CLAUDE.md +- Terse answers. No preamble, no "Let me…", no closing summary. +- Keep verbatim: code, quoted errors, security warnings. Cut the rest. +``` + +#### 3) Make the agent talk less + +Output is repetition — "Let me explain…", "Here's a summary…". You pay to generate every word. + +- The [`caveman`](https://github.com/JuliusBrussee/caveman) skill forces short, filler-free replies (reported ~65% output-token cut, code and data intact). Auto-detects 30+ agents. + +```text +before: "Great question! Let me walk you through each of the steps involved…" +after: "3 steps:" +``` + +#### 4) Filter noisy command output + +Test runs, installs, and build logs flood the context with lines the model never needs. + +- A CLI proxy strips them before they land: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). Both report 60–90% on noisy output, zero overhead when no filter matches. + +```bash +$ rtk proxy npm test +# full build log in → only failures + final summary kept +``` + +#### 5) Prefer CLI over MCP + +An MCP server loads its full tool schema into **every** turn; a CLI call costs a few tokens only when you use it. + +- Reach for the CLI when one exists; keep MCP for what truly needs it. See [`mcp-installation.md`](mcp-installation.md). + +```bash +$ gh pr list # a few tokens per call +# vs a GitHub MCP server: its whole schema rides along every turn +``` + +#### 6) Use progressive disclosure + +Don't paste big procedural docs into context. Load knowledge only when the task needs it. + +- Install an AIDD framework so skills, rules, and runbooks load on demand instead of riding along every turn. + +```text +skill description matched → its steps load +no match → 0 tokens spent +``` + +#### 7) Compact deliberately + +Auto-compaction fires late and may drop what you wanted kept. + +- Run `/compact` around 60–70% context, passing focus instructions for what to retain. + +```bash +$ /compact keep the repro steps and the failing test; drop the file dumps +``` + +#### 8) Route by difficulty + +The top model on a routine task is wasted spend. + +- Send research and routine work to a cheaper/faster model or a fresh subagent context; reserve the strongest model for the hard reasoning. + +```text +research / boilerplate → small model or subagent +architecture / tricky bug → top model +``` + +#### 9) Cap extended thinking + +Extended reasoning can silently add thousands of tokens per turn on tasks that don't need it. + +- Control it with `MAX_THINKING_TOKENS` in your settings — set `0` to turn extended thinking off when you don't need it. See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). + +```bash +# settings.json (env) +"MAX_THINKING_TOKENS": "0" # disable extended thinking for routine work +``` + +## Verify + +- Run `/cost` (or `prompt-analytics summary`) before and after a typical task — the token count should drop measurably. +- `/context` shows your instruction file and tool schemas taking a smaller share of the window. +- A noisy command (test suite, `npm install`) routed through RTK or SNIP returns far fewer lines than the raw run. + +## Related + +- [`mcp-installation.md`](mcp-installation.md) — why CLI beats MCP for context efficiency +- [Anthropic — Claude Code costs](https://code.claude.com/docs/en/costs) · [settings](https://code.claude.com/docs/en/settings) +- Tools: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) · [`caveman`](https://github.com/JuliusBrussee/caveman) · [`RTK`](https://github.com/rtk-ai/rtk) · [`SNIP`](https://github.com/edouard-claude/snip) · [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) From 7f8c358f8fd19156e7270ecbbac785e1a1e061fa Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 08:12:14 +0200 Subject: [PATCH 04/22] refactor(aidd-context): extract recipe contract and tighten cook template Move the recipe authoring rules out of the template's HTML comment into references/recipe-contract.md, cited by SKILL.md and upsert. The template keeps only the scaffold. - Steps heading carries the goal ("## Steps to ") and each step opens with an emoji. - Step how-bullets follow where-it-is -> install-from-URL -> how-to-use, benefit-first and filler-free. - "## Why" is short, keyword-led, and bold. - SKILL.md description is shorter and high-level, triggered on "recipe" / "cook" / "/cook". Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 3 ++- plugins/aidd-context/skills/12-cook/SKILL.md | 5 ++-- .../skills/12-cook/actions/02-upsert.md | 6 ++--- .../skills/12-cook/actions/04-apply.md | 6 ++--- .../skills/12-cook/assets/recipe-template.md | 23 +++++++++--------- .../12-cook/references/recipe-contract.md | 24 +++++++++++++++++++ 6 files changed, 46 insertions(+), 21 deletions(-) create mode 100644 plugins/aidd-context/skills/12-cook/references/recipe-contract.md diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 70007010..f1ae4d74 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -202,6 +202,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [refine-goal-checklist.md](skills/12-cook/assets/refine-goal-checklist.md) | - | | `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.md) | - | | `-` | [README.md](skills/12-cook/README.md) | - | +| `references` | [recipe-contract.md](skills/12-cook/references/recipe-contract.md) | - | | `references` | [research-playbook.md](skills/12-cook/references/research-playbook.md) | - | -| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes/ how-to sheets: list them as a table, create or update one from the canonical template, research modern alternatives for a recipe, or apply a recipe to the project. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe", "research a recipe", "modernize a recipe", "apply a recipe", "run a recipe".` | +| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes/ how-to sheets: list, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe".` | diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index d1d1b8b6..2f793c7a 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/plugins/aidd-context/skills/12-cook/SKILL.md @@ -1,6 +1,6 @@ --- name: 12-cook -description: Manage the project's recipes/ how-to sheets: list them as a table, create or update one from the canonical template, research modern alternatives for a recipe, or apply a recipe to the project. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe", "research a recipe", "modernize a recipe", "apply a recipe", "run a recipe". +description: Manage the project's recipes/ how-to sheets: list, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe". --- # Cook @@ -20,10 +20,11 @@ Run `list` to survey recipes, `research` to gather insights, `upsert` to author ## References +- `references/recipe-contract.md`: the rules every recipe file follows; `upsert` writes to it. - `references/research-playbook.md`: the scouting angles and per-candidate criteria `research` applies (freshness, community signal, tips). ## Assets -- `assets/recipe-template.md`: the canonical recipe scaffold `upsert` renders from, and the shape `list` parses. Its header comment carries the field rules. +- `assets/recipe-template.md`: the canonical recipe scaffold `upsert` renders from, and the shape `list` parses. - `assets/refine-goal-checklist.md`: the checklist `research` fills with the user to define the target recipe. - `assets/research-checklist.md`: the done-when gate `research` clears before drafting. diff --git a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md index 64777f2d..ca2af855 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -1,6 +1,6 @@ # 02 - Upsert recipe -Create or update one recipe at `recipes/.md`, scaffolded from `@assets/recipe-template.md`. +Create or update one recipe at `recipes/.md`, scaffolded from `@assets/recipe-template.md` and following the rules in `@references/recipe-contract.md`. ## Input @@ -10,10 +10,10 @@ The recipe topic. Ask for any missing field (level, time, prerequisites, steps, 1. Derive a kebab-case `` from the topic → `recipes/.md`. 2. If `recipes/.md` is new, run `list` and rate each near match in an overlap table `| Existing recipe | Shared scope | Overlap |`, where `Overlap` is none, partial, or high. On any `high`, recommend updating that recipe instead, and ask update-or-create before scaffolding. -3. If it exists, update in place; else scaffold from the template. +3. If it exists, update in place; else scaffold from the template. Apply `@references/recipe-contract.md` to every section. 4. Fill every placeholder, then add or refresh the recipe's row in the `recipes/README.md` index. The index table is `| Recipe | Goal | Level |`: link the title to `.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. ## Test -- `recipes/.md` exists and matches the template, every section present, no `<...>` placeholder left. +- `recipes/.md` exists and follows `@references/recipe-contract.md`: every section present, each step a `#### N)` emoji heading with an example, no `<...>` placeholder left. - A new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding. diff --git a/plugins/aidd-context/skills/12-cook/actions/04-apply.md b/plugins/aidd-context/skills/12-cook/actions/04-apply.md index 45e00c4f..b337eea5 100644 --- a/plugins/aidd-context/skills/12-cook/actions/04-apply.md +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -8,16 +8,16 @@ The recipe to apply, named by slug or topic. ## Output -The recipe's `## Steps` carried out on the project, tracked as a todo list, ending with its `## Verify` checks run and reported. +The recipe's steps carried out on the project, tracked as a todo list, ending with its `## Verify` checks run and reported. ## Process 1. **Locate.** Resolve the recipe to `recipes/.md` and read it. Run `list` first when the recipe is unnamed. -2. **Plan.** Turn each `## Steps` item into one todo entry. +2. **Plan.** Turn each step under the recipe's steps heading (`## Steps to …`) into one todo entry. 3. **Confirm.** Show the user the plan and ask for confirmation before any change. 4. **Execute.** Spawn an agent via the `Task` tool to work the todo list in order. It marks each item done as it lands, and pauses for confirmation on any step that mutates the project. 5. **Verify.** Run the recipe's `## Verify` checks and report pass or fail. ## Test -- Applying a recipe produces a todo list mirroring its `## Steps`, asks for confirmation before executing, and runs the `## Verify` checks at the end. +- Applying a recipe produces a todo list mirroring the recipe's steps, asks for confirmation before executing, and runs the `## Verify` checks at the end. diff --git a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md index bf3f98e9..86bfe0d2 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -1,5 +1,3 @@ - - # > **Goal:** @@ -12,25 +10,26 @@ ## Why - + -## Steps +## Steps to -#### 1) +#### 1) - + -- -- +- +- +- ```bash $ ``` -#### 2) +#### 2) - + - - @@ -39,9 +38,9 @@ $ ``` -#### 3) +#### 3) - + - diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md new file mode 100644 index 00000000..e9f13049 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -0,0 +1,24 @@ + + +# Recipe contract + +Rules for every `recipes/.md` the skill writes. + +## File + +- Path: `recipes/.md`. +- `Level` is one of Beginner, Intermediate, Advanced. `Time` is prefixed with `~`. + +## Writing + +- One idea per sentence. Prefer removing over adding. +- No filler line under a heading (no "Ranked by impact", "Start at the top", and the like). +- `## Why`: short and benefit-first. Lead with the keywords a reader would search, **bold** the key terms. A few sentences, no more. + +## Steps + +- The steps section heading is named after the goal: `## Steps to `, never a bare `## Steps`. +- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. +- How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. +- Every step carries one concrete example: a command with its useful output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. +- Link to a reference when applicable. From e5c5240641063109ad9e2aa79666c9d3569846f1 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 13:37:13 +0200 Subject: [PATCH 05/22] fix(aidd-context): repair 12-cook SKILL.md YAML frontmatter The description contained an unquoted "sheets: list" colon, which YAML parses as a mapping value and rejects ("mapping values are not allowed here"), breaking the skill's frontmatter. Replace the colon with a dash. The bug pre-dated this branch (same colon on main). Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 2 +- plugins/aidd-context/skills/12-cook/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index f1ae4d74..7b2ed315 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -204,5 +204,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `-` | [README.md](skills/12-cook/README.md) | - | | `references` | [recipe-contract.md](skills/12-cook/references/recipe-contract.md) | - | | `references` | [research-playbook.md](skills/12-cook/references/research-playbook.md) | - | -| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes/ how-to sheets: list, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe".` | +| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes/ how-to sheets — list, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe".` | diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index 2f793c7a..3f678f0e 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/plugins/aidd-context/skills/12-cook/SKILL.md @@ -1,6 +1,6 @@ --- name: 12-cook -description: Manage the project's recipes/ how-to sheets: list, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe". +description: Manage the project's recipes/ how-to sheets — list, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe". --- # Cook From aa1e65f88d9e78de81ac368cc7c481bd1c855a95 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 14:13:43 +0200 Subject: [PATCH 06/22] refactor(aidd-context): refine cook recipe structure and apply R13 to cook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review feedback on the cook skill, plus the new includes convention: - Recipe template drops the Time field, groups steps under three level subheadings (Beginner / Intermediate / Expert), and aligns the Level enum to Expert. - upsert now runs `research` (03) first for any new or substantial recipe and drafts only from its verified results, never from memory — the "always research" rule was being skipped as a routing note. - Apply R13 (explicit, scoped includes): the action-specific research aids move out of SKILL.md and are cited from 03-research in fenced blocks; refine-goal-checklist is renamed research-goal-checklist; SKILL.md lists only the global recipe-template and recipe-contract. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 2 +- plugins/aidd-context/skills/12-cook/SKILL.md | 3 --- .../skills/12-cook/actions/02-upsert.md | 21 ++++++++++----- .../skills/12-cook/actions/03-research.md | 26 +++++++++++++++---- .../skills/12-cook/assets/recipe-template.md | 9 +++++-- ...hecklist.md => research-goal-checklist.md} | 6 ++--- .../12-cook/references/recipe-contract.md | 5 ++-- 7 files changed, 49 insertions(+), 23 deletions(-) rename plugins/aidd-context/skills/12-cook/assets/{refine-goal-checklist.md => research-goal-checklist.md} (70%) diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 7b2ed315..bc539548 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -199,8 +199,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-research.md](skills/12-cook/actions/03-research.md) | - | | `actions` | [04-apply.md](skills/12-cook/actions/04-apply.md) | - | | `assets` | [recipe-template.md](skills/12-cook/assets/recipe-template.md) | - | -| `assets` | [refine-goal-checklist.md](skills/12-cook/assets/refine-goal-checklist.md) | - | | `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.md) | - | +| `assets` | [research-goal-checklist.md](skills/12-cook/assets/research-goal-checklist.md) | - | | `-` | [README.md](skills/12-cook/README.md) | - | | `references` | [recipe-contract.md](skills/12-cook/references/recipe-contract.md) | - | | `references` | [research-playbook.md](skills/12-cook/references/research-playbook.md) | - | diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index 3f678f0e..1031e621 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/plugins/aidd-context/skills/12-cook/SKILL.md @@ -21,10 +21,7 @@ Run `list` to survey recipes, `research` to gather insights, `upsert` to author ## References - `references/recipe-contract.md`: the rules every recipe file follows; `upsert` writes to it. -- `references/research-playbook.md`: the scouting angles and per-candidate criteria `research` applies (freshness, community signal, tips). ## Assets - `assets/recipe-template.md`: the canonical recipe scaffold `upsert` renders from, and the shape `list` parses. -- `assets/refine-goal-checklist.md`: the checklist `research` fills with the user to define the target recipe. -- `assets/research-checklist.md`: the done-when gate `research` clears before drafting. diff --git a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md index ca2af855..f0362296 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -1,19 +1,26 @@ # 02 - Upsert recipe -Create or update one recipe at `recipes/.md`, scaffolded from `@assets/recipe-template.md` and following the rules in `@references/recipe-contract.md`. +Create or update one recipe at `recipes/.md`, scaffolded from the recipe template and following the recipe contract: + +```md +@assets/recipe-template.md +@references/recipe-contract.md +``` ## Input -The recipe topic. Ask for any missing field (level, time, prerequisites, steps, verify, related) before writing. +The recipe topic. Ask for any missing field (level, prerequisites, steps, verify, related) before writing. ## Process -1. Derive a kebab-case `` from the topic → `recipes/.md`. -2. If `recipes/.md` is new, run `list` and rate each near match in an overlap table `| Existing recipe | Shared scope | Overlap |`, where `Overlap` is none, partial, or high. On any `high`, recommend updating that recipe instead, and ask update-or-create before scaffolding. -3. If it exists, update in place; else scaffold from the template. Apply `@references/recipe-contract.md` to every section. -4. Fill every placeholder, then add or refresh the recipe's row in the `recipes/README.md` index. The index table is `| Recipe | Goal | Level |`: link the title to `.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. +1. **Research first.** For a new recipe or any substantial update, run `research` (03) on the topic and draft only from its verified results — never from memory. +2. Derive a kebab-case `` from the topic → `recipes/.md`. +3. If `recipes/.md` is new, run `list` and rate each near match in an overlap table `| Existing recipe | Shared scope | Overlap |`, where `Overlap` is none, partial, or high. On any `high`, recommend updating that recipe instead, and ask update-or-create before scaffolding. +4. If it exists, update in place; else scaffold from the template. Apply the contract to every section. +5. Fill every placeholder, then add or refresh the recipe's row in the `recipes/README.md` index. The index table is `| Recipe | Goal | Level |`: link the title to `.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. ## Test -- `recipes/.md` exists and follows `@references/recipe-contract.md`: every section present, each step a `#### N)` emoji heading with an example, no `<...>` placeholder left. +- A new or substantially-updated recipe is drafted from `research` results, not from memory. +- `recipes/.md` exists and follows the recipe contract: every section present, steps grouped under the three level subheadings, each step a `#### N)` emoji heading with an example, no `<...>` placeholder left. - A new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding. diff --git a/plugins/aidd-context/skills/12-cook/actions/03-research.md b/plugins/aidd-context/skills/12-cook/actions/03-research.md index e5b67568..e6c8695b 100644 --- a/plugins/aidd-context/skills/12-cook/actions/03-research.md +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -18,14 +18,30 @@ Every presented item is confirmed to exist, with its latest state and official l ## Process -1. **Refine.** Fill `@assets/refine-goal-checklist.md` with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/.md` first when the recipe exists. Run `list` when it is unnamed. -2. **Fan out.** Spawn one agent per angle in `@references/research-playbook.md` via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources. -3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. -4. **Verify.** Spawn one agent per surviving candidate via the `Task` tool to confirm it exists, capture its official link, and record its latest state (version or date). Drop any candidate that cannot be confirmed against an official source. This clears the checklist's `Confirm claims`. -5. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, each item carrying its official link, then state a recommendation and why. Clear `@assets/research-checklist.md`: gaps filled, unknowns surfaced, claims confirmed. +1. **Refine.** Fill the goal checklist with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/.md` first when the recipe exists. Run `list` when it is unnamed. + +```md +@assets/research-goal-checklist.md +``` + +2. **Fan out.** Spawn one agent per angle in the playbook via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources. + +```md +@references/research-playbook.md +``` + +3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear the research checklist: gaps filled, unknowns surfaced, claims corroborated. + +```md +@assets/research-checklist.md +``` + +4. **Verify.** Spawn one agent per surviving candidate via the `Task` tool to confirm it exists, capture its official link, and record its latest state (version or date). Drop any candidate that cannot be confirmed against an official source. +5. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, each item carrying its official link, then state a recommendation and why. 6. **Hand off.** If the user picks insights to keep, route to `upsert` to fold them into the recipe. ## Test - The output has an alternatives table with pros and cons, a coverage-gaps list, and a counter-intuitive wins list, plus an explicit recommendation, and nothing is written to disk. - Every presented item carries an official link and was confirmed to exist; unverifiable candidates are dropped. +- The research checklist clears (gaps filled, unknowns surfaced, claims confirmed) before any hand-off to `upsert`. diff --git a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md index 86bfe0d2..d4c30f4e 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -4,8 +4,7 @@ | | | | ----------------- | ---------------------------------------- | -| **Level** | | -| **Time** | ~ min | +| **Level** | | | **Prerequisites** | | ## Why @@ -14,6 +13,8 @@ ## Steps to +### 🟢 Beginner + #### 1) @@ -27,6 +28,8 @@ $ ``` +### 🟡 Intermediate + #### 2) @@ -38,6 +41,8 @@ $ ``` +### 🔴 Expert + #### 3) diff --git a/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md b/plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md similarity index 70% rename from plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md rename to plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md index ba2e17f4..3ad21d32 100644 --- a/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md +++ b/plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md @@ -1,12 +1,12 @@ - + # Refine the goal Fill this with the user before scouting. A vague goal returns vague insights. - [ ] **Goal** — one sentence naming the precise outcome the recipe delivers. -- [ ] **Audience and level** — who it is for, mapped to Beginner / Intermediate / Advanced. +- [ ] **Audience and level** — who it is for, mapped to Beginner / Intermediate / Expert. - [ ] **Scope** — what is in and explicitly out, so the search stays bounded. - [ ] **Actionable insights** — every item is a concrete action with an observable result, never theory alone. -- [ ] **Grouping** — how insights are categorized: by level, by sub-topic, or by use-case. +- [ ] **Grouping** — insights are organized under the three recipe levels (Beginner / Intermediate / Expert). - [ ] **Counter-intuitive wins** — leave room for surprising tips that outperform the obvious default. diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index e9f13049..981a2ef1 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -7,7 +7,7 @@ Rules for every `recipes/.md` the skill writes. ## File - Path: `recipes/.md`. -- `Level` is one of Beginner, Intermediate, Advanced. `Time` is prefixed with `~`. +- `Level` is one of Beginner, Intermediate, Expert. ## Writing @@ -18,7 +18,8 @@ Rules for every `recipes/.md` the skill writes. ## Steps - The steps section heading is named after the goal: `## Steps to `, never a bare `## Steps`. -- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. +- Group the steps under three level subheadings, in order: `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert`. Put each step under the level it fits; drop a level that has no step. +- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously across levels. - How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. - Every step carries one concrete example: a command with its useful output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. - Link to a reference when applicable. From 96dee3dca4d7545bd45f75cd618138fd145b76cc Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 14:27:55 +0200 Subject: [PATCH 07/22] refactor(aidd-context): make recipe level subheadings optional Level grouping was effectively mandatory. Make the contract state it is optional: group steps under Beginner/Intermediate/Expert only when the recipe spans difficulty levels and grouping helps; a short or single-level recipe lists its steps directly. Relax the upsert Test accordingly. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/12-cook/actions/02-upsert.md | 2 +- .../aidd-context/skills/12-cook/references/recipe-contract.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md index f0362296..c0906840 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -22,5 +22,5 @@ The recipe topic. Ask for any missing field (level, prerequisites, steps, verify ## Test - A new or substantially-updated recipe is drafted from `research` results, not from memory. -- `recipes/.md` exists and follows the recipe contract: every section present, steps grouped under the three level subheadings, each step a `#### N)` emoji heading with an example, no `<...>` placeholder left. +- `recipes/.md` exists and follows the recipe contract: every section present, each step a `#### N)` emoji heading with an example, with level subheadings used only when they help, no `<...>` placeholder left. - A new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding. diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index 981a2ef1..ac6600c2 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -18,8 +18,8 @@ Rules for every `recipes/.md` the skill writes. ## Steps - The steps section heading is named after the goal: `## Steps to `, never a bare `## Steps`. -- Group the steps under three level subheadings, in order: `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert`. Put each step under the level it fits; drop a level that has no step. -- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously across levels. +- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. - How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. - Every step carries one concrete example: a command with its useful output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. +- Level subheadings are optional. Group steps under `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert` only when the recipe spans difficulty levels and grouping helps the reader; a short or single-level recipe lists its steps directly. Include only the levels that have a step. - Link to a reference when applicable. From 4e7c5df72466e3b46c30cedab7b0af84968d9fcc Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 12:53:16 +0200 Subject: [PATCH 08/22] docs(framework): conform token-optimization recipe to recipe contract Align the recipe with references/recipe-contract.md: drop the Time row (no longer in the template), name the section "Steps to " instead of a bare Steps, remove the "ranked by impact" filler line, and give each step how-bullets plus a concrete example. Co-Authored-By: Claude Opus 4.8 (1M context) --- recipes/token-optimization.md | 109 ++++++++++++++++++---------------- 1 file changed, 58 insertions(+), 51 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index b5483264..2e773c71 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -2,40 +2,38 @@ > **Goal:** Cut token usage and cost in AI coding assistants without losing output quality. -| | | -| ----------------- | ---------------------------------------------------------------------------- | -| **Level** | Intermediate | -| **Time** | ~15 min | +| | | +| ----------------- | ---------------------------------------------------------------------------------- | +| **Level** | Intermediate | | **Prerequisites** | An AI coding assistant (Claude Code, GitHub Copilot, Codex, Cursor, …); a terminal | ## Why -Tokens are the bill. Every turn re-sends your context window — instructions, file reads, command output, the model's own narration — and you pay for all of it, every time. Most of it is waste: filler prose, noisy logs, stale context, oversized instruction files. The tips below attack each source. Stack them and large savings are realistic; every percentage here is **as reported by the tool**, not an independent benchmark. +**Token usage** is the bill. Every turn re-sends your whole **context window** — instructions, file reads, command output, narration — and you pay for it again. Most of it is waste: filler prose, noisy logs, stale context, bloated instruction files. Reach for this recipe when **cost** climbs faster than output. -> **Measure before you optimise.** You cannot cut what you do not see. +## Steps to cut token usage -## Best tips +### 🟢 Beginner -Ranked by impact-to-effort. Start at the top. +#### 1) 📊 Measure first -#### 1) Measure first +You cannot cut what you cannot see, so find what fills the window before changing anything. -You cannot improve what you do not track, and the bill is rarely where you think — cache reads usually dominate, not generation. - -- In Claude Code: `/context` shows what fills the window, `/cost` shows the session cost and plan usage, `/insights` reports your session patterns and friction points. -- For a per-prompt breakdown across every session, use [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code). +- Built-in: run `/context`, `/cost`, and `/insights` in Claude Code. +- Cross-session detail: install [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and run it with `uvx`. ```bash $ uvx --from prompt-analytics-for-claude-code prompt-analytics summary -# per-prompt tokens & cost from your local logs — cache reads dominate the total +# per-prompt tokens & cost from local logs — cache reads usually dominate ``` -#### 2) Trim your instruction file +#### 2) ✂️ Trim your instruction file -`CLAUDE.md` (or `.github/copilot-instructions.md`) ships in **every** turn, so each wasted line is taxed on every message. +Your instruction file ships every turn, so each cut line saves on every message. -- Keep it short; add explicit conciseness rules. -- Drop-in ruleset: [`drona23/claude-token-efficient`](https://github.com/drona23/claude-token-efficient) (savings vary by model; measure your own). +- It lives at `CLAUDE.md` (or `.github/copilot-instructions.md`). +- Cut it to essentials and add explicit conciseness rules. +- Reuse the [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) ruleset. ```md # CLAUDE.md @@ -43,76 +41,85 @@ $ uvx --from prompt-analytics-for-claude-code prompt-analytics summary - Keep verbatim: code, quoted errors, security warnings. Cut the rest. ``` -#### 3) Make the agent talk less +#### 3) 🗜️ Compact deliberately + +Compacting on your terms keeps what matters instead of letting auto-compaction guess. + +- Watch context use and act around 60–70%. +- Run `/compact` with focus instructions naming what to keep. + +```bash +$ /compact keep the repro steps and the failing test; drop the file dumps +``` + +### 🟡 Intermediate + +#### 4) 🗣️ Make the agent talk less -Output is repetition — "Let me explain…", "Here's a summary…". You pay to generate every word. +Output is repetition you pay to generate, so cap the chatter. -- The [`caveman`](https://github.com/JuliusBrussee/caveman) skill forces short, filler-free replies (reported ~65% output-token cut, code and data intact). Auto-detects 30+ agents. +- Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill (auto-detects 30+ agents). +- It forces short, filler-free replies (reported ~65% output cut, code intact). ```text -before: "Great question! Let me walk you through each of the steps involved…" +before: "Great question! Let me walk you through each step involved…" after: "3 steps:" ``` -#### 4) Filter noisy command output +#### 5) 🧹 Filter noisy command output -Test runs, installs, and build logs flood the context with lines the model never needs. +Test, install, and build logs flood context with lines the model never needs. -- A CLI proxy strips them before they land: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). Both report 60–90% on noisy output, zero overhead when no filter matches. +- Install a CLI proxy: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). +- Run noisy commands through it; it keeps only the signal (reported 60–90%). ```bash $ rtk proxy npm test # full build log in → only failures + final summary kept ``` -#### 5) Prefer CLI over MCP +#### 6) 🔌 Prefer CLI over MCP -An MCP server loads its full tool schema into **every** turn; a CLI call costs a few tokens only when you use it. +An MCP server loads its full schema every turn, while a CLI costs tokens only when called. -- Reach for the CLI when one exists; keep MCP for what truly needs it. See [`mcp-installation.md`](mcp-installation.md). +- Use the CLI when one exists (`gh`, `acli`, …); keep MCP for what has none. +- See [`mcp-installation.md`](mcp-installation.md). ```bash -$ gh pr list # a few tokens per call -# vs a GitHub MCP server: its whole schema rides along every turn +$ gh pr list # a few tokens per call, vs a GitHub MCP schema riding along every turn ``` -#### 6) Use progressive disclosure +### 🔴 Expert -Don't paste big procedural docs into context. Load knowledge only when the task needs it. +#### 7) 📚 Use progressive disclosure -- Install an AIDD framework so skills, rules, and runbooks load on demand instead of riding along every turn. +Load knowledge only when the task needs it, instead of riding along every turn. + +- Install an AIDD framework so skills, rules, and runbooks load on demand. ```text skill description matched → its steps load no match → 0 tokens spent ``` -#### 7) Compact deliberately - -Auto-compaction fires late and may drop what you wanted kept. - -- Run `/compact` around 60–70% context, passing focus instructions for what to retain. - -```bash -$ /compact keep the repro steps and the failing test; drop the file dumps -``` - -#### 8) Route by difficulty +#### 8) 🎯 Route by difficulty -The top model on a routine task is wasted spend. +The top model on routine work is wasted spend. -- Send research and routine work to a cheaper/faster model or a fresh subagent context; reserve the strongest model for the hard reasoning. +- Send research and boilerplate to a cheaper model or a fresh subagent. +- Reserve the strongest model for hard reasoning. ```text research / boilerplate → small model or subagent architecture / tricky bug → top model ``` -#### 9) Cap extended thinking +#### 9) ✅ Cap extended thinking -Extended reasoning can silently add thousands of tokens per turn on tasks that don't need it. +Extended reasoning can silently add thousands of tokens on tasks that don't need it. -- Control it with `MAX_THINKING_TOKENS` in your settings — set `0` to turn extended thinking off when you don't need it. See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). +- Set `MAX_THINKING_TOKENS` to `0` for routine work. +- See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). ```bash # settings.json (env) @@ -121,9 +128,9 @@ Extended reasoning can silently add thousands of tokens per turn on tasks that d ## Verify -- Run `/cost` (or `prompt-analytics summary`) before and after a typical task — the token count should drop measurably. +- Run `/cost` before and after a typical task — the token count drops measurably. - `/context` shows your instruction file and tool schemas taking a smaller share of the window. -- A noisy command (test suite, `npm install`) routed through RTK or SNIP returns far fewer lines than the raw run. +- A noisy command routed through RTK or SNIP returns far fewer lines than the raw run. ## Related From 4348c46b40b90e6e9a859548c836a8f98a1bf16e Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 17:46:08 +0200 Subject: [PATCH 09/22] docs(framework): split measure steps per tool and drop metadata table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply review of the token-optimization recipe: - Goal becomes a plain sentence (no blockquote). - Drop the Level/Prerequisites table; level now lives in the subheadings. - Split the bundled "Measure first" step into one step per tool (/context, /cost, /insights, an analytics tool) — one subheading per action. - Each measure step says how to use and read the command, and carries an example output; the analytics step uses a real prompt-analytics run (volumes rounded, cost omitted) showing cache reads dominate. Co-Authored-By: Claude Opus 4.8 --- recipes/token-optimization.md | 96 ++++++++++++++++++++++++++--------- 1 file changed, 73 insertions(+), 23 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 2e773c71..fa77823d 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -1,33 +1,83 @@ # Token optimization for AI IDEs -> **Goal:** Cut token usage and cost in AI coding assistants without losing output quality. +**Goal:** Cut token usage and cost in AI coding assistants without losing output quality. -| | | -| ----------------- | ---------------------------------------------------------------------------------- | -| **Level** | Intermediate | -| **Prerequisites** | An AI coding assistant (Claude Code, GitHub Copilot, Codex, Cursor, …); a terminal | +## Why optimize your tokens -## Why +**Token usage** is the bill — every turn re-sends your whole **context window** and you pay for it again. -**Token usage** is the bill. Every turn re-sends your whole **context window** — instructions, file reads, command output, narration — and you pay for it again. Most of it is waste: filler prose, noisy logs, stale context, bloated instruction files. Reach for this recipe when **cost** climbs faster than output. +Most of it is **waste**: filler prose, noisy logs, stale context, bloated instruction files. + +Reach for this recipe when **cost** climbs faster than your output. ## Steps to cut token usage ### 🟢 Beginner -#### 1) 📊 Measure first +#### 1) 🔎 See what fills the window — `/context` -You cannot cut what you cannot see, so find what fills the window before changing anything. +`/context` paints your context as a grid, so you cut the biggest consumers instead of guessing. -- Built-in: run `/context`, `/cost`, and `/insights` in Claude Code. -- Cross-session detail: install [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and run it with `uvx`. +- Run `/context` in Claude Code. +- Read the grid and find the heavy blocks: tool schemas, instruction files, long file reads. +- Attack the biggest block first. -```bash +```text +$ /context + MCP tool schemas ████████████ 28% ← biggest, cut first + file reads ████████ 19% + CLAUDE.md ████ 9% + system + tools ███████████ … +(illustrative — paste your real /context here) +``` + +#### 2) 💸 Read the bill — `/cost` + +`/cost` tells you what a session actually costs and where the spend goes. + +- Run `/cost` (alias `/usage`). +- Read the breakdown by skill, subagent, and MCP server. +- Re-run it after a change to confirm the spend really dropped. + +```text +$ /cost + Session: $0.42 · 1.2M tokens + By: subagents 38% · MCP 21% · main 41% +(illustrative — paste your real /cost here) +``` + +#### 3) 🔍 Find your bad habits — `/insights` + +`/insights` analyses how you prompt — which is probably sub-optimal — so you fix the pattern, not one prompt. + +- What you repeat every session → move it into the knowledge base (`CLAUDE.md`, rules). +- Counter-intuitive habits you never noticed → surfaced so you can drop them. + +```text +$ /insights + • You restate the test command in ~60% of sessions → put it in CLAUDE.md + • Long "summary" turns inflate output → ask for terse replies +(illustrative — paste your real /insights here) +``` + +#### 4) 📈 Track per-prompt with an analytics tool + +Built-ins show one session; an analytics tool reads all your local logs and reveals where the bill truly sits. + +- Several exist: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and [`ccusage`](https://www.npmjs.com/package/ccusage). +- Run one against your local history — no setup, it parses `~/.claude`. +- The lesson it surfaces: **cache reads dwarf input + output**, so caching, not generation, is most of the bill. + +```text $ uvx --from prompt-analytics-for-claude-code prompt-analytics summary -# per-prompt tokens & cost from local logs — cache reads usually dominate + Input tokens ~8M + Output tokens ~22M + Cache read tokens ~4.5B ← dominates the total + Source: live parse of ~/.claude/projects +(real run, token volumes rounded; cost figures omitted) ``` -#### 2) ✂️ Trim your instruction file +#### 5) ✂️ Trim your instruction file Your instruction file ships every turn, so each cut line saves on every message. @@ -41,20 +91,20 @@ Your instruction file ships every turn, so each cut line saves on every message. - Keep verbatim: code, quoted errors, security warnings. Cut the rest. ``` -#### 3) 🗜️ Compact deliberately +#### 6) 🗜️ Compact deliberately Compacting on your terms keeps what matters instead of letting auto-compaction guess. - Watch context use and act around 60–70%. - Run `/compact` with focus instructions naming what to keep. -```bash +```text $ /compact keep the repro steps and the failing test; drop the file dumps ``` ### 🟡 Intermediate -#### 4) 🗣️ Make the agent talk less +#### 7) 🗣️ Make the agent talk less Output is repetition you pay to generate, so cap the chatter. @@ -66,7 +116,7 @@ before: "Great question! Let me walk you through each step involved…" after: "3 steps:" ``` -#### 5) 🧹 Filter noisy command output +#### 8) 🧹 Filter noisy command output Test, install, and build logs flood context with lines the model never needs. @@ -78,7 +128,7 @@ $ rtk proxy npm test # full build log in → only failures + final summary kept ``` -#### 6) 🔌 Prefer CLI over MCP +#### 9) 🔌 Prefer CLI over MCP An MCP server loads its full schema every turn, while a CLI costs tokens only when called. @@ -91,7 +141,7 @@ $ gh pr list # a few tokens per call, vs a GitHub MCP schema riding along ever ### 🔴 Expert -#### 7) 📚 Use progressive disclosure +#### 10) 📚 Use progressive disclosure Load knowledge only when the task needs it, instead of riding along every turn. @@ -102,7 +152,7 @@ skill description matched → its steps load no match → 0 tokens spent ``` -#### 8) 🎯 Route by difficulty +#### 11) 🎯 Route by difficulty The top model on routine work is wasted spend. @@ -114,7 +164,7 @@ research / boilerplate → small model or subagent architecture / tricky bug → top model ``` -#### 9) ✅ Cap extended thinking +#### 12) ✅ Cap extended thinking Extended reasoning can silently add thousands of tokens on tasks that don't need it. @@ -136,4 +186,4 @@ Extended reasoning can silently add thousands of tokens on tasks that don't need - [`mcp-installation.md`](mcp-installation.md) — why CLI beats MCP for context efficiency - [Anthropic — Claude Code costs](https://code.claude.com/docs/en/costs) · [settings](https://code.claude.com/docs/en/settings) -- Tools: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) · [`caveman`](https://github.com/JuliusBrussee/caveman) · [`RTK`](https://github.com/rtk-ai/rtk) · [`SNIP`](https://github.com/edouard-claude/snip) · [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) +- Tools: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) · [`ccusage`](https://www.npmjs.com/package/ccusage) · [`caveman`](https://github.com/JuliusBrussee/caveman) · [`RTK`](https://github.com/rtk-ai/rtk) · [`SNIP`](https://github.com/edouard-claude/snip) · [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) From ab670351190a0cec1dc0aa8c16d5ed870e92b4d7 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 17:51:06 +0200 Subject: [PATCH 10/22] docs(framework): drop the Goal label from token-optimization The recipe opens with a plain description sentence, no "Goal:" label. Co-Authored-By: Claude Opus 4.8 --- recipes/token-optimization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index fa77823d..0a988360 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -1,6 +1,6 @@ # Token optimization for AI IDEs -**Goal:** Cut token usage and cost in AI coding assistants without losing output quality. +Cut token usage and cost in AI coding assistants without losing output quality. ## Why optimize your tokens From 237335fe7fd9fc266a3666bd406398c1b7418411 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 17:51:06 +0200 Subject: [PATCH 11/22] refactor(aidd-context): recipe header = description sentence, no table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rules extracted from the token-optimization recipe review: - A recipe opens with the H1 title then one plain description sentence — no "Goal:" label, no blockquote, no metadata table. list/upsert parse that sentence; the index becomes `| Recipe | Description |` (Level was dropped, level now lives only in the optional subheadings). - One step = one action; never bundle several tools or commands under a single heading. - Every step's example shows real command output (from docs or by running it); the research playbook now requires capturing a real example and marking interactive output for the human to paste. - `## Why` is one idea per line. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/12-cook/actions/01-list.md | 10 +++++----- .../aidd-context/skills/12-cook/actions/02-upsert.md | 6 +++--- .../skills/12-cook/assets/recipe-template.md | 9 ++------- .../skills/12-cook/references/recipe-contract.md | 7 ++++--- .../skills/12-cook/references/research-playbook.md | 3 ++- 5 files changed, 16 insertions(+), 19 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/actions/01-list.md b/plugins/aidd-context/skills/12-cook/actions/01-list.md index 543e18e9..561fd1e2 100644 --- a/plugins/aidd-context/skills/12-cook/actions/01-list.md +++ b/plugins/aidd-context/skills/12-cook/actions/01-list.md @@ -5,9 +5,9 @@ List every recipe under `recipes/` at the project root as a table, excluding `RE ## Output ```md -| Recipe | Goal | Level | -| --- | --- | --- | -| [](recipes/<file>) | <goal> | <level> | +| Recipe | Description | +| --- | --- | +| [<title>](recipes/<file>) | <description> | ``` One row per `recipes/*.md`, sorted by file name. If `recipes/` is absent or empty: `No recipes yet.` @@ -15,10 +15,10 @@ One row per `recipes/*.md`, sorted by file name. If `recipes/` is absent or empt ## Process 1. Read each `recipes/*.md` except `README.md`. -2. Pull the H1 title, the `> **Goal:**` line, and the **Level** row. +2. Pull the H1 title and the one-sentence description right below it. 3. Render the table above. ## Test -- One row per recipe file, each with title, goal, and level. +- One row per recipe file, each with title and description. - Absent/empty `recipes/` → `No recipes yet`, no error. diff --git a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md index c0906840..22816be8 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -9,7 +9,7 @@ Create or update one recipe at `recipes/<slug>.md`, scaffolded from the recipe t ## Input -The recipe topic. Ask for any missing field (level, prerequisites, steps, verify, related) before writing. +The recipe topic. Ask for any missing field (description, steps, verify, related) before writing. ## Process @@ -17,10 +17,10 @@ The recipe topic. Ask for any missing field (level, prerequisites, steps, verify 2. Derive a kebab-case `<slug>` from the topic → `recipes/<slug>.md`. 3. If `recipes/<slug>.md` is new, run `list` and rate each near match in an overlap table `| Existing recipe | Shared scope | Overlap |`, where `Overlap` is none, partial, or high. On any `high`, recommend updating that recipe instead, and ask update-or-create before scaffolding. 4. If it exists, update in place; else scaffold from the template. Apply the contract to every section. -5. Fill every placeholder, then add or refresh the recipe's row in the `recipes/README.md` index. The index table is `| Recipe | Goal | Level |`: link the title to `<slug>.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. +5. Fill every placeholder, then add or refresh the recipe's row in the `recipes/README.md` index. The index table is `| Recipe | Description |`: link the title to `<slug>.md` (relative) and copy the one-sentence description. Same columns `list` emits. ## Test - A new or substantially-updated recipe is drafted from `research` results, not from memory. -- `recipes/<slug>.md` exists and follows the recipe contract: every section present, each step a `#### N)` emoji heading with an example, with level subheadings used only when they help, no `<...>` placeholder left. +- `recipes/<slug>.md` exists and follows the recipe contract: opens with a one-sentence description (no Goal label, no table), each step a `#### N)` emoji heading with a real example, no `<...>` placeholder left. - A new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding. diff --git a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md index d4c30f4e..a60cb11d 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -1,15 +1,10 @@ # <Recipe title> -> **Goal:** <one line stating the outcome the reader achieves> - -| | | -| ----------------- | ---------------------------------------- | -| **Level** | <Beginner \| Intermediate \| Expert> | -| **Prerequisites** | <what the reader needs first, or "None"> | +<One sentence describing what this recipe gets the reader.> ## Why -<Short and benefit-first. Lead with the keywords a reader would search, **bold** the key terms. A few sentences, no filler.> +<Short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms.> ## Steps to <the outcome the reader achieves> diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index ac6600c2..fb44bc84 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -7,19 +7,20 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. ## File - Path: `recipes/<kebab-slug>.md`. -- `Level` is one of Beginner, Intermediate, Expert. +- The recipe opens with the H1 title, then one plain sentence of description — no "Goal:" label, no blockquote, no metadata table. ## Writing - One idea per sentence. Prefer removing over adding. - No filler line under a heading (no "Ranked by impact", "Start at the top", and the like). -- `## Why`: short and benefit-first. Lead with the keywords a reader would search, **bold** the key terms. A few sentences, no more. +- `## Why`: short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms. ## Steps - The steps section heading is named after the goal: `## Steps to <outcome>`, never a bare `## Steps`. +- One step = one action: never bundle several tools or commands under one heading; split them. - Each step is a `#### N) <emoji> Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. - How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. -- Every step carries one concrete example: a command with its useful output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. +- Every step carries one concrete example: a command with its real output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. - Level subheadings are optional. Group steps under `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert` only when the recipe spans difficulty levels and grouping helps the reader; a short or single-level recipe lists its steps directly. Include only the levels that have a step. - Link to a reference when applicable. diff --git a/plugins/aidd-context/skills/12-cook/references/research-playbook.md b/plugins/aidd-context/skills/12-cook/references/research-playbook.md index 062d45f1..aad44ee3 100644 --- a/plugins/aidd-context/skills/12-cook/references/research-playbook.md +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -2,7 +2,7 @@ # Research playbook -Guidance for `03-research`: the angles to scout, the criteria each candidate must clear, and the verification each must pass. Define the target with `assets/refine-goal-checklist.md` first, and clear `assets/research-checklist.md` before drafting. +Guidance for `03-research`: the angles to scout, the criteria each candidate must clear, and the verification each must pass. Define the target with `assets/research-goal-checklist.md` first, and clear `assets/research-checklist.md` before drafting. ## Angles to cover @@ -28,6 +28,7 @@ After curating, confirm every surviving candidate before presenting it. Spawn on - **Exists** — confirm it is real and current, not invented or abandoned. - **Official link** — capture the canonical source: official docs, repository, or release page. - **Latest state** — record the current version or release date. +- **Real example** — capture a usable example: copy a real output from the official docs, or run the command and capture what it prints. For an interactive command that cannot be scripted, mark the output for the human to paste. Never fabricate output. - Drop any candidate that cannot be confirmed against an official source. ## Reporting From d687be80743c65568227fd3ae786f5e8f9d1b2e2 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:06:02 +0200 Subject: [PATCH 12/22] docs(framework): use the real prompt-analytics dashboard image Replace the fabricated text output with the tool's official dashboard screenshot (cost by token type makes "cache reads dominate" visible). The slash-command placeholders now ask for a screenshot of the real output. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 0a988360..a725501b 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -28,7 +28,7 @@ $ /context file reads ████████ 19% CLAUDE.md ████ 9% system + tools ███████████ … -(illustrative — paste your real /context here) +(illustrative — replace with a screenshot of your real /context) ``` #### 2) 💸 Read the bill — `/cost` @@ -43,7 +43,7 @@ $ /context $ /cost Session: $0.42 · 1.2M tokens By: subagents 38% · MCP 21% · main 41% -(illustrative — paste your real /cost here) +(illustrative — replace with a screenshot of your real /cost) ``` #### 3) 🔍 Find your bad habits — `/insights` @@ -57,7 +57,7 @@ $ /cost $ /insights • You restate the test command in ~60% of sessions → put it in CLAUDE.md • Long "summary" turns inflate output → ask for terse replies -(illustrative — paste your real /insights here) +(illustrative — replace with a screenshot of your real /insights) ``` #### 4) 📈 Track per-prompt with an analytics tool @@ -65,17 +65,10 @@ $ /insights Built-ins show one session; an analytics tool reads all your local logs and reveals where the bill truly sits. - Several exist: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and [`ccusage`](https://www.npmjs.com/package/ccusage). -- Run one against your local history — no setup, it parses `~/.claude`. +- Run it — `uvx --from prompt-analytics-for-claude-code prompt-analytics summary` — no setup, it parses `~/.claude`. - The lesson it surfaces: **cache reads dwarf input + output**, so caching, not generation, is most of the bill. -```text -$ uvx --from prompt-analytics-for-claude-code prompt-analytics summary - Input tokens ~8M - Output tokens ~22M - Cache read tokens ~4.5B ← dominates the total - Source: live parse of ~/.claude/projects -(real run, token volumes rounded; cost figures omitted) -``` +![prompt-analytics dashboard — cost by token type shows cache reads dominate the bill](https://raw.githubusercontent.com/romainfjgaspard/prompt-analytics-for-claude-code/main/docs/screenshots/dashboard-home.png) #### 5) ✂️ Trim your instruction file From b0c2dbe091597e2087929f3c63b6b7542b8f7d33 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:06:02 +0200 Subject: [PATCH 13/22] refactor(aidd-context): prefer images over text examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A real screenshot or GIF is unfakeable, faithful, and credible, where a text example can be approximated (the failure we hit). Make the contract and the research playbook prefer an image that matches the action — e.g. a tool's official screenshot — falling back to real text output only when no image exists. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- .../aidd-context/skills/12-cook/references/recipe-contract.md | 2 +- .../aidd-context/skills/12-cook/references/research-playbook.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index fb44bc84..988c8833 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -21,6 +21,6 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. - One step = one action: never bundle several tools or commands under one heading; split them. - Each step is a `#### N) <emoji> Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. - How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. -- Every step carries one concrete example: a command with its real output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. +- Every step carries one concrete example. Prefer an image — a screenshot or short video/GIF that matches the action — over text whenever one exists; for a tool, use its official screenshot. Otherwise: a command with its real output (show what it prints, not just the command), or a config or snippet. - Level subheadings are optional. Group steps under `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert` only when the recipe spans difficulty levels and grouping helps the reader; a short or single-level recipe lists its steps directly. Include only the levels that have a step. - Link to a reference when applicable. diff --git a/plugins/aidd-context/skills/12-cook/references/research-playbook.md b/plugins/aidd-context/skills/12-cook/references/research-playbook.md index aad44ee3..40db46c7 100644 --- a/plugins/aidd-context/skills/12-cook/references/research-playbook.md +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -28,7 +28,7 @@ After curating, confirm every surviving candidate before presenting it. Spawn on - **Exists** — confirm it is real and current, not invented or abandoned. - **Official link** — capture the canonical source: official docs, repository, or release page. - **Latest state** — record the current version or release date. -- **Real example** — capture a usable example: copy a real output from the official docs, or run the command and capture what it prints. For an interactive command that cannot be scripted, mark the output for the human to paste. Never fabricate output. +- **Real example** — prefer an image: grab the official screenshot or GIF that matches the action. Else a real output: copy it from the docs, or run the command and capture what it prints. For interactive output that cannot be scripted, mark it for the human to paste (ideally a screenshot). Never fabricate. - Drop any candidate that cannot be confirmed against an official source. ## Reporting From 7a3dee2c13b5c35c028d9102903c184453a95663 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:17:27 +0200 Subject: [PATCH 14/22] docs(framework): show real tool usage in token-optimization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - caveman: show its real `/caveman` invocation (and modes), not just a before/after. - RTK: a Mermaid diagram of the proxy flow + the real `rtk <command>` syntax (was a wrong `rtk proxy …`) and the README's own 200->10 token saving. - CLI vs MCP: a comparison table instead of prose. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index a725501b..0e5c753d 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -102,9 +102,11 @@ $ /compact keep the repro steps and the failing test; drop the file dumps Output is repetition you pay to generate, so cap the chatter. - Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill (auto-detects 30+ agents). +- Invoke it like any skill: `/caveman` (or `/caveman ultra` for the hardest cut); stop with "normal mode". - It forces short, filler-free replies (reported ~65% output cut, code intact). ```text +/caveman before: "Great question! Let me walk you through each step involved…" after: "3 steps:" ``` @@ -114,23 +116,29 @@ after: "3 steps:" Test, install, and build logs flood context with lines the model never needs. - Install a CLI proxy: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). -- Run noisy commands through it; it keeps only the signal (reported 60–90%). - -```bash -$ rtk proxy npm test -# full build log in → only failures + final summary kept +- Prefix your command with it — `rtk git status`, `rtk cargo test` — it runs the command and returns only the signal. + +```mermaid +flowchart LR + A[your command] --> R[RTK proxy] + R --> C[real command runs] + C --> R + R -->|filter · group · truncate · dedupe| M[compact output to model] ``` +Real saving: `git push` (15 lines, ~200 tokens) -> `rtk git push` (1 line, ~10 tokens). + #### 9) 🔌 Prefer CLI over MCP -An MCP server loads its full schema every turn, while a CLI costs tokens only when called. +An MCP server's schema rides along every turn; a CLI costs tokens only when you call it. -- Use the CLI when one exists (`gh`, `acli`, …); keep MCP for what has none. -- See [`mcp-installation.md`](mcp-installation.md). +| | CLI (`gh`, `acli`, …) | MCP server | +| --- | --- | --- | +| Token cost | a few, only when called | full tool schema, every turn | +| Context footprint | zero when idle | always present | +| Use when | a CLI exists | no CLI, or you need typed/live tool calls | -```bash -$ gh pr list # a few tokens per call, vs a GitHub MCP schema riding along every turn -``` +See [`mcp-installation.md`](mcp-installation.md). ### 🔴 Expert From 5dca0c26bfadc7d8b07d8c8f30336bd6aa53178a Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:17:28 +0200 Subject: [PATCH 15/22] refactor(aidd-context): add tool-example rules to recipe contract From the token-optimization review: - Show how to invoke a tool (its real command or slash invocation). - Reuse the canonical example from the tool's own site or README, never an invented one. - A "prefer X over Y" step uses a comparison table, not prose. - A structural or flow concept (proxy, pipeline, architecture) gets a small Mermaid diagram. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- .../skills/12-cook/references/recipe-contract.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index 988c8833..68c40371 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -20,7 +20,10 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. - The steps section heading is named after the goal: `## Steps to <outcome>`, never a bare `## Steps`. - One step = one action: never bundle several tools or commands under one heading; split them. - Each step is a `#### N) <emoji> Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. -- How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. +- How-bullets are straight to the point and ordered for action. For a tool: where it is, install it from its URL, then how to invoke it (its real command or slash invocation, e.g. `/caveman`). - Every step carries one concrete example. Prefer an image — a screenshot or short video/GIF that matches the action — over text whenever one exists; for a tool, use its official screenshot. Otherwise: a command with its real output (show what it prints, not just the command), or a config or snippet. +- Reuse the canonical example from the tool's own site or README, never an invented one. +- A step that prefers one option over another uses a comparison table, not prose. +- For a structural or flow concept (a proxy, a pipeline, an architecture), add a small Mermaid diagram. - Level subheadings are optional. Group steps under `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert` only when the recipe spans difficulty levels and grouping helps the reader; a short or single-level recipe lists its steps directly. Include only the levels that have a step. - Link to a reference when applicable. From 26c34a687ee2fb7b87f3654086c9cd1c6ca01e9e Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:20:56 +0200 Subject: [PATCH 16/22] docs(framework): use caveman's real before/after example Replace the invented caveman before/after with the verbatim example from its README (rule F: reuse the tool's own canonical example). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 0e5c753d..64ebe569 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -107,8 +107,10 @@ Output is repetition you pay to generate, so cap the chatter. ```text /caveman -before: "Great question! Let me walk you through each step involved…" -after: "3 steps:" + +before: The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object. + +after: New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`. ``` #### 8) 🧹 Filter noisy command output From c56464a30eca84fbc77ed8b850d2e3a814e69720 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:28:21 +0200 Subject: [PATCH 17/22] docs(framework): numbered actions, valid-JSON config, tighter sections - Actions are numbered lists; descriptions are prose (no description-bullets). - settings.json shown as valid JSON, not a bash fragment. - RTK Mermaid uses concrete values (cargo test ~25k -> ~2.5k tokens). - CLI vs MCP notes MCP tool/context selection (cheaper, still slower). - Step 10 reworded plainly ("load knowledge on demand"). - Drop the weak Verify and the redundant Related; add a short conclusion. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 100 ++++++++++++++++------------------ 1 file changed, 46 insertions(+), 54 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 64ebe569..753fc50c 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -18,16 +18,15 @@ Reach for this recipe when **cost** climbs faster than your output. `/context` paints your context as a grid, so you cut the biggest consumers instead of guessing. -- Run `/context` in Claude Code. -- Read the grid and find the heavy blocks: tool schemas, instruction files, long file reads. -- Attack the biggest block first. +1. Run `/context` in Claude Code. +2. Find the heavy blocks: tool schemas, instruction files, long file reads. +3. Attack the biggest block first. ```text $ /context MCP tool schemas ████████████ 28% ← biggest, cut first file reads ████████ 19% CLAUDE.md ████ 9% - system + tools ███████████ … (illustrative — replace with a screenshot of your real /context) ``` @@ -35,9 +34,9 @@ $ /context `/cost` tells you what a session actually costs and where the spend goes. -- Run `/cost` (alias `/usage`). -- Read the breakdown by skill, subagent, and MCP server. -- Re-run it after a change to confirm the spend really dropped. +1. Run `/cost` (alias `/usage`). +2. Read the breakdown by skill, subagent, and MCP server. +3. Re-run it after a change to confirm the spend really dropped. ```text $ /cost @@ -48,10 +47,10 @@ $ /cost #### 3) 🔍 Find your bad habits — `/insights` -`/insights` analyses how you prompt — which is probably sub-optimal — so you fix the pattern, not one prompt. +`/insights` analyses how you prompt — probably sub-optimal — so you fix the pattern, not one prompt. What you repeat every session belongs in the knowledge base, and the counter-intuitive habits you never noticed get surfaced so you can drop them. -- What you repeat every session → move it into the knowledge base (`CLAUDE.md`, rules). -- Counter-intuitive habits you never noticed → surfaced so you can drop them. +1. Run `/insights`. +2. Move what you repeat into `CLAUDE.md` or a rule, and drop the habits it flags. ```text $ /insights @@ -62,11 +61,10 @@ $ /insights #### 4) 📈 Track per-prompt with an analytics tool -Built-ins show one session; an analytics tool reads all your local logs and reveals where the bill truly sits. +Built-ins show one session; an analytics tool reads all your local logs and reveals where the bill truly sits. The lesson it surfaces: **cache reads dwarf input + output**, so caching, not generation, is most of the bill. -- Several exist: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and [`ccusage`](https://www.npmjs.com/package/ccusage). -- Run it — `uvx --from prompt-analytics-for-claude-code prompt-analytics summary` — no setup, it parses `~/.claude`. -- The lesson it surfaces: **cache reads dwarf input + output**, so caching, not generation, is most of the bill. +1. Pick one: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) or [`ccusage`](https://www.npmjs.com/package/ccusage). +2. Run it — `uvx --from prompt-analytics-for-claude-code prompt-analytics summary` — no setup, it parses `~/.claude`. ![prompt-analytics dashboard — cost by token type shows cache reads dominate the bill](https://raw.githubusercontent.com/romainfjgaspard/prompt-analytics-for-claude-code/main/docs/screenshots/dashboard-home.png) @@ -74,9 +72,9 @@ Built-ins show one session; an analytics tool reads all your local logs and reve Your instruction file ships every turn, so each cut line saves on every message. -- It lives at `CLAUDE.md` (or `.github/copilot-instructions.md`). -- Cut it to essentials and add explicit conciseness rules. -- Reuse the [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) ruleset. +1. Open `CLAUDE.md` (or `.github/copilot-instructions.md`). +2. Cut it to essentials and add explicit conciseness rules. +3. Reuse the [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) ruleset. ```md # CLAUDE.md @@ -88,8 +86,8 @@ Your instruction file ships every turn, so each cut line saves on every message. Compacting on your terms keeps what matters instead of letting auto-compaction guess. -- Watch context use and act around 60–70%. -- Run `/compact` with focus instructions naming what to keep. +1. Watch context use and act around 60–70%. +2. Run `/compact` with focus instructions naming what to keep. ```text $ /compact keep the repro steps and the failing test; drop the file dumps @@ -99,11 +97,10 @@ $ /compact keep the repro steps and the failing test; drop the file dumps #### 7) 🗣️ Make the agent talk less -Output is repetition you pay to generate, so cap the chatter. +Output is repetition you pay to generate, so cap the chatter. caveman forces short, filler-free replies (reported ~65% output cut, code intact) and auto-detects 30+ agents. -- Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill (auto-detects 30+ agents). -- Invoke it like any skill: `/caveman` (or `/caveman ultra` for the hardest cut); stop with "normal mode". -- It forces short, filler-free replies (reported ~65% output cut, code intact). +1. Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill. +2. Invoke it like any skill: `/caveman` (or `/caveman ultra` for the hardest cut); stop with "normal mode". ```text /caveman @@ -117,50 +114,50 @@ after: New object ref each render. Inline object prop = new ref = re-render. Wr Test, install, and build logs flood context with lines the model never needs. -- Install a CLI proxy: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). -- Prefix your command with it — `rtk git status`, `rtk cargo test` — it runs the command and returns only the signal. +1. Install a CLI proxy: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). +2. Prefix your command with it: `rtk cargo test`. ```mermaid flowchart LR - A[your command] --> R[RTK proxy] - R --> C[real command runs] - C --> R - R -->|filter · group · truncate · dedupe| M[compact output to model] + A["rtk cargo test"] --> R[RTK proxy] + R --> C["cargo test runs"] + C -->|"~25,000 tokens"| R + R -->|"filter · group · dedupe"| M["~2,500 tokens to model"] ``` Real saving: `git push` (15 lines, ~200 tokens) -> `rtk git push` (1 line, ~10 tokens). #### 9) 🔌 Prefer CLI over MCP -An MCP server's schema rides along every turn; a CLI costs tokens only when you call it. +An MCP server's schema rides along every turn; a CLI costs tokens only when you call it. Newer MCP tooling adds tool/context selection that loads only the tools you pick — cheaper than before — but a CLI is still leaner and faster. | | CLI (`gh`, `acli`, …) | MCP server | | --- | --- | --- | -| Token cost | a few, only when called | full tool schema, every turn | -| Context footprint | zero when idle | always present | +| Token cost | a few, only when called | a schema every turn; less with tool/context selection | +| Speed | fastest | slower | | Use when | a CLI exists | no CLI, or you need typed/live tool calls | See [`mcp-installation.md`](mcp-installation.md). ### 🔴 Expert -#### 10) 📚 Use progressive disclosure +#### 10) 📚 Load knowledge on demand -Load knowledge only when the task needs it, instead of riding along every turn. +Big procedural docs pasted into context are taxed every turn. Keep them as skills or rules instead: each loads only when its trigger matches the task, so it costs zero tokens until needed. -- Install an AIDD framework so skills, rules, and runbooks load on demand. +1. Install an AIDD framework so skills, rules, and runbooks load on demand. ```text -skill description matched → its steps load +skill trigger matches the task → its steps load no match → 0 tokens spent ``` #### 11) 🎯 Route by difficulty -The top model on routine work is wasted spend. +The top model on routine work is wasted spend, so match the model to the task. -- Send research and boilerplate to a cheaper model or a fresh subagent. -- Reserve the strongest model for hard reasoning. +1. Send research and boilerplate to a cheaper model or a fresh subagent. +2. Reserve the strongest model for hard reasoning. ```text research / boilerplate → small model or subagent @@ -171,22 +168,17 @@ architecture / tricky bug → top model Extended reasoning can silently add thousands of tokens on tasks that don't need it. -- Set `MAX_THINKING_TOKENS` to `0` for routine work. -- See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). +1. In `settings.json`, set `MAX_THINKING_TOKENS` to `0` for routine work. +2. See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). -```bash -# settings.json (env) -"MAX_THINKING_TOKENS": "0" # disable extended thinking for routine work +```json +{ + "env": { + "MAX_THINKING_TOKENS": "0" + } +} ``` -## Verify +## In short -- Run `/cost` before and after a typical task — the token count drops measurably. -- `/context` shows your instruction file and tool schemas taking a smaller share of the window. -- A noisy command routed through RTK or SNIP returns far fewer lines than the raw run. - -## Related - -- [`mcp-installation.md`](mcp-installation.md) — why CLI beats MCP for context efficiency -- [Anthropic — Claude Code costs](https://code.claude.com/docs/en/costs) · [settings](https://code.claude.com/docs/en/settings) -- Tools: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) · [`ccusage`](https://www.npmjs.com/package/ccusage) · [`caveman`](https://github.com/JuliusBrussee/caveman) · [`RTK`](https://github.com/rtk-ai/rtk) · [`SNIP`](https://github.com/edouard-claude/snip) · [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) +Measure first, then stack the cheap wins — trimmed instructions, less chatter, filtered output — before reaching for model routing. Most of the bill is cache and repetition; cut those and the cost follows. From 047e926e066eb379de0250fc7519df63e6ad23e3 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:28:22 +0200 Subject: [PATCH 18/22] refactor(aidd-context): add bullet/diagram/config/section rules to contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From the token-optimization review: - Actions are a numbered list; descriptions and indications are prose, never bullets. - A Mermaid diagram carries concrete example values. - A config example uses the file's real syntax (valid JSON for settings.json, valid YAML for frontmatter, ...). - Reuse a tool's canonical example captured verbatim — never a paraphrase or on the strength of a summary that one exists. - No `## Related` section (links live inline); `## Verify` is optional; recipes may end with a short conclusion. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- .../skills/12-cook/assets/recipe-template.md | 23 ++++++++----------- .../12-cook/references/recipe-contract.md | 12 ++++++---- 2 files changed, 16 insertions(+), 19 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md index a60cb11d..95a189c4 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -12,11 +12,10 @@ #### 1) <emoji> <First step title> -<One benefit-focused line: what this gets the reader and why.> +<One benefit-focused line of what and why, in prose.> -- <where it is / what it is> -- <install it from its URL> -- <how to use it> +1. <where it is, then install it from its URL> +2. <how to invoke it — its real command or slash> ```bash $ <command the reader runs> @@ -27,10 +26,10 @@ $ <command the reader runs> #### 2) <emoji> <Next step title> -<Benefit-focused what and why.> +<Benefit-focused what and why, in prose.> -- <how> -- <how> +1. <action> +2. <action> ```<lang> <a config or snippet the reader can copy> @@ -40,16 +39,12 @@ $ <command the reader runs> #### 3) <emoji> <Last step title — until the goal is reached> -<Benefit-focused what and why.> +<Benefit-focused what and why, in prose.> -- <how> +1. <action> ![<what this screenshot or video shows>](<path-or-url>) ## Verify -- <An observable check that proves it worked: a command, a UI state, a file that now exists.> - -## Related - -- <Link to a sibling recipe, a skill, or a doc the reader needs next.> +- <Optional. An observable check that proves it worked: a command, a UI state, a file that now exists.> diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index 68c40371..849f9a2b 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -8,6 +8,7 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. - Path: `recipes/<kebab-slug>.md`. - The recipe opens with the H1 title, then one plain sentence of description — no "Goal:" label, no blockquote, no metadata table. +- Sections: the description, `## Why`, then the steps. `## Verify` is optional — omit it when it adds little. End with an optional short conclusion. Never add a `## Related` section: links live inline where they are used. ## Writing @@ -19,11 +20,12 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. - The steps section heading is named after the goal: `## Steps to <outcome>`, never a bare `## Steps`. - One step = one action: never bundle several tools or commands under one heading; split them. -- Each step is a `#### N) <emoji> Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. -- How-bullets are straight to the point and ordered for action. For a tool: where it is, install it from its URL, then how to invoke it (its real command or slash invocation, e.g. `/caveman`). -- Every step carries one concrete example. Prefer an image — a screenshot or short video/GIF that matches the action — over text whenever one exists; for a tool, use its official screenshot. Otherwise: a command with its real output (show what it prints, not just the command), or a config or snippet. -- Reuse the canonical example from the tool's own site or README, never an invented one. +- Each step is a `#### N) <emoji> Title` heading, then one benefit-focused line of what and why in prose. Number steps continuously. +- Write the actions to take as a numbered list; write any description or indication as prose, never as a bullet. +- For a tool: where it is, install it from its URL, then how to invoke it (its real command or slash invocation, e.g. `/caveman`). +- Reuse the tool's canonical example captured verbatim from its site or README — never a paraphrase, and never on the strength of a summary that says one exists. +- Every step carries one concrete example. Prefer an image — a screenshot or short video/GIF that matches the action — over text whenever one exists; for a tool, use its official screenshot. Otherwise: a command with its real output, a config in the file's real syntax (valid JSON for `settings.json`, valid YAML for frontmatter, …), or a snippet. - A step that prefers one option over another uses a comparison table, not prose. -- For a structural or flow concept (a proxy, a pipeline, an architecture), add a small Mermaid diagram. +- For a structural or flow concept (a proxy, a pipeline, an architecture), add a small Mermaid diagram with concrete example values. - Level subheadings are optional. Group steps under `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert` only when the recipe spans difficulty levels and grouping helps the reader; a short or single-level recipe lists its steps directly. Include only the levels that have a step. - Link to a reference when applicable. From 9f7dcaaedf66646f25977ef2bdaf151a73b7ea77 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:32:34 +0200 Subject: [PATCH 19/22] docs(framework): expert steps use verified Claude Code config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Step 10 now audits which skills/tools run via `Ctrl+O` (toggles the detailed transcript), instead of the vaguer "load on demand". - Step 11 routes by difficulty with the real `model:` frontmatter field on a skill or agent (haiku/sonnet/opus/inherit) — example agent pinned to haiku. Both verified against the official Claude Code docs (interactive-mode, skills, sub-agents). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 753fc50c..747a90e2 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -141,29 +141,41 @@ See [`mcp-installation.md`](mcp-installation.md). ### 🔴 Expert -#### 10) 📚 Load knowledge on demand +#### 10) 🔬 Audit which skills and tools run — `Ctrl+O` -Big procedural docs pasted into context are taxed every turn. Keep them as skills or rules instead: each loads only when its trigger matches the task, so it costs zero tokens until needed. +You optimise what you can see, so expand the transcript to watch what each turn actually invokes and pulls into context. -1. Install an AIDD framework so skills, rules, and runbooks load on demand. +1. Press `Ctrl+O` to toggle the transcript — it shows detailed tool and skill usage and expands collapsed MCP calls. +2. Spot skills or tools that load on turns that don't need them, then scope or remove them. ```text -skill trigger matches the task → its steps load -no match → 0 tokens spent +Ctrl+O — transcript expanded + ⎿ Skill: token-optimization + ⎿ Called slack 3 times → expanded: 3 tool calls +(illustrative — replace with a screenshot of your real Ctrl+O transcript) ``` +See the [keyboard shortcuts](https://code.claude.com/docs/en/interactive-mode). + #### 11) 🎯 Route by difficulty -The top model on routine work is wasted spend, so match the model to the task. +The top model on routine work is wasted spend, so pin the model per skill or agent — cheap for routine, top-tier for hard reasoning. -1. Send research and boilerplate to a cheaper model or a fresh subagent. -2. Reserve the strongest model for hard reasoning. +1. Set `model` in a skill's or an agent's frontmatter (`haiku` / `sonnet` / `opus`, a full id, or `inherit`). +2. Give routine scouts a small model; reserve `opus` for the hard reasoning. -```text -research / boilerplate → small model or subagent -architecture / tricky bug → top model +```yaml +# .claude/agents/explore.md — routine scouting on a cheap model +--- +name: explore +description: Read-only codebase scout +tools: Read, Grep, Glob +model: haiku +--- ``` +A skill's `SKILL.md` takes the same `model:` field (e.g. `model: opus` for a heavy step). See [sub-agents](https://code.claude.com/docs/en/sub-agents) and [skills](https://code.claude.com/docs/en/skills). + #### 12) ✅ Cap extended thinking Extended reasoning can silently add thousands of tokens on tasks that don't need it. From 92050b1d797bc22520206c1bfdea6af6f2f4760c Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Mon, 22 Jun 2026 09:40:07 +0200 Subject: [PATCH 20/22] docs(framework): point the instruction-file step at AGENTS.md Use the framework's own concise AGENTS.md as the worked example for a trimmed instruction file, with its real rules (answer first, no narration), instead of a generic snippet. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 747a90e2..5aadad43 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -74,11 +74,12 @@ Your instruction file ships every turn, so each cut line saves on every message. 1. Open `CLAUDE.md` (or `.github/copilot-instructions.md`). 2. Cut it to essentials and add explicit conciseness rules. -3. Reuse the [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) ruleset. +3. Model it on a real concise instruction file: [AGENTS.md](../plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md). ```md -# CLAUDE.md -- Terse answers. No preamble, no "Let me…", no closing summary. +# CLAUDE.md — keep it terse (see AGENTS.md for the full example) +- Answer first. Lead with the result, then the reason. Drop pleasantries and hedging. +- No tool-call narration. No decorative tables or emoji unless they carry information. - Keep verbatim: code, quoted errors, security warnings. Cut the rest. ``` From 781e5a5f42ef298d3c908d9b30df8829e900da38 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Mon, 22 Jun 2026 09:40:07 +0200 Subject: [PATCH 21/22] refactor(aidd-context): apply analyses a recipe and asks before acting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A recipe is often a human tutorial, not an agent-runnable procedure. So apply now reads the recipe, classifies each step agent-doable vs human-only, and asks the user what to do before any change — then runs the chosen agent-doable steps and reports the human-only ones. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- .../skills/12-cook/actions/04-apply.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/actions/04-apply.md b/plugins/aidd-context/skills/12-cook/actions/04-apply.md index b337eea5..fbc82a0b 100644 --- a/plugins/aidd-context/skills/12-cook/actions/04-apply.md +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -1,6 +1,6 @@ # 04 - Apply recipe -Execute an existing recipe against the current project by spawning an agent that works through its steps as a tracked todo list, confirming with the user. +Analyse a chosen recipe, ask the user what to do, then run the agent-doable steps and report the rest. ## Input @@ -8,16 +8,17 @@ The recipe to apply, named by slug or topic. ## Output -The recipe's steps carried out on the project, tracked as a todo list, ending with its `## Verify` checks run and reported. +A short analysis of the recipe — what it achieves, and which steps the agent can run versus which are the human's — then, on the user's choice, the chosen steps carried out and a report of what is left for the human. ## Process 1. **Locate.** Resolve the recipe to `recipes/<slug>.md` and read it. Run `list` first when the recipe is unnamed. -2. **Plan.** Turn each step under the recipe's steps heading (`## Steps to …`) into one todo entry. -3. **Confirm.** Show the user the plan and ask for confirmation before any change. -4. **Execute.** Spawn an agent via the `Task` tool to work the todo list in order. It marks each item done as it lands, and pauses for confirmation on any step that mutates the project. -5. **Verify.** Run the recipe's `## Verify` checks and report pass or fail. +2. **Analyse.** Read each step and classify it: agent-doable (a file edit, a config change) or human-only (a TUI command, an install, anything needing the user's terminal or UI). Summarise what the recipe achieves and what is in scope for the agent. +3. **Ask.** Show the analysis and ask the user what to do — run all agent-doable steps, a subset, or just report. Never mutate before this answer. +4. **Execute.** For the chosen steps, work them as a tracked todo list, pausing for confirmation on any step that changes a file. Leave the human-only steps untouched. +5. **Report.** Report what was done, list the human-only steps as instructions for the user, and run any `## Verify` checks. ## Test -- Applying a recipe produces a todo list mirroring the recipe's steps, asks for confirmation before executing, and runs the `## Verify` checks at the end. +- Applying a recipe first produces an analysis that marks each step agent-doable or human-only, then asks the user what to do before any change. +- The chosen agent-doable steps run as a todo list; human-only steps are reported as instructions, never executed. From 7f7a7fbf305e60133cfea25b3f5c62b3c025c10c Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Mon, 22 Jun 2026 10:08:32 +0200 Subject: [PATCH 22/22] docs(framework): add five verified token levers to the recipe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From a research pass, all verified against official Claude Code docs: - Plan mode (Shift+Tab ×2) — avoid execution-phase rework. - `/clear` between tasks — drop stale context instead of re-billing it. - Deny reads (`permissions.deny`) — keep vendor/dist/secrets out of context; the official answer to the unshipped `.claudeignore`. - Subagent offload — run high-volume ops in an isolated context. - Protect cache hits — avoid mid-task model/MCP/effort switches that invalidate the cache (closes the loop on "cache reads dominate"). Also fold the built-in `outputStyle: concise` into the "talk less" step. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 100 ++++++++++++++++++++++++++++++---- 1 file changed, 90 insertions(+), 10 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 5aadad43..5f18d43f 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -83,7 +83,35 @@ Your instruction file ships every turn, so each cut line saves on every message. - Keep verbatim: code, quoted errors, security warnings. Cut the rest. ``` -#### 6) 🗜️ Compact deliberately +#### 6) 🧭 Plan before you edit — plan mode + +Approving the wrong direction burns tokens on rework, so let Claude explore read-only and propose a plan first. + +1. Press `Shift+Tab` twice to enter plan mode (or start with `claude --permission-mode plan`). +2. Review the plan, then approve to switch to execution. + +```text +Shift+Tab Shift+Tab → ⏸ plan mode + Claude reads and proposes; no edits until you approve +``` + +See [permission modes](https://code.claude.com/docs/en/permission-modes). + +#### 7) ♻️ Clear context between tasks — `/clear` + +Stale early turns ride along and get re-billed every turn, so reset when the task changes. + +1. Finish a task, then run `/clear` to drop the history and reload only `CLAUDE.md` and memory. +2. Use `/compact` instead when you want to keep a summary of the same task. + +```text +$ /clear + history dropped → fresh window, CLAUDE.md + memory reloaded +``` + +See [reduce token usage](https://code.claude.com/docs/en/costs). + +#### 8) 🗜️ Compact deliberately Compacting on your terms keeps what matters instead of letting auto-compaction guess. @@ -96,12 +124,12 @@ $ /compact keep the repro steps and the failing test; drop the file dumps ### 🟡 Intermediate -#### 7) 🗣️ Make the agent talk less +#### 9) 🗣️ Make the agent talk less Output is repetition you pay to generate, so cap the chatter. caveman forces short, filler-free replies (reported ~65% output cut, code intact) and auto-detects 30+ agents. -1. Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill. -2. Invoke it like any skill: `/caveman` (or `/caveman ultra` for the hardest cut); stop with "normal mode". +1. Built-in route: set `"outputStyle": "concise"` in `settings.json`. +2. Harder cut: install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill and invoke it like any skill — `/caveman` (or `/caveman ultra`); stop with "normal mode". ```text /caveman @@ -111,7 +139,9 @@ before: The reason your React component is re-rendering is likely because you're after: New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`. ``` -#### 8) 🧹 Filter noisy command output +See [output styles](https://code.claude.com/docs/en/output-styles). + +#### 10) 🧹 Filter noisy command output Test, install, and build logs flood context with lines the model never needs. @@ -128,7 +158,24 @@ flowchart LR Real saving: `git push` (15 lines, ~200 tokens) -> `rtk git push` (1 line, ~10 tokens). -#### 9) 🔌 Prefer CLI over MCP +#### 11) 🚫 Keep big paths out of context — deny reads + +Vendor dirs, build output, and secrets get pulled into context by accident. Deny reads on them so they stay out — they remain grep-able. + +1. In `settings.json`, add `Read(...)` deny rules for large or sensitive paths. +2. `.claudeignore` is not shipped — deny rules are the official way. + +```json +{ + "permissions": { + "deny": ["Read(./vendor/**)", "Read(./dist/**)", "Read(./.env)"] + } +} +``` + +See [permissions](https://code.claude.com/docs/en/permissions). + +#### 12) 🔌 Prefer CLI over MCP An MCP server's schema rides along every turn; a CLI costs tokens only when you call it. Newer MCP tooling adds tool/context selection that loads only the tools you pick — cheaper than before — but a CLI is still leaner and faster. @@ -142,7 +189,7 @@ See [`mcp-installation.md`](mcp-installation.md). ### 🔴 Expert -#### 10) 🔬 Audit which skills and tools run — `Ctrl+O` +#### 13) 🔬 Audit which skills and tools run — `Ctrl+O` You optimise what you can see, so expand the transcript to watch what each turn actually invokes and pulls into context. @@ -158,7 +205,7 @@ Ctrl+O — transcript expanded See the [keyboard shortcuts](https://code.claude.com/docs/en/interactive-mode). -#### 11) 🎯 Route by difficulty +#### 14) 🎯 Route by difficulty The top model on routine work is wasted spend, so pin the model per skill or agent — cheap for routine, top-tier for hard reasoning. @@ -177,7 +224,40 @@ model: haiku A skill's `SKILL.md` takes the same `model:` field (e.g. `model: opus` for a heavy step). See [sub-agents](https://code.claude.com/docs/en/sub-agents) and [skills](https://code.claude.com/docs/en/skills). -#### 12) ✅ Cap extended thinking +#### 15) 🧫 Offload high-volume work to subagents + +Test runs, log parsing, and wide exploration flood the main window. A subagent does it in its own context and hands back only a summary, so the bloat never lands in your session. + +1. Define an agent in `.claude/agents/<name>.md` with only the tools it needs and a small `model`. +2. Let it run the noisy op and return a short result. + +```yaml +# .claude/agents/test-runner.md +--- +name: test-runner +description: Run the suite and return only the failures +tools: Bash, Read +model: haiku +--- +``` + +See [sub-agents](https://code.claude.com/docs/en/sub-agents). + +#### 16) 🧊 Protect your cache hits + +Cached input bills far cheaper, and cache reads are most of your tokens (step 4) — so don't throw the cache away mid-task. A model switch, an MCP connect or disconnect, or an effort change rebuilds it from scratch. + +1. Set the model and reasoning effort at the start of a task, not mid-work. +2. Switch model or toggle MCP servers only at task boundaries, where a cache rebuild is acceptable. + +```text +mid-task model switch → cache invalidated → full re-bill +same model to a boundary → cache reads stay cheap +``` + +See [prompt caching](https://code.claude.com/docs/en/prompt-caching). + +#### 17) ✅ Cap extended thinking Extended reasoning can silently add thousands of tokens on tasks that don't need it. @@ -194,4 +274,4 @@ Extended reasoning can silently add thousands of tokens on tasks that don't need ## In short -Measure first, then stack the cheap wins — trimmed instructions, less chatter, filtered output — before reaching for model routing. Most of the bill is cache and repetition; cut those and the cost follows. +Measure first, then stack the cheap wins — trimmed instructions, plan mode, a clean context, less chatter, filtered output — before the advanced routing, subagents, and cache discipline. Most of the bill is cache and repetition; cut those and the cost follows.