diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 3ce4b47f..bc539548 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -196,7 +196,13 @@ 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` | [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) | - | -| `-` | [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` | [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".` | 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..1031e621 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, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe". --- # Cook @@ -9,13 +9,19 @@ 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/recipe-contract.md`: the rules every recipe file follows; `upsert` writes to it. ## 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. 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 62e87015..22816be8 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -1,17 +1,26 @@ # 02 - Upsert recipe -Create or update one recipe at `recipes/<slug>.md`, scaffolded from `@assets/recipe-template.md`. +Create or update one recipe at `recipes/<slug>.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 (description, steps, verify, related) before writing. ## Process -1. Derive a kebab-case `<slug>` from the topic → `recipes/<slug>.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 `<slug>.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 `<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 | Description |`: link the title to `<slug>.md` (relative) and copy the one-sentence description. Same columns `list` emits. ## Test -- `recipes/<slug>.md` exists and matches the template, every section present, no `<...>` placeholder left. +- A new or substantially-updated recipe is drafted from `research` results, not from memory. +- `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/actions/03-research.md b/plugins/aidd-context/skills/12-cook/actions/03-research.md new file mode 100644 index 00000000..e6c8695b --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -0,0 +1,47 @@ +# 03 - Research alternatives + +Refine the target recipe with a checklist, scout for the highest-value insights, verify each one exists, and propose them as sorted lists. + +## Input + +The recipe or topic to modernize. If a recipe, its `recipes/<slug>.md` holds the current approach and coverage. + +## Output + +Three parts, then a recommendation: + +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. + +Every presented item is confirmed to exist, with its latest state and official link. Ephemeral: nothing is written under `recipes/`. + +## Process + +1. **Refine.** Fill the goal checklist with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/<slug>.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/actions/04-apply.md b/plugins/aidd-context/skills/12-cook/actions/04-apply.md new file mode 100644 index 00000000..fbc82a0b --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -0,0 +1,24 @@ +# 04 - Apply recipe + +Analyse a chosen recipe, ask the user what to do, then run the agent-doable steps and report the rest. + +## Input + +The recipe to apply, named by slug or topic. + +## Output + +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. **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 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. 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..95a189c4 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -1,29 +1,50 @@ -<!-- Recipe contract: file is recipes/<kebab-slug>.md · Level ∈ {Beginner, Intermediate, Advanced} · Time prefixed with ~ · one idea per sentence, prefer removing over adding. --> - # <Recipe title> -> **Goal:** <one line stating the outcome the reader achieves> - -| | | -| ----------------- | ---------------------------------------- | -| **Level** | <Beginner \| Intermediate \| Advanced> | -| **Time** | ~<N> min | -| **Prerequisites** | <what the reader needs first, or "None"> | +<One sentence describing what this recipe gets the reader.> ## Why -<One short paragraph: the problem this recipe solves and when to reach for it.> +<Short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms.> -## Steps +## Steps to <the outcome the reader achieves> -1. 📋 **<First step>** — <imperative instruction.> -2. 🔧 **<Next step>** — <imperative instruction.> -3. ✅ **<Last step>** — <until the goal is reached.> +### 🟢 Beginner -## Verify +#### 1) <emoji> <First step title> + +<One benefit-focused line of what and why, in prose.> + +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> +<the useful output it prints, trimmed to what matters> +``` + +### 🟡 Intermediate + +#### 2) <emoji> <Next step title> -- <An observable check that proves it worked: a command, a UI state, a file that now exists.> +<Benefit-focused what and why, in prose.> -## Related +1. <action> +2. <action> + +```<lang> +<a config or snippet the reader can copy> +``` + +### 🔴 Expert + +#### 3) <emoji> <Last step title — until the goal is reached> + +<Benefit-focused what and why, in prose.> + +1. <action> + +![<what this screenshot or video shows>](<path-or-url>) + +## Verify -- <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/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 @@ +<!-- Tick before drafting in 03-research. A research pass is done only when all three clear. --> + +# 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/assets/research-goal-checklist.md b/plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md new file mode 100644 index 00000000..3ad21d32 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md @@ -0,0 +1,12 @@ +<!-- Filled with the user before scouting in 03-research. Defines the target recipe. --> + +# 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 / 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** — 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 new file mode 100644 index 00000000..849f9a2b --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -0,0 +1,31 @@ +<!-- Cited by upsert. The rules every recipe file follows. --> + +# Recipe contract + +Rules for every `recipes/<kebab-slug>.md` the skill writes. + +## File + +- 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 + +- 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, 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, 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 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. 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..40db46c7 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -0,0 +1,38 @@ +<!-- Read before spawning research agents in 03-research. The scouting angles, the bar each candidate must clear, and how to verify them. Not a recipe itself. --> + +# 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/research-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. + +## 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. +- **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 + +- 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. 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..5f18d43f --- /dev/null +++ b/recipes/token-optimization.md @@ -0,0 +1,277 @@ +# Token optimization for AI IDEs + +Cut token usage and cost in AI coding assistants without losing output quality. + +## Why optimize your tokens + +**Token usage** is the bill — every turn re-sends your whole **context window** 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 your output. + +## Steps to cut token usage + +### 🟢 Beginner + +#### 1) 🔎 See what fills the window — `/context` + +`/context` paints your context as a grid, so you cut the biggest consumers instead of guessing. + +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% +(illustrative — replace with a screenshot of your real /context) +``` + +#### 2) 💸 Read the bill — `/cost` + +`/cost` tells you what a session actually costs and where the spend goes. + +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 + Session: $0.42 · 1.2M tokens + By: subagents 38% · MCP 21% · main 41% +(illustrative — replace with a screenshot of your real /cost) +``` + +#### 3) 🔍 Find your bad habits — `/insights` + +`/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. + +1. Run `/insights`. +2. Move what you repeat into `CLAUDE.md` or a rule, and drop the habits it flags. + +```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 — replace with a screenshot of your real /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. 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) + +#### 5) ✂️ Trim your instruction file + +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. Model it on a real concise instruction file: [AGENTS.md](../plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md). + +```md +# 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. +``` + +#### 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. + +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 +``` + +### 🟡 Intermediate + +#### 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. 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 + +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`. +``` + +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. + +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["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). + +#### 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. + +| | CLI (`gh`, `acli`, …) | MCP server | +| --- | --- | --- | +| 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 + +#### 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. + +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 +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). + +#### 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. + +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. + +```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). + +#### 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. + +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). + +```json +{ + "env": { + "MAX_THINKING_TOKENS": "0" + } +} +``` + +## In short + +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.