speckit-token-budget-usage
Skill107 starsChanged 9 months agoMITView on GitHub
Show token usage for every SDD artifact in the active feature, the projected
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-conciseSkill
- speckit-token-budget-scopeSkill
- 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
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
Default scope: the active feature (from current git branch).
- Very specific: line 88
If --all was passed, repeat the artifact table once per feature and add a final cross-feature roll-up showing the total savings.
- Distinctive: line 92
If any single artifact exceeds 5,000 tokens and is not compacted, append a one-line nudge:
- Distinctive: line 100
If concise mode is off and the project is large (more than 12k total tokens), suggest:
- Distinctive: line 107
Only emit suggestions that are actually warranted by the numbers.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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 Usage Skill
/speckit.token-budget.usage
The user has invoked /speckit.token-budget.usage with arguments: $ARGUMENTS.
Your task
Inspect the active feature directory and produce a one-screen token-usage dashboard. Read-only — never modify artifacts.
Algorithm
Step 1 — Resolve scope
Default scope: the active feature (from current git branch). If
$ARGUMENTS contains --all, walk every feature under specs/. If it
contains --feature=<name>, target that feature.
Step 2 — Enumerate artifacts
For each artifact present, record:
- path (relative to feature directory)
- byte size
- estimated token count (use
estimate_tokens.sh) - whether a
.full.mdbackup exists, and its token count if so - whether the file carries the
<!-- token-budget: compacted -->marker
Standard artifact set: constitution.md, spec.md, plan.md,
research.md, data-model.md, quickstart.md, tasks.md, every file
in contracts/, plus any extra .md files in the feature root (treat
as auxiliary).
Step 3 — Project per-phase budgets
For each upcoming phase the feature has not yet completed, sum the
artifacts it would normally consume (from scope.phase_inputs in
token-budget-config.yml). Show two numbers per phase: current size,
and size if every artifact were compacted (estimated as 60% for medium,
45% for aggressive — these are heuristics, not guarantees, and should
be labeled as such).
Step 4 — Render
Output exactly this layout. Right-align numbers. Use thousands separators. Pad with spaces, not tabs.
Token Budget — feature: <feature-name>
Path: specs/<feature-name>/
Artifact tokens vs full status
─────────────────────────────────────────────────────────────────
constitution.md 1,240 — baseline
spec.md 2,310 -52.1% compacted (medium)
plan.md 3,580 -41.7% compacted (medium)
research.md 1,180 -63.1% compacted (medium)
data-model.md 1,840 — baseline
contracts/orders.yaml 910 — schema (not eligible)
contracts/users.yaml 820 — schema (not eligible)
quickstart.md 640 — baseline
tasks.md 4,210 — baseline
─────────────────────────────────────────────────────────────────
total 16,730 -27.4% vs uncompacted
Projected phase budgets
current if aggressive compact
plan (done) — —
tasks (done) — —
implement 12,560 ~7,540
analyze 10,100 ~6,060
Backups present: spec.full.md, plan.full.md, research.full.md
Concise mode: <on|off> (memory file: <path>)If --all was passed, repeat the artifact table once per feature and
add a final cross-feature roll-up showing the total savings.
Step 5 — Recommendations (only when warranted)
If any single artifact exceeds 5,000 tokens and is not compacted, append a one-line nudge:
Suggestion: tasks.md is 6,140 tokens. /speckit.token-budget.compact tasks
would likely save ~40%.If concise mode is off and the project is large (more than 12k total tokens), suggest:
Suggestion: /speckit.token-budget.concise on (estimated 5–15% output savings)Only emit suggestions that are actually warranted by the numbers. No generic advice.
End the response. The dashboard is the deliverable.
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.

