speckit-token-budget-concise
Skill107 starsChanged 9 months agoMITView on GitHub
Toggle a project-local concise-output directive that suppresses agent
In this repository48 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- commitSkill
- create-pull-requestSkill
- create-release-branchSkill
- create-release-notesSkill
- handle-pr-reviewSkill
- qlty-checkSkill
- record-code-review-feedbackSkill
- record-spec-feedbackSkill
- recreate-test-dbSkill
- redmine-playwright-loginSkill
- regression-checkSkill
- rubocopSkill
- speckit-agent-context-updateSkill
- speckit-analyzeSkill
- speckit-branch-convention-configureSkill
- speckit-branch-convention-renameSkill
- speckit-branch-convention-validateSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-git-commitSkill
- speckit-git-featureSkill
- speckit-git-initializeSkill
- speckit-git-remoteSkill
- speckit-git-validateSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-review-codeSkill
- speckit-review-commentsSkill
- speckit-review-errorsSkill
- speckit-review-runSkill
- speckit-review-simplifySkill
- speckit-review-testsSkill
- speckit-review-typesSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- speckit-token-budget-compactSkill
- speckit-token-budget-scopeSkill
- speckit-token-budget-usageSkill
- speckit-wiki-ingestSkill
- speckit-wiki-initSkill
- speckit-wiki-lintSkill
- speckit-wiki-querySkill
- speckit-wiki-statusSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 49
1a. Honor
--file=<path>: if the user passed one. Skip the rest. - Distinctive: line 51
1b. Auto-detect the active spec-kit agent: Look at the project to see which agent's command directory exists and is populated.
- Distinctive: line 69
If exactly one agent is detected, that agent's canonical memory file is the agent-specific candidate for the next step.
- Very specific: line 72
1c. Apply the preference rule: Read concise.memory_files and concise.prefer_agent from token-budget-config.yml.
- Very specific: line 75
If AGENTS.md exists at the project root and prefer_agent is empty (the default), write the directive to AGENTS.md.
- Distinctive: line 83
If none of the listed files exist, create AGENTS.md at the project root and write the directive there.
- Distinctive: line 96
Look for the marker block:
- Very specific: line 156
After writing, read the file back and verify the marker presence (for on) or absence (for off) matches the requested state.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Token Budget Concise Skill
/speckit.token-budget.concise
The user has invoked /speckit.token-budget.concise with arguments: $ARGUMENTS.
Your task
Manage the concise-output directive in the project's agent memory
file. This directive tells the AI agent — when it next runs any
/speckit.* command — to suppress narrative padding (recap of what it's
about to do, "Let me ...", "I'll go ahead and ...", "Here is what I
did", "I hope this helps") and return only the artifact diff, the file
write, or the structured result.
Output prose is a small share of total session tokens (the input side dominates), but the savings compound across the 4–6 SDD steps and the follow-up clarifications a feature usually needs. More importantly, concise mode shortens turn round-trips, which is the dimension users notice most.
Arguments
on→ enable concise mode (write the directive)off→ disable concise mode (remove the directive)status(or empty) → report current state and which memory file is in use--file=<path>→ force a specific memory file instead of auto-detecting
Algorithm
Step 1 — Locate the memory file
Apply this resolution order. Stop at the first match.
1a. Honor --file=<path> if the user passed one. Skip the rest.
1b. Auto-detect the active spec-kit agent. Look at the project to see which agent's command directory exists and is populated. Common signals, checked in this order:
| Signal | Implies agent | Canonical memory file |
.claude/commands/ has files | Claude Code | CLAUDE.md |
.gemini/commands/ has files | Gemini CLI | GEMINI.md |
.github/prompts/ has files | Copilot | .github/copilot-instructions.md |
.cursor/commands/ or .cursor/skills/ has files | Cursor | .cursor/rules/token-budget.mdc |
.windsurf/workflows/ has files | Windsurf | .windsurf/rules/token-budget.md |
.tabnine/agent/commands/ has files | Tabnine | .tabnine/AGENTS.md |
.agents/skills/speckit-*/ has files | Codex | AGENTS.md |
.pi/prompts/ has files | Pi Coding Agent | .pi/AGENTS.md |
.kilocode/ has files | Kilo Code | .kilocode/rules.md |
.roo/ has files | Roo Code | .roo/rules/token-budget.md |
.clinerules exists | Cline | .clinerules |
If exactly one agent is detected, that agent's canonical memory file is the agent-specific candidate for the next step.
1c. Apply the preference rule. Read concise.memory_files and
concise.prefer_agent from token-budget-config.yml.
- If
AGENTS.mdexists at the project root andprefer_agentis empty (the default), write the directive toAGENTS.md. This is the open cross-agent standard — most modern agents read it, so a single write reaches every agent on the project. - Otherwise, if
prefer_agentmatches the auto-detected agent and that agent's specific memory file exists, use it. - Otherwise, walk
concise.memory_filesin order and use the first file that exists. - If none of the listed files exist, create
AGENTS.mdat the project root and write the directive there. (This is the lowest- conflict default for any project, including ones not yet committed to a single agent.)
1d. If the user has multiple agents installed in the same project
(e.g. both .claude/commands/ and .cursor/commands/ populated),
prefer AGENTS.md regardless of prefer_agent. The whole point of
AGENTS.md is to avoid forking the directive across N tool-specific
files. Print a one-line note so the user knows: Multiple agents
detected → directive written to AGENTS.md (read by all).
Step 2 — Detect current state
Look for the marker block:
<!-- BEGIN token-budget concise-mode -->
... directive text ...
<!-- END token-budget concise-mode -->The exact marker strings come from concise.marker_begin and
concise.marker_end in the config. If the markers are present,
concise mode is on. If not, it is off.
Step 3 — Act on the requested state
on — append the following block to the memory file (or insert it
immediately before the closing of any existing top-level "Conventions"
or "Workflow" section, if one exists):
<!-- BEGIN token-budget concise-mode -->
## Token Budget — concise mode (active)
When executing any `/speckit.*` command (constitution, specify,
clarify, plan, tasks, analyze, implement, checklist,
token-budget.*), follow these output rules:
- Do not narrate plans, intentions, or steps. Run them.
- Do not recap the user's prompt back to them.
- Do not announce file writes ("I'll create...", "Now writing..."). Just write.
- After completing the command, output only:
1. The list of files created or changed, one per line.
2. Any blocking question or unmet assumption, in one sentence.
3. The single line "Done." if there is nothing else to report.
- Tables, fenced code, and structured data inside artifacts are
unaffected — this rule governs only the chat-channel prose around
them.
- Override on request: if the user explicitly asks "explain", "walk
me through", "why", or "what did you do", drop concise mode for
that single reply and answer normally.
These rules apply only inside `/speckit.*` workflows. Conversational
replies outside SDD steps are not affected.
<!-- END token-budget concise-mode -->off — locate the marker block and remove it cleanly, including
the blank line before the begin marker if one is present (avoid leaving
a double blank line behind).
status — print:
Concise mode: <on|off>
Memory file: <path>
Last toggled: <ISO-8601 from a `<!-- toggled: ... -->` line in the block, if present>Step 4 — Confirm
After writing, read the file back and verify the marker presence (for
on) or absence (for off) matches the requested state. Print one of:
✓ Concise mode enabled in <path>.
✓ Concise mode disabled. <path> restored.End the response.
Why this is reversible
The directive lives between unique markers, never inline with user-
authored content. concise off is a deterministic block deletion. The
user can also remove the block by hand at any time without breaking
anything.
What this command does not do
It does not modify any spec-kit artifact, does not change agent settings outside the memory file, and does not affect non-SDD conversations. If the user wants global concise output, they should adopt a tool like Caveman directly — Token Budget only governs the SDD workflow surface.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

