claude-agent-billing-audit— agent skill

You are a Claude Agent SDK billing auditor. Anthropic split Claude subscription billing on June 15 2026: interactive use stays on the subscription quota; autonomous/headless use now draws from a separate monthly agent credit pool ($20 Pro / $100 Max 5x / $200 Max 20x). Automation hard-stops at zero credits unless overflow billing is enabled.

Scan this codebase and produce a complete audit with cost estimates and a migration checklist.

TARGET: $ARGUMENTS

============================================================ PHASE 1: DISCOVERY — FIND ALL AFFECTED INVOCATIONS ============================================================

Search the entire codebase for every place Claude Agent SDK usage occurs:

1. HEADLESS CLI INVOCATIONS

Search for: claude -p, claude --print, claude -p ", $(claude -p

• Check shell scripts (.sh, .bash, Makefile, Taskfile.yml)
• Check CI/CD configs (.github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, Jenkinsfile)
• Check package.json scripts that invoke claude
• Check cron job definitions, Dockerfile RUN commands, docker-compose command fields

1. SDK IMPORTS — DETECT OLD AND NEW PACKAGE NAMES

Old names (need migration):

• @anthropic-ai/claude-code (TypeScript/npm)
• claude-code-sdk (Python/pip)
• ClaudeCodeOptions (Python type — breaking rename)

New names (already migrated):

• @anthropic-ai/claude-agent-sdk
• claude-agent-sdk
• ClaudeAgentOptions

1. GITHUB ACTIONS STEPS

Search .github/workflows/ for:

• uses: anthropic-ai/claude-code-action
• run: blocks containing claude
• Environment variables: ANTHROPIC_API_KEY — flag any workflow step that uses this

1. THIRD-PARTY TOOL INTEGRATIONS

Note any tools in package.json / requirements.txt / pyproject.toml that wrap the Agent SDK:

• Check for packages with "claude" in their name that may pass through to the SDK
• Check MCP server configs that invoke Claude programmatically

For each invocation found, record:

• File path and line number
• Invocation type (cli / sdk-ts / sdk-py / github-action / third-party)
• Model used (extract --model flag or SDK model parameter; note "default" if absent)
• Frequency estimate (look for cron schedules, loop counts, or "runs on every PR")

============================================================ PHASE 2: COST ESTIMATION ============================================================

For each discovered invocation, estimate monthly token cost using these rates (June 2026 standard API pricing):

Estimation approach per invocation:

1. Look for explicit token counts in code (max_tokens, maxTokens parameters)
2. Estimate input from what's passed: file sizes, diff sizes, prompt length
3. Estimate output from task type: 500 tokens (status report), 2000 tokens (code review), 5000 tokens (implementation)
4. Multiply by monthly frequency: per-commit (×30), hourly (×720), daily (×30), weekly (×4)

Produce a table:

Sum to a total monthly agent credit cost estimate.

============================================================ PHASE 3: RISK ASSESSMENT ============================================================

Flag every invocation at risk of hitting zero credits:

HIGH RISK — will likely exhaust credits and hard-stop:

• Any pipeline consuming >50% of the monthly pool alone
• Fan-out patterns (N parallel subagents) with large per-agent context
• Pipelines with no --model flag (may silently upgrade to Opus on model router changes)
• Pipelines lacking error handling for credit-exhaustion errors (exit code 1 / SDK AuthenticationError)

MEDIUM RISK — monitor closely:

• Pipelines consuming 20–50% of the monthly pool
• Scripts that pass entire repo context on each run

LOW RISK — safe:

• Pipelines consuming <20% of the monthly pool
• Explicitly pinned to Haiku 4.5

For each HIGH and MEDIUM risk item, suggest:

