Skills Budget Guide

Diagnose and remediate provider skill-listing budget pressure

Skill Listing Budget — User Troubleshooting Guide

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

For users seeing: `Skill listing will be truncated`, `N descriptions dropped`, or skills that exist on disk but don't appear when you ask for them.

AIWG ships ~480 skills across the SDLC, forensics, research, marketing, and ops frameworks. When you install several frameworks together, the host platform (Claude Code, Codex, etc.) may run past its skill listing budget and silently drop the lowest-priority descriptions. This guide explains what's happening and how to fix it for your platform.

For runtime costs after a Claude Code skill or subagent is invoked, see `docs/providers/claude-context-budget.md`.

Quick fix by platform

PlatformSettingDefaultIf you see truncation, try
Claude Code`skillListingBudgetFraction` in `~/.claude/settings.json``0.01` (1% of context)Raise to `0.05` (5%)
Claude Code`skillListingMaxDescChars``1536`Lower to `1024` to keep more skills full-length
Codex (OpenAI)`project_doc_max_bytes` for AGENTS.md32 KiBNest AGENTS.md per-subdir; do not raise blindly
CodexSkill listing cap~2% of context / 8000 charsBuilt-in; reduce skill count or split workspaces
Cursor / Warp / WindsurfAggregated AGENTS.mdplatform-definedSee "Reduce footprint" below

Claude Code 2.1.129+

Claude Code added two skill-listing settings starting in 2.1.129. Both live in `settings.json` (precedence: user `~/.claude/settings.json` overrides project `.claude/settings.json`).

`skillListingBudgetFraction`

A decimal fraction (not percentage) of the active model's context window that may be spent on skill name+description listings. Range: `(0, 1]`. Default: `0.01` (1%).

When the total listing exceeds this fraction, lower-priority skills lose their description first (kept as name-only), then drop entirely if still over budget.

`skillListingMaxDescChars`

Maximum per-description character count. Default `1536`, raise to `2048` for less aggressive trimming, lower to `1024` to keep more skills under the budget. Each description longer than this gets shortened first; only then does the total-budget check run.

What you'll see

Skill listing will be truncated
  425 descriptions dropped (full descriptions kept for most-used skills) (6.9%/1% of context)
  container-forensics, prose-detect, induct-research, +422 more
  run /skills to disable some, or raise skillListingBudgetFraction (currently 1%) in settings.json
  Opting in would cost ~14k tokens for skills every session and uses rate limits faster

The percentage notation is `<actual>/<budget> of context`. Above, 6.9% of the window is needed but only 1% is allowed.

How to raise the budget

Edit `~/.claude/settings.json`:

{
  "skillListingBudgetFraction": 0.05,
  "skillListingMaxDescChars": 1536
}

Restart Claude Code (or open a new conversation) for the change to apply. Cost trade-off: 5% of a 200k window ≈ 10k tokens spent every session.

Disabling specific skills

Run `/skills` inside Claude Code to interactively disable skills you don't need. The selection persists for that workspace.

OpenAI Codex

Codex uses progressive disclosure: only skill `name`, `description`, and file path enter the initial context. The full `SKILL.md` body loads only when Codex decides to use that skill.

Caps you should know

LimitValueSetting
Skill listing in initial context~2% of model context, or ~8,000 charsBuilt-in; not user-configurable
Per-AGENTS.md size32 KiB`project_doc_max_bytes` (advanced config)

