speckit-token-budget-compact
Skill107 starsChanged 9 months agoMITView on GitHub
Compact one or more Spec-Driven Development artifacts in place to reduce
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-conciseSkill
- 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, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 54
If keep_full_backup is true and <artifact>.full.md does not yet exist, copy the current artifact to <artifact>.full.md.
- Very specific: line 60
Remove HTML comments left over from templates (<!-- ...
- Very specific: line 63
Remove sections whose heading prefix-matches any entry in compact.drop_sections.
- Very specific: line 66
Remove decorative ASCII separators (---, ===, repeated * or _ runs) that are not Markdown horizontal rules between meaningful sections.
- Distinctive: line 111
If at any point you are uncertain whether a transformation is lossless, do
- Very specific: line 116
After stripping, ensure heading levels are still contiguous (no jump from # to ###).
- Distinctive: line 155
Use it to keep your edits auditable and the output consistent.
- Very specific: line 160
If an artifact already carries the <!-- token-budget: compacted --> marker, re-compaction works against the .full.md backup, not the …
≈ “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 Compact Skill
/speckit.token-budget.compact
The user has invoked /speckit.token-budget.compact with arguments: $ARGUMENTS.
Your task
Compact one or more SDD artifacts in the active feature so that downstream spec-kit commands consume fewer tokens, without losing any requirement, decision, contract, ID, user story, or acceptance criterion.
Inputs
- Resolve the active feature directory (typically
specs/<NNN-feature-name>/) from the current git branch using the existing spec-kit conventions. If the user is not on a feature branch, ask which feature to operate on and stop. - Parse
$ARGUMENTS:- empty → compact every artifact in the active feature directory.
spec|plan|tasks|research|data-model|contracts|quickstart|constitution→ compact only that one (or that group, in the case ofcontracts).- a relative or absolute path → compact that file.
--level=light|medium|aggressive→ override the configured level for this run only.--dry-run→ report what would change, write nothing.
- Load
token-budget-config.ymlfrom the extension directory if present, otherwise use the template defaults. The keys you care about are:compact.level,compact.preserve_sections,compact.drop_sections,compact.preserve_code_blocks,compact.preserve_id_patterns,compact.keep_full_backup.
Algorithm — apply in order, per artifact
Step 1 — Backup
If keep_full_backup is true and <artifact>.full.md does not yet exist,
copy the current artifact to <artifact>.full.md. Never overwrite an
existing backup. The backup is the source of truth for re-compaction at a
different level later.
Step 2 — Lossless strips (every level)
- Remove HTML comments left over from templates (
<!-- ... -->), except the spec-kit machine-readable markers (e.g.<!-- INSERT_STATUS_BELOW -->) if present. - Remove sections whose heading prefix-matches any entry in
compact.drop_sections. - Collapse runs of 3+ blank lines into a single blank line.
- Remove decorative ASCII separators (
---,===, repeated*or_runs) that are not Markdown horizontal rules between meaningful sections. - Strip repeated cross-reference reminders that the same artifact already states (e.g. "see spec.md FR-001" appearing in three sibling sections — keep the first occurrence per section, drop the rest).
- Strip phrase-level filler: "Note that", "It should be noted that", "As mentioned above", "For your reference", "Please be aware that", "It is important to understand that", and similar leading hedges. Keep the substantive clause that follows.
Step 3 — Medium level (default)
In addition to Step 2:
- Convert prose paragraphs that enumerate items into bullet lists when the prose contains "first ... second ... third", "as well as", or comma- separated noun clauses. Only when conversion is lossless — if in doubt, leave the prose alone.
- Collapse multi-sentence paragraphs that restate a single requirement into one sentence per requirement.
- For tables that have an "Example" or "Notes" column with prose larger than 20 words, condense to ≤ 12 words per cell.
Step 4 — Aggressive level
In addition to Steps 2–3:
- Drop sections titled "Rationale", "Alternatives Considered", "Background", "Motivation" — these are valuable for humans but the decision they justify is captured elsewhere in the artifact.
- Drop the leading framing paragraph of each top-level section if a structured list immediately follows that conveys the same information.
- Replace prose in "Research" findings with a one-line conclusion plus a bulleted evidence list.
Step 5 — Hard preservation guardrails (every level)
Never modify, paraphrase, or remove:
- Any line containing a token that matches
compact.preserve_id_patterns(FR-001, NFR-002, T015, US-003, AC-007, etc.) — keep the line verbatim. - Any heading that prefix-matches
compact.preserve_sections. - Any fenced code block when
preserve_code_blocksis true (default). - The contents of
contracts/*schema files (OpenAPI, JSON Schema, GraphQL SDL). You may strip surrounding markdown prose but the schema bytes must be identical. - The Constitution check matrix in plan.md.
- The acceptance test expectations in tasks.md.
- File path references (anything that looks like a path:
src/...,./...,/...).
If at any point you are uncertain whether a transformation is lossless, do not apply it. Compaction must never invent, summarize away, or merge distinct requirements.
Step 6 — Re-anchor headings
After stripping, ensure heading levels are still contiguous (no jump from
# to ###). Promote orphan subheadings as needed. The artifact must
still parse as a valid spec-kit document of its kind.
Step 7 — Stamp
Append a single line at the very bottom of the compacted file:
<!-- token-budget: compacted (level=<level>) on <ISO-8601-date>; original at <basename>.full.md -->This marker lets usage and re-runs detect already-compacted files and
skip no-op work.
Output
For each artifact processed, run the helper script to get character/token counts before and after, then report:
spec.md 4,820 → 2,310 tokens (-52.1%) [backup: spec.full.md]
plan.md 6,140 → 3,580 tokens (-41.7%) [backup: plan.full.md]
research.md 3,200 → 1,180 tokens (-63.1%) [backup: research.full.md]
─────────────────────────────────────────────────
total 14,160 → 7,070 tokens (-50.1%)Then end the response. Do not narrate the steps you took — the file diff is the deliverable.
Scripts
The helper script .specify/extensions/token-budget/scripts/bash/compact_helper.sh provides:
snapshot <file>— prints the current token count.backup_if_needed <file>— copies to.full.mdif no backup exists yet.summarize <before_path> <after_path>— prints the one-line report row.has_marker <file>— exit 0 if file is already compacted.stamp <file> <level>— append the compaction marker.
Use it to keep your edits auditable and the output consistent. You do the content rewriting; the script does the bookkeeping.
Re-running
If an artifact already carries the <!-- token-budget: compacted -->
marker, re-compaction works against the .full.md backup, not the
current compacted version. This prevents lossy compounding across runs.
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.