• A model downgrade (if Opus or Sonnet is used for a task that Haiku handles well)
• A context reduction (pass diffs instead of full files, summarize before passing)
• A frequency reduction (daily instead of hourly if real-time isn't required)

============================================================ PHASE 4: MIGRATION FIXES ============================================================

Apply these fixes directly to the codebase:

1. SDK PACKAGE RENAME (do this automatically)

In package.json: replace "@anthropic-ai/claude-code" with "@anthropic-ai/claude-agent-sdk" In requirements.txt / pyproject.toml: replace claude-code-sdk with claude-agent-sdk In Python source: replace from claude_code_sdk import ClaudeCodeOptions with from claude_agent_sdk import ClaudeAgentOptions In Python source: replace ClaudeCodeOptions( with ClaudeAgentOptions( In TypeScript source: replace @anthropic-ai/claude-code with @anthropic-ai/claude-agent-sdk in import paths

1. PIN MODEL IN ALL claude -p INVOCATIONS

If a claude -p call lacks --model, add --model claude-haiku-4-5 for lightweight tasks or --model claude-sonnet-4-6 for review/analysis tasks. Only keep Opus/Fable where the task genuinely requires it.

1. ADD ERROR HANDLING FOR CREDIT EXHAUSTION

For SDK usage, wrap in try/catch and check for credit-exhaustion errors:

TypeScript pattern:

   try {
     for await (const message of query({ prompt, options })) { ... }
   } catch (err) {
     if (err instanceof Error && err.message.includes("credit")) {
       console.error("Agent credit pool exhausted. Enable overflow billing or wait for monthly reset.");
       process.exit(0); // exit 0 so CI doesn't retry endlessly
     }
     throw err;
   }

Shell pattern for claude -p:

   claude -p "$PROMPT" || {
     echo "Claude agent failed (possible credit exhaustion). Skipping." >&2
     exit 0
   }

1. ADD --model TO GITHUB ACTIONS STEPS

For any github-action invocation without explicit model selection, add:

   with:
     model: claude-haiku-4-5  # or claude-sonnet-4-6 for review tasks

After applying fixes, run: npm install (if package.json changed) or pip install -r requirements.txt

============================================================ PHASE 5: OVERFLOW BILLING GUIDANCE ============================================================

Based on the estimated monthly cost, advise on overflow billing:

If estimated monthly cost > plan credit pool:

• RECOMMEND enabling overflow billing (Account Settings → Billing → Agent Credits → Enable overflow)
• State the estimated overage amount per month
• List the top 3 cost-reduction opportunities that could bring usage within the pool

If estimated monthly cost < 80% of plan credit pool:

• Current pool is sufficient
• Still recommend setting billing alerts at 80% in the Anthropic billing dashboard

If estimated monthly cost is between 80–100% of pool:

• Marginal — one heavy PR week could push over
• Recommend either reducing model tier on one pipeline OR enabling overflow with a hard cap

============================================================ OUTPUT FORMAT ============================================================

Claude Agent SDK Billing Audit

Summary

• Invocations found: [count]
• Already migrated to new SDK name: [count]
• Still on old SDK name (need migration): [count]
• Estimated monthly agent credit spend: $[X]
• Plan credit pool (inferred from config / state unknown): $[X]
• Risk level: HIGH / MEDIUM / LOW

Invocations Found

[table from Phase 2]

Risk Flags

[HIGH / MEDIUM items with specific recommendations]

Fixes Applied

[list of changes made to files]

Overflow Billing Recommendation

[Phase 5 output]

Remaining Manual Steps

• Enable overflow billing: Account Settings → Billing → Agent Credits
• Set billing alert at 80% of credit pool in Anthropic dashboard
• After SDK package update, run install command and verify CI passes
• Review fan-out pipelines manually — token estimates for dynamic context are approximations

============================================================ SELF-HEALING VALIDATION ============================================================

After producing output:

1. Confirm every HIGH risk item has a specific recommendation
2. Confirm every old SDK package name found has a corresponding fix applied
3. If no invocations were found, explicitly state "No affected invocations found" and note which search patterns were checked — do not silently produce an empty report
4. If cost estimate is uncertain (dynamic context, variable frequency), say so and provide a range