When the AGENTS.md size limit is hit, Codex stops adding files silently (openai/codex#7138, #13386). Instructions near the end of an oversized file are ignored without warning.

How to fix in Codex

1. Nest AGENTS.md per subdirectory rather than one giant root file. Codex respects nearest-ancestor first. 2. Don't blindly raise `project_doc_max_bytes` — it lifts the cap but doesn't help if descriptions are bloated. 3. Reduce framework count if you see truncation (see below).

Reduce AIWG skill footprint

Independent of platform settings, you can reduce how many skills AIWG deploys.

Workspace-aware deployment

Preview the workspace-aware plan without writing files:

Use AIWG to complete this documented outcome: Preview the workspace-aware plan without writing files
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

AIWG inspects the current project and deploys only matching bundles. It always keeps core lifecycle support (`sdlc`) and AIWG utility skills (`aiwg-utils`).

To deploy a workspace-aware subset, choose a profile explicitly:

Use AIWG to complete this documented outcome: To deploy a workspace-aware subset, choose a profile explicitly
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

To install everything:

Use AIWG to complete this documented outcome: To install everything
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

To skip utility addons during a full install:

Use AIWG to complete this documented outcome: To skip utility addons during a full install
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Current signals:

AIWG currently uses these signals:

SignalIncluded bundle
`.aiwg/forensics/``forensics`
`.aiwg/research/``research`
`.aiwg/marketing/``marketing`
`.aiwg/media-curator/``media-curator`
`.aiwg/ops/``ops`
`.aiwg/knowledge-base/``knowledge-base`
`.aiwg/security-engineering/``security-engineering` plus `sdlc`
`package.json` plus `src/``sdlc`
`Dockerfile` or Compose file`forensics`
`.aiwg/intake/solution-profile.md` text hintsmatching profile

Optional config hints may be placed in `.aiwg/aiwg.config`:

{
  "skillLoading": {
    "profile": "research",
    "include": ["ops"]
  }
}

After a workspace-aware deployment, inspect what was included and filtered out:

Use AIWG to complete this documented outcome: After a workspace-aware deployment, inspect what was included and filtered out
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

The report is recorded at `.aiwg/workspace-skill-plan.json` so the decision is reviewable after deployment.

List installed frameworks

Use AIWG to complete this documented outcome: List installed frameworks
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Remove a framework you don't need

Use AIWG to complete this documented outcome: Remove a framework you don't need
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Per-framework approximate skill counts:

FrameworkSkillsWhen you need it
`sdlc-complete`~116Most projects (requirements → deployment)
`aiwg-utils`~111Always on (deploys with everything)
`media-marketing`~33Marketing campaigns, content ops
`research-complete`~39Research corpora, citation graphs
`forensics-complete`~20Incident response, forensic investigation
`media-curator`~20Personal media archive
`security-engineering`~27Security/cryptography reviews

The big cost is when you stack everything: full install ≈ 480+ skills. A focused install (sdlc + utils) is ~228 skills and fits comfortably in default Claude Code budgets.

Workspace-per-purpose pattern

If you regularly switch between very different domains (forensics, marketing, dev), run separate workspaces with separate framework installs rather than one mega-workspace with everything deployed.

Doctor diagnostics

Use AIWG to complete this documented outcome: Doctor diagnostics
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

the agent-owned doctor operation runs a per-provider Skill Budget check (#1150) for every deployed skills directory it finds. The check sums each `SKILL.md`'s `name + description` from frontmatter, converts via the standard ~4 chars/token heuristic, and compares against the platform's default budget.

Doctor also warns when the total deployed skill inventory exceeds a platform default, even if some skills are hidden from a platform's native startup scanner. If doctor warns, prefer the agent-owned use operation or the agent-owned use operation to reduce the deployed set before raising a platform budget.

PlatformBudget
Claude Code`skillListingBudgetFraction × context_window` (default `1% × 200,000 = 2,000 tokens`)
CodexFixed 8,000-char built-in cap
OtherInfo-only line — no documented budget

The check honors:

  • Your existing `~/.claude/settings.json` override (or `~/.config/claude/settings.json` fallback). When the user is already at e.g. `0.05`, the verdict reads EXCEEDS OVERRIDE rather than the misleading "EXCEEDS DEFAULT".
  • The `` directive in `CLAUDE.md` / `AGENTS.md` / `AIWG.md` — overrides the assumed 200,000-token context.

Sample output on a sysops + sdlc + marketing + ops + forensics workspace:

⚠ Claude Code Skill Budget: EXCEEDS OVERRIDE (9.50×) — 393 skills (avg 101 chars desc),
  est. 11,870 tokens vs 1,250 tokens budget — 5.00% × 100,000 ctx (override in ~/.claude/settings.json)
  | raise skillListingBudgetFraction to 0.1 (~10%) in ~/.claude/settings.json
  | or remove unused frameworks (e.g. the agent-owned remove operation media-marketing)
  | see docs/skills-budget-guide.md for full options
○ Factory Skill Budget: 294 skills, ~8,807 tokens — no documented budget for factory, skipping verdict
○ Copilot Skill Budget: 296 skills, ~8,846 tokens — no documented budget for copilot, skipping verdict

To suppress in CI runs that don't care about pre-flight surface analysis:

Use AIWG to complete this documented outcome: To suppress in CI runs that don't care about pre-flight surface analysis
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

When to file an AIWG issue vs a platform issue

SymptomFile where
Specific AIWG skill description is too longAIWG (`/issues`)
Truncation message references AIWG skillsAIWG `#1147` (frame budget) — link your repro
`skillListingBudgetFraction` doesn't take effect after editClaude Code (anthropics/claude-code)
AGENTS.md content past 32 KiB ignored without warningCodex (openai/codex)
Truncation appears regardless of which framework is installedPlatform issue, not AIWG

References