agentleFS
haruharu/redmine_ai_helper/.claude/skills/speckit-token-budget-compact/SKILL.md

speckit-token-budget-compact

Skill107 starsChanged 9 months agoMITView on GitHub

Compact one or more Spec-Driven Development artifacts in place to reduce

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
  1. Very specific:

    If keep_full_backup is true and <artifact>.full.md does not yet exist, copy the current artifact to <artifact>.full.md.

    line 54
  2. Very specific:

    Remove HTML comments left over from templates (<!-- ...

    line 60
  3. Very specific:

    Remove sections whose heading prefix-matches any entry in compact.drop_sections.

    line 63
  4. Very specific:

    Remove decorative ASCII separators (---, ===, repeated * or _ runs) that are not Markdown horizontal rules between meaningful sections.

    line 66
  5. Distinctive:

    If at any point you are uncertain whether a transformation is lossless, do

    line 111
  6. Very specific:

    After stripping, ensure heading levels are still contiguous (no jump from # to ###).

    line 116
  7. Distinctive:

    Use it to keep your edits auditable and the output consistent.

    line 155
  8. Very specific:

    If an artifact already carries the <!-- token-budget: compacted --> marker, re-compaction works against the .full.md backup, not the …

    line 160

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. 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.
  2. 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 of contracts).
    • 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.
  3. Load token-budget-config.yml from 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_blocks is 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.md if 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.