mujin-skillbudget 0.1.0

Budget the always-loaded token cost of your AI agent context (CLAUDE.md, skill descriptions, Cursor rules) and fail CI when it bloats.

skillbudget

Your agent's always-loaded context has a token budget. Spend it wisely — and fail CI when you blow it.

Every turn, before the user says a word, your coding agent loads CLAUDE.md, every skill's description, and your always-apply rules into its context window. Teams quietly let this grow to tens of thousands of tokens — one enterprise setup burned 143K of 200K tokens (72%) on definitions alone. A bloated CLAUDE.md (>5K tokens) measurably shrinks the room left for actual work.

skillbudget measures that always-on surface and gives you a CI gate.

pipx install mujin-skillbudget

skillbudget scan --budget 8000     # exit 1 if always-on context exceeds the budget

always-on context budget: 8,000 tokens   [estimated (~4 chars/token — pip install tiktoken for exact)]

    1,853  CLAUDE.md
       16  skill deploy · frontmatter
       13  skill test · frontmatter
  -------
    1,882  TOTAL always-on  (1,882/8,000  ok)

  on-invocation (not counted — loads only when triggered):
      500  skill deploy · body

  suggestions:
  - CLAUDE.md is 1,853 tokens — move rarely-needed guidance into on-demand skills.

What counts (and what doesn't)

The key insight most "context size" tools miss: skill bodies are lazy. A skill only puts its name + description into context until it's actually invoked. So skillbudget charges the always-on budget for:

• CLAUDE.md (or AGENTS.md) — loaded every turn,
• each skill's frontmatter (.claude/skills/*/SKILL.md description),
• Cursor rules with alwaysApply: true.

…and reports skill bodies and glob-scoped rules separately as on-invocation cost — real, but only when triggered. Budget the thing that's always there.

Exact counts

By default it estimates (~4 chars/token, zero dependencies, fully offline). For exact cl100k_base counts, pip install mujin-skillbudget[accurate] (pulls tiktoken) — it's auto-detected.

CI gate

# .github/workflows/context-budget.yml
jobs:
  skillbudget:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.11" }
      - run: pipx install mujin-skillbudget
      - run: skillbudget scan --budget 8000   # fails the build if context bloats

--json for machine output, --no-fail to report without gating.

Part of a set

• agentsync — keep CLAUDE.md / AGENTS.md / Cursor / Copilot in sync.
• agentaudit — audit skills / MCP servers / plugins for security & quality.

Sync your config → budget its size → audit it for risk. Same files, same CI.

---

Built by Mujin Labs — tooling for the autonomous-agent era. MIT.