New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Context Budget Check

by poshan0126 in poshan0126/dotclaude

Estimates the per-turn token cost of a project's .claude folder and CLAUDE.md, split into always-loaded, path-scoped and invoked-only files, and flags what runs over budget.

MITAuto-check passedAgent Workflows

Install Context Budget Check

skills CLI
$ npx skills add poshan0126/dotclaude --skill context-budget -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install poshan0126/dotclaude context-budget --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/poshan0126/dotclaude.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/context-budget .claude/skills/context-budget && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
context-budget
GitHub stars
870
Token cost
~1.4k tokens
SKILL.md length
434 words
Files
1
Skills in repo
14
Repo updated
First seen
Licence
MIT

At a glance

Estimates the per-turn token cost of a project's .claude folder and CLAUDE.md, split into always-loaded, path-scoped and invoked-only files, and flags what runs over budget.

  • Works in 4 steps: Discover loadable files → Classify rules by frontmatter → Count tokens per file → …
  • Finding out which config files cost tokens on every turn
  • SKILL.md covers Step 1: Discover loadable files, Step 2: Classify rules by…, Step 3: Count tokens per file and Step 4: Aggregate and report, plus 2 more sections
  • Calls jq and curl; reaches api.anthropic.com; needs ANTHROPIC_API_KEY

What it does

The agent finds CLAUDE.md, the rules, each skill's SKILL.md and the agent files, skipping folder README files that are never loaded. Rules are sorted by their frontmatter: a rule with a `paths` list is path-scoped and loads only near matching files, while a rule without one is always loaded, as is CLAUDE.md. Skills are invoked-only and cost nothing per turn, and agent files run in their own isolated context.

Tokens are counted with a characters-divided-by-four heuristic that the report labels as approximate, or with exact tokenizer counts when `--api` is passed and `ANTHROPIC_API_KEY` is set, falling back to the heuristic otherwise. The report totals each category, names the top three always-loaded contributors, gives a verdict against budget guidance, and ends with the single trim that would save the most tokens if a class is over budget.

When your agent uses it

  • Finding out which config files cost tokens on every turn
  • Deciding what to trim from CLAUDE.md or always-loaded rules
  • Getting exact token counts for a project's agent configuration

Example prompts

  • “Check the context budget of this project and tell me what to trim first.”
  • “Run the context budget with --api so the counts are exact.”
  • “Which rules in .claude/rules load on every turn and which are path-scoped?”

Requirements

  • A project with a .claude folder or a CLAUDE.md
  • ANTHROPIC_API_KEY, only for exact counts with --api

Workflow steps

4 steps, taken from the step headings in SKILL.md.

  1. Discover loadable files
  2. Classify rules by frontmatter
  3. Count tokens per file
  4. Aggregate and report

What it can do on your machine

Read from SKILL.md and the folder at commit 94b84b9. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • jq
    • curl

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Hosts in commands or code, which the agent is likely to contact:

    • api.anthropic.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • ANTHROPIC_API_KEY

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Context Budget Check loads about 1.4k tokens when it runs. Until then it costs about 50 tokens; SKILL.md has 434 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~50
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from poshan0126/dotclaude at commit 94b84b9, republished under its MIT licence (© poshan0126). 434 words, ~1,350 tokens.

Download SKILL.mdSave it as .claude/skills/context-budget/SKILL.md (or your agent's skills folder).
name
context-budget
description
Estimate per-turn token cost of `.claude/` and `CLAUDE.md` — always-loaded vs path-scoped vs invoked-only, top contributors, over-budget flags. Add `--api` for exact tokenizer counts.
argument-hint
[--api]
disable-model-invocation
true

Estimate the token cost of this project's .claude/ configuration and CLAUDE.md so the user can see exactly which files load every turn versus only when triggered.

Step 1: Discover loadable files

From the project root:

bash
ls CLAUDE.md 2>/dev/null
find .claude/rules -name '*.md' -type f 2>/dev/null
find .claude/skills -name 'SKILL.md' -type f 2>/dev/null
find .claude/agents -name '*.md' -type f 2>/dev/null
[ -f .claude/CLAUDE.md ] && echo "WARN: .claude/CLAUDE.md exists. CLAUDE.md belongs at the project root."

Skip any file under .claude/agents/README.md, .claude/rules/README.md, etc. Those are folder descriptions, not loaded by Claude Code at runtime.

Step 2: Classify rules by frontmatter

For every .md file in .claude/rules/, read the YAML frontmatter (the block between the first two --- lines).

Frontmatter containsClassificationPer-turn cost
paths: [...]Path-scopedLoaded only when working near matched files
No paths: (or no frontmatter)Always-loadedEvery turn

Other categories:

  • ./CLAUDE.md -> always-loaded (by definition).
  • .claude/skills/<name>/SKILL.md -> invoked-only (zero per-turn cost; only loads when the user runs /skill-name or, if disable-model-invocation is unset, when Claude auto-triggers it).
  • .claude/agents/<name>.md -> invoked-only and runs in isolated context (per-invocation cost in its own session, not per-turn cost in the main thread).

Step 3: Count tokens per file

Default mode (no API call): chars-based heuristic. Anthropic documents that English text averages roughly 4 characters per token. Compute:

bash
chars=$(wc -c < "$FILE" | tr -d ' ')
tokens=$((chars / 4))

Note this in the report so the user knows the count is approximate (within roughly 10 to 15 percent of the exact count for typical config text).

--api mode: if $ARGUMENTS contains --api:

bash
if [ -z "$ANTHROPIC_API_KEY" ]; then
  echo "ERROR: --api requested but ANTHROPIC_API_KEY is not set. Falling back to heuristic."
else
  CONTENT=$(jq -Rs . < "$FILE")
  tokens=$(curl -s https://api.anthropic.com/v1/messages/count_tokens \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d "{\"model\":\"claude-sonnet-4-6\",\"messages\":[{\"role\":\"user\",\"content\":$CONTENT}]}" \
    | jq -r '.input_tokens')
fi

The endpoint returns Anthropic's exact tokenizer count. That is the factual number Claude Code itself would see when loading the file.

Step 4: Aggregate and report

Sum tokens within each category, identify the top 3 contributors among always-loaded files, then print:

Context budget for <project root>
Method: heuristic (chars/4)        [or: Anthropic count_tokens API]

Always-loaded (every turn):                 ~N tokens
  CLAUDE.md                                  ~N tokens
  .claude/rules/code-quality.md  (always)      ~N tokens
  .claude/rules/testing.md       (always)      ~N tokens

Path-scoped (loaded near matched files):    ~N tokens (max, if every glob matches)
  .claude/rules/security.md      (paths: src/api/**, ...)  ~N tokens
  .claude/rules/frontend.md      (paths: **/*.tsx, ...)    ~N tokens

Invoked-only (zero per-turn cost):
  Cumulative size if every skill and agent loaded once: ~N tokens
  .claude/skills/<name>/SKILL.md   ~N tokens
  .claude/agents/<name>.md         ~N tokens

Top 3 always-loaded contributors:
  1. <file>   ~N tokens
  2. <file>   ~N tokens
  3. <file>   ~N tokens

Verdict: PASS / NEAR LIMIT / OVER BUDGET

End the report with the highest-leverage trim recommendation if any class is over budget.

Show full SKILL.md (176 more words)Show less

Budget guidance (used to compute the verdict)

ClassTargetHard capAction when over
CLAUDE.md<25 non-blank lines<50 non-blank linesTrim per Phase 4 of /setupdotclaude.
Each always-loaded rule<30 lines, ~250 tokn/aPush content to a path-scoped rule or into an agent.
Total always-loaded<1000 tokens<1500 tokensIdentify the single biggest contributor and trim it.

Caveats to mention in the report

  • The heuristic is approximate. Re-run with --api (requires $ANTHROPIC_API_KEY) for the exact count from Anthropic's tokenizer.
  • Claude Code does not expose live context window state to skills, so this report estimates "what would load each turn for this configuration", not "what's currently in your session window".
  • Agents run in isolated context. Their prompt cost is per-invocation in their own session, not per-turn in your main thread.
  • Skills cost zero until invoked. Most have disable-model-invocation: true, meaning they only fire on /name.
  • Path-scoped rules cost zero unless the conversation touches files matching their globs.
  • Hooks contribute to context only if they print to stdout. dotclaude's hooks are silent on success by design.

© poshan0126, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/context-budget of poshan0126/dotclaude.

Open the folder on GitHubat commit 94b84b9

Compare with similar skills

Context Budget Check next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Context Budget Check compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Context Budget Check this skillposhan0126/dotclaude870—~1.4kAutomated safety check: PassMIT
Caveman Learn Token FixesJuliusBrussee/caveman111k—~2.8kAutomated safety check: PassApache-2.0
Claude Code Cost Optimizermergisi/awesome-openclaw-agents4k—~1.1kAutomated safety check: PassMIT
Caveman Memory File CompressorJuliusBrussee/caveman-code942—~1.2kAutomated safety check: PassMIT
Claude Code Masteryborghei/Claude-Skills891—~1.9kAutomated safety check: PassMIT
Context Mode Output Sandboxmksglu/context-mode26k—~4.1kAutomated safety check: PassCustom licence

Similar skills

  • Caveman Learn Token Fixes

    JuliusBrussee/caveman

    Acts on a Caveman learn report: reviews ranked token sinks, applies cost-lowering edits one at a time with your consent, and reports what each fix returned.

    111k GitHub stars~2.8k tokensUpdated yesterday
    Agent WorkflowsAuto-check passed

  • Claude Code Cost Optimizer

    mergisi/awesome-openclaw-agents

    Audits a project's Claude Code setup for common token-cost leaks and returns a prioritized fix list, using only static inspection of files and settings.

    4k GitHub stars~1.1k tokensUpdated 13 days ago
    Agent WorkflowsAuto-check passed

  • Caveman Memory File Compressor

    JuliusBrussee/caveman-code

    Rewrites a memory file such as CLAUDE.md or a todo list in terse caveman-style text to cut input tokens, saving a readable backup outside the project tree.

    942 GitHub stars~1.2k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check passed

  • Claude Code Mastery

    borghei/Claude-Skills

    A skill your agent uses when the user asks to "optimize CLAUDE.md", "create a new skill", "write a custom agent", "configure hooks", "manage context window", "set up MCP servers", "scaffold a skill…

    891 GitHub stars~1.9k tokensUpdated 2 days ago
    Agent WorkflowsAuto-check passed

  • Context Mode Output Sandbox

    mksglu/context-mode

    Routes large command, file, API and browser output through context-mode tools so only the needed result enters the agent's context, instead of dumping it via Bash.

    26k GitHub stars~4.1k tokensUpdated today
    Agent WorkflowsAuto-check passed

  • Context Mode for Antigravity CLI

    mksglu/context-mode

    Routing rules for using context-mode MCP tools in Antigravity CLI: sandboxed code runs, file analysis, indexed search and web fetches that keep large output out of the conversation.

    26k GitHub stars~850 tokensUpdated today
    Agent WorkflowsAuto-check passed

More from poshan0126/dotclaude

All 14 skills in this repo

  • Session Catchup and Handoff

    poshan0126/dotclaude

    Rebuilds working context after /clear by reading a handoff note and the branch's git state, or writes that handoff note before a session ends.

    870 GitHub stars~811 tokensUpdated 1 mo ago
    Auto-check passed

  • Codebase Onboarding Tour

    poshan0126/dotclaude

    Builds a quick mental model of an unfamiliar codebase by dispatching read-only Explore subagents and merging their findings into one brief.

    870 GitHub stars~858 tokensUpdated 1 mo ago
    Auto-check passed

  • Parallel Specialist PR Review

    poshan0126/dotclaude

    Reviews a pull request, staged changes or a file by sending the diff to specialist reviewer agents in parallel, then merges their findings into one compact report.

    870 GitHub stars~1.7k tokensUpdated 1 mo ago
    Auto-check passed

  • dotclaude Project Setup

    poshan0126/dotclaude

    Scans a codebase, interviews you, and installs only the justified Claude Code rules, hooks, agents and skills, tailored to the project's stack.

    870 GitHub stars~3.6k tokensUpdated 1 mo ago
    Auto-check passed

  • Ship Changes

    poshan0126/dotclaude

    Walks through commit, push and pull request creation for the current changes, asking you to confirm the files, message, push and PR text at each step.

    870 GitHub stars~953 tokensUpdated 1 mo ago
    Auto-check: notes

  • Interview-Driven Spec Writer

    poshan0126/dotclaude

    Interviews you about scope, behavior, edge cases and verification, then writes a self-contained SPEC.md that a fresh session can implement without this conversation.

    870 GitHub stars~804 tokensUpdated 1 mo ago
    Auto-check passed

Categories

Questions about Context Budget Check

What does Context Budget Check do?

Estimates the per-turn token cost of a project's .claude folder and CLAUDE.md, split into always-loaded, path-scoped and invoked-only files, and flags what runs over budget. md and the agent files, skipping folder README files that are never loaded.md.

When should I use Context Budget Check?

Context Budget Check fits situations like: finding out which config files cost tokens on every turn; deciding what to trim from CLAUDE.md or always-loaded rules; getting exact token counts for a project's agent configuration.

How do I install Context Budget Check in Claude Code?

Run `npx skills add poshan0126/dotclaude --skill context-budget -a claude-code`. Or copy the skill folder (skills/context-budget in poshan0126/dotclaude) into .claude/skills/context-budget in your project. Claude Code loads it when a task matches its description.

How do I install Context Budget Check in Codex?

Run `npx skills add poshan0126/dotclaude --skill context-budget -a codex`. Or copy the skill folder (skills/context-budget in poshan0126/dotclaude) into .agents/skills/context-budget in your project. Codex loads it when a task matches its description.

Can I use Context Budget Check in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add poshan0126/dotclaude --skill context-budget -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/context-budget, .gemini/skills/context-budget, .github/skills/context-budget and .opencode/skills/context-budget in your project.

What does Context Budget Check need to run?

Going by SKILL.md and its folder, Context Budget Check needs the command-line tools its instructions call (jq and curl) and credentials named ANTHROPIC_API_KEY. Our summary lists: A project with a .claude folder or a CLAUDE.md; ANTHROPIC_API_KEY, only for exact counts with --api.

Does Context Budget Check access the network?

SKILL.md names 1 domain. In commands or code: api.anthropic.com; the agent is likely to contact it when it follows the instructions. This is read from the text; nothing was executed.

Is Context Budget Check safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Context Budget Check use?

Context Budget Check is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Context Budget Check use?

About 1.4k tokens (SKILL.md is roughly 5.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Context Budget Check?

Skills that share tags, products or a category with Context Budget Check: Caveman Learn Token Fixes (JuliusBrussee/caveman, 111k stars), Claude Code Cost Optimizer (mergisi/awesome-openclaw-agents, 4k stars), Caveman Memory File Compressor (JuliusBrussee/caveman-code, 942 stars) and Claude Code Mastery (borghei/Claude-Skills, 891 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Context Budget Check?

poshan0126 (a GitHub user) maintains it in poshan0126/dotclaude, which has 870 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on August 27, 2026.

Source: poshan0126/dotclaude on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.