skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/ai-engineering/skills/subagent-design/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "subagent-design",
+  "version": "0.1.2",
+  "description": "Decompose a task into an orchestrator and subagents — one-mission role cards with typed output contracts, a topology (pipeline / parallel / judge panel) chosen with a reason, context-isolation rationale, and a verification stage that is never a generator. Use when the user wants to fan work out across multiple agents, design a multi-agent workflow or orchestration, or asks \"should this be one agent or several\".",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["agent-budget", "agent-loop-design", "council-review", "devils-advocate", "feature-implement-loop"],
+  "tags": ["subagents", "orchestration", "multi-agent", "fan-out", "agentic", "role-cards"],
+  "model": { "tier": "standard", "rationale": "Design synthesis against a fixed topology catalog and role-card template. The fan-out-or-refuse judgment is bounded by the three-reasons rule; escalate via ambiguous-input on genuinely novel workflow shapes." }
+}

skilldrop_cli/data/packs/ai-engineering/skills/subagent-design/templates/orchestration-plan.md

@@ -0,0 +1,47 @@
+# Orchestration plan: {task}
+
+> Fan-out justification: {context separation | independence | role conflict} — {one line why}. If none applies, this document should instead say: use one agent.
+
+## Role cards
+
+### {agent-name}
+- **Mission:** {one sentence, one job, no "and"}
+- **Inputs:** {exactly what it receives}
+- **Denied (isolation):** {what it must not see, and why}
+- **Output contract:** `{ field: type, field: type }` — schema, not prose
+- **Tools/permissions:** {least privilege}
+- **On failure:** {structured BLOCKED/empty return — never improvisation}
+- **Tier:** {light | standard | heavy} — {why this tier suffices}
+
+<!-- one card per agent role (use ×N in the name for a mission repeated per item), and always include a card for the orchestrator itself -->
+
+## Topology
+
+**Shape:** {pipeline | parallel+barrier | judge panel} — **because** {the named dependency or independence requirement}.
+{If barrier: the cross-item dependency that earns it. If judge panel: the vote rule.}
+**Depth:** one level. {Justification here if any agent spawns agents.}
+
+```mermaid
+flowchart LR
+    O[orchestrator] --> A["{agent}"]
+    O --> B["{agent}"]
+    A --> V{verify}
+    B --> V
+    V -->|pass| OUT["{artifact}"]
+    V -->|refuted| F[failure route]
+```
+
+## Aggregation & verification
+
+- **Aggregation:** {code-shaped merge — dedup key, schema union}; contract-invalid output → failure route, never the merge
+- **Verification:** {adversarial verifier — persona/prompt, independent of all generators}; verdict gates the result
+- **Vote rule:** {panels: e.g. finding survives unless 2 of 3 refute · single verifier: "ships unless refuted"}
+
+## Budget line
+
+Fleet cap per run: {tokens/currency} `[source: agent-budget spec | assumption]` · Worker tiers as carded above · On cap: {stop and escalate — see the loop spec}
+
+## Hand-offs
+
+- Loop wrapping this fan-out (caps, gates, exits) → `agent-loop-design`
+- Full spend model → `agent-budget`

skilldrop_cli/data/packs/api-builder/pack.json

@@ -0,0 +1,48 @@
+{
+  "description": "Skills for teams building on the Anthropic API — prompt caching, token budgeting, eval generation for skills, and tool-use schema writing.",
+  "display_name": "API builder",
+  "keywords": ["anthropic", "prompt-caching", "tokens", "tool-use", "evals"],
+  "links": {
+    "documentation": "https://sananthanarayan.github.io/skilldrop/packs/api-builder/"
+  },
+  "maintainers": [
+    {
+      "name": "sananthanarayan"
+    }
+  ],
+  "first-value": {
+    "audience-posture": "technical",
+    "prerequisites": ["A system prompt and a typical request from your Claude API integration"],
+    "starter-task": "Find where prompt caching will cut your input costs",
+    "starter-prompt": "Here is our system prompt and a typical request: <paste them>. Where should the cache_control breakpoints go, and what hit rate should we expect?",
+    "verification": "prompt-caching-advisor marks where each cache_control checkpoint goes and estimates the cache hit rate.",
+    "recovery": "If prompt-caching-advisor does not activate, ask for it by name and check that its folder exists in your skills folder (`~/.claude/skills/` by default)."
+  },
+  "journey": {
+    "when": "You are building or tuning a Claude API integration and want its tools defined properly and its token costs under control.",
+    "you_bring": [
+      "the functions your agent should call: name, purpose and parameters",
+      "your system prompt and a typical request",
+      "a description of the workflow: turns, tool results, output length"
+    ],
+    "time": "30–60 minutes",
+    "steps": [
+      {
+        "skill": "tool-use-schema-writer",
+        "you_do": "Describe each function the model should call.",
+        "you_get": "A tool_use JSON schema per function with types, required fields and parameter descriptions, plus a Python client.messages.create snippet."
+      },
+      {
+        "skill": "token-budget-estimator",
+        "you_do": "Describe the workflow or share a sample request and response.",
+        "you_get": "A per-component token table, the dominant cost driver, and max_tokens and other budget controls per component."
+      },
+      {
+        "skill": "prompt-caching-advisor",
+        "you_do": "Paste the system prompt and a typical request.",
+        "you_get": "Each block classed as static, quasi-static or dynamic, where each cache_control breakpoint goes with code, and an expected cache hit rate."
+      }
+    ],
+    "you_end_with": "Tool schemas ready to wire in, a token budget with its main cost driver named, and a caching plan."
+  }
+}

skilldrop_cli/data/packs/api-builder/skills/eval-harness-generator/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: eval-harness-generator
+description: Takes a skill's SKILL.md and generates a set of eval cases — trigger queries, expected output shape, and pass/fail criteria — ready to drop into the skill's evals/ directory. Use when adding evals to a new or existing skill, verifying a skill behaves as documented, or building a regression gate before modifying a skill.
+---
+
+# eval-harness-generator
+
+Reads a SKILL.md and generates eval cases that cover the skill's happy path, edge cases, and known failure modes. The output is JSON that drops directly into the skill's `evals/cases.json` (in skilldrop, `packs/<pack>/skills/<name>/evals/`). Unlike `llm-eval-harness` (which designs eval harnesses for arbitrary LLM features), this skill specifically targets the skilldrop eval format and the patterns that skilldrop skills routinely get wrong.
+
+## How to respond
+
+### Step 1 — Read the skill
+
+Ask the user to paste the full SKILL.md. Extract:
+- What the skill takes as input
+- What the skill produces as output
+- Any explicit quality bars or anti-patterns the skill names
+- Whether the skill is a **gate** (emits a verdict from `contracts/terminals.json`) or a **generator** (produces an artifact)
+
+### Step 2 — Identify failure modes
+
+Before writing cases, enumerate the failure modes the eval set should catch:
+
+| Category | Failure mode to test |
+|---|---|
+| **Happy path** | Standard input produces the expected artifact/verdict |
+| **Minimal input** | Sparse or ambiguous input — does the skill ask clarifying questions rather than hallucinate? |
+| **Anti-pattern input** | Input that would tempt the skill to produce a common bad output (named in the SKILL.md's quality bar) |
+| **Edge input** | Boundary conditions specific to this skill (e.g., a bug report with no repro steps for bug-triage) |
+| **Gate refusal** | For gate skills: input that should produce BLOCKED or REVISE, not PROCEED |
+
+### Step 3 — Generate the eval cases
+
+Produce a JSON array with 8–12 cases. Each case:
+
+```json
+{
+  "id": "happy-path-standard",
+  "trigger": "The exact query or input that activates this case",
+  "expected_shape": [
+    "Output contains a <specific element>",
+    "Output names a specific field or section",
+    "Output avoids <anti-pattern named in quality bar>"
+  ],
+  "must_not_include": [
+    "Fabricated detail not present in the input",
+    "A verdict word from the wrong class (for gate skills)"
+  ],
+  "verdict_class": "pass",
+  "notes": "One sentence on what this case is testing and why it matters"
+}
+```
+
+For gate skills, use `verdict_class` values from `contracts/terminals.json`: `pass`, `conditional`, `revise`, `redirect`, `blocked`. For generators, use `pass` / `fail`.
+
+### Step 4 — Write an eval strategy note
+
+After the JSON array, add a brief eval strategy note (3–5 sentences) explaining:
+- Which cases cover which failure modes
+- The most important case and why
+- What a regression on which case would mean
+
+### Step 5 — Remind about placement
+
+Tell the user:
+```
+Drop this into packs/<pack>/skills/<skill-name>/evals/cases.json
+Run: python3 validate.py   # confirms the file is found
+```
+
+## Anti-patterns
+
+- **Triggers that don't test anything.** "Run the skill on this input" is not a meaningful trigger. Each trigger must be specific enough that a failing model would produce a wrong output you'd recognize.
+- **expected_shape items that can't be checked.** "Output is comprehensive" is not checkable. Name specific sections, fields, or behaviors.
+- **Missing anti-pattern cases.** The most common eval gap is no cases that test the quality bar's failure modes. If a skill says "never present a hypothesis as the cause," there must be a case where the input tempts that failure.
+
+For designing eval harnesses for general LLM features (not skilldrop skills specifically), use `llm-eval-harness` instead. Use `contribution-wizard` when creating a new skill from scratch — it calls this skill as part of the authoring flow.
+
+## Quality bar
+
+- **Triggers must be realistic.** A trigger of "run this skill" is not an eval case — it doesn't test anything specific. Each trigger should be the kind of input a real user would paste.
+- **expected_shape items must be checkable.** "Output is good" is not checkable. "Output contains a numbered repro sequence starting from a clean state" is.
+- **Cover the refusal cases.** The most common gap in skilldrop evals is missing cases for the skill's anti-patterns — the bad outputs the quality bar explicitly forbids. At least 2 of the 8–12 cases must test that the skill refuses or avoids its stated failure mode.
+- **Don't pad to 12.** Eight strong cases beat twelve weak ones. Only add cases that test a distinct failure mode not already covered.

skilldrop_cli/data/packs/api-builder/skills/eval-harness-generator/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "Write eval cases for this SKILL.md so I can put them in its evals folder",
+    "should_trigger": true
+  },
+  {
+    "query": "Generate trigger queries and pass/fail criteria for the release-notes skill",
+    "should_trigger": true
+  },
+  {
+    "query": "I'm about to edit a skill — build me a regression set from its SKILL.md first",
+    "should_trigger": true
+  },
+  {
+    "query": "Check this skill behaves as documented: draft eval cases covering its anti-patterns",
+    "should_trigger": true
+  },
+  {
+    "query": "Design an eval harness for our customer-support chatbot's RAG pipeline",
+    "should_trigger": false
+  },
+  {
+    "query": "Help me author a brand-new skilldrop skill from scratch, manifest and all",
+    "should_trigger": false
+  },
+  {
+    "query": "We need a golden set and LLM-judge rubric for our summarization feature in production",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/api-builder/skills/eval-harness-generator/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "eval-harness-generator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Here's the full SKILL.md for our new skilldrop skill `vendor-risk-screen` (a gate skill that reads a vendor security questionnaire and emits PROCEED, REVISE, or BLOCKED; its quality bar says it must never pass a vendor that has no SOC 2 report or equivalent, and must never invent certifications not in the questionnaire). [SKILL.md pasted below] Generate the eval cases for its evals/ folder.",
+      "assertions": [
+        "Produces 8 to 12 cases, each with id, trigger, expected_shape, must_not_include, verdict_class, and notes",
+        "Every trigger is a realistic input a user would paste (e.g. a specific questionnaire excerpt), not 'run this skill'",
+        "Every expected_shape item is checkable — it names a specific section, field, or behavior, not 'output is good'",
+        "At least 2 cases test the quality bar's failure modes, including a vendor with no SOC 2 report that must not get PROCEED",
+        "Because the skill is a gate, verdict_class values come from contracts/terminals.json and at least one case expects revise or blocked",
+        "At least one must_not_include entry forbids certifications or facts not present in the input questionnaire",
+        "A 3 to 5 sentence eval strategy note follows the JSON, naming the most important case and what a regression on it would mean",
+        "Ends with the placement reminder for packs/<pack>/skills/vendor-risk-screen/evals/ and running python3 validate.py"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/api-builder/skills/eval-harness-generator/evals/files/1/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: vendor-risk-screen
+description: Screen a vendor's security questionnaire and emit PROCEED, REVISE or BLOCKED with the evidence for each finding. Use when procurement asks whether a vendor can be onboarded, or when a completed security questionnaire needs a go/no-go. Do NOT use to write the questionnaire or to negotiate contract terms.
+---
+
+# vendor-risk-screen
+
+Read a completed vendor security questionnaire and return one verdict.
+
+## Workflow
+
+1. Read the questionnaire. Work only from what it states.
+2. Check the hard requirements: a SOC 2 Type II report or an equivalent (ISO 27001 certificate) dated within 12 months; encryption at rest and in transit; a named security contact; a breach-notification commitment.
+3. Emit the verdict:
+   - `PROCEED`: every hard requirement is met with evidence quoted from the questionnaire.
+   - `REVISE`: a requirement is unanswered or the evidence is out of date. List what the vendor must supply.
+   - `BLOCKED`: the vendor states it has no SOC 2 report or equivalent, or the questionnaire is missing.
+4. List each finding with the question it came from.
+
+Non-interactive runs: with no questionnaire, emit `BLOCKED: need the completed questionnaire`.
+
+## Quality bar
+
+- Never pass a vendor that has no SOC 2 report or equivalent.
+- Never invent a certification that is not in the questionnaire.
+- Every finding quotes the answer it rests on.
+
+## Anti-patterns to avoid
+
+- ❌ Treating "in progress" as holding the certification.
+- ❌ Passing on the vendor's reputation instead of its answers.

skilldrop_cli/data/packs/api-builder/skills/eval-harness-generator/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "eval-harness-generator",
+  "version": "1.0.1",
+  "description": "Takes a skill's SKILL.md and generates a set of eval cases — trigger queries, expected output shape, and pass/fail criteria — ready to drop into the skill's evals/ directory. Use when adding evals to a new or existing skill, verifying a skill behaves as documented, or building a regression gate before modifying a skill.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["llm-eval-harness", "contribution-wizard"],
+  "tags": ["claude-api", "evals", "testing", "quality", "skilldrop-meta"],
+  "model": { "tier": "standard", "rationale": "Reads a SKILL.md and synthesizes eval cases — requires understanding of the skill's intent but not heavy reasoning." }
+}

skilldrop_cli/data/packs/api-builder/skills/prompt-caching-advisor/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: prompt-caching-advisor
+description: Analyzes a prompt or conversation structure and identifies the highest-value cache breakpoints — where to insert cache_control checkpoints to minimize repeated token processing. Use when designing or optimizing a Claude API integration that uses prompt caching, when input costs are dominated by a static system prompt or few-shot block, or when a multi-turn conversation reprocesses the same context on every turn.
+---
+
+# prompt-caching-advisor
+
+Identifies where to place `cache_control` checkpoints in a Claude API prompt or conversation structure to minimize repeated token processing. The savings are real — a cache hit on a 10,000-token system prompt costs ~90% less than re-processing it — but the placement matters. Wrong breakpoints waste the minimum cacheable block size or cache dynamic content that never hits.
+
+## How to respond
+
+### Step 1 — Understand the structure
+
+Ask the user to share (or describe) their prompt structure. You need:
+- The system prompt (or a description of what's in it and roughly how long)
+- Any few-shot examples passed in messages
+- The shape of the variable user turn (what changes per request)
+- Whether this is single-turn or multi-turn
+
+If they share code, read the messages array. The cache breakpoint goes at the end of the block you want cached — a `cache_control: {"type": "ephemeral"}` on the **last content block** of a message causes everything up to and including that block to be cached.
+
+### Step 2 — Classify each block
+
+For each distinct block, classify it:
+
+| Class | Characteristics | Cache? |
+|---|---|---|
+| **Static** | Same on every request (system instructions, reference docs, few-shot examples) | Yes — put breakpoint at the end |
+| **Quasi-static** | Same for a session or user, different across users (user profile, project context) | Yes, with session-scope awareness |
+| **Dynamic** | Changes every request (current user message, real-time data, timestamps) | No — never cache |
+
+### Step 3 — Recommend breakpoints
+
+State exactly where to place each `cache_control` checkpoint. Show the code:
+
+```python
+messages = [
+    {
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": "<static few-shot examples here>",
+                "cache_control": {"type": "ephemeral"}  # breakpoint 1 — caches system + examples
+            },
+            {
+                "type": "text",
+                "text": user_query  # dynamic — no cache_control
+            }
+        ]
+    }
+]
+```
+
+For system prompts, the cache breakpoint goes on the last block of the system array.
+
+### Step 4 — Estimate cache hit rate
+
+Give a rough hit rate estimate:
+- **Near 100%**: static system prompt, fixed few-shot examples, no dynamic injection into the cached block
+- **~session %**: user-context cached per-session; hits on turn 2+, misses on first turn per user
+- **Low**: anything that embeds timestamps, UUIDs, or per-request data in the cached block
+
+### Step 5 — Warn on sub-threshold blocks
+
+Warn if a block the user wants to cache is likely under the minimum cacheable size:
+- **Haiku**: ~1,024 tokens minimum
+- **Sonnet / Opus**: ~2,048 tokens minimum
+
+A block under the minimum is processed as normal — no error, just no cache savings. Calculate roughly: 1 token ≈ 4 characters of English prose. A 2,000-character system prompt (~500 tokens) won't benefit on Sonnet/Opus.
+
+### Step 6 — Output format
+
+Produce:
+1. **Annotated structure** — show the messages array with `cache_control` placements marked and commented
+2. **Cache strategy summary** — one paragraph: what is cached, why, expected hit rate, and the dominant cost driver before and after
+
+## Anti-patterns
+
+- **Caching dynamic content.** If a user query, timestamp, or per-request database result is inside a cached block, every request is a cache miss — the structure defeats itself. Identify and flag before recommending.
+- **Recommending a cache on a block under the minimum size.** A 300-token block doesn't cache on Sonnet/Opus. The API doesn't error — it just processes normally. Always check size before recommending.
+- **Recommending four or more breakpoints.** More than three breakpoints on a single request is almost always a sign the prompt structure should be simplified, not patched with caches.
+
+Use `token-budget-estimator` after this skill if the user also wants to size the token budget across components.
+
+## Quality bar
+
+- **Never cache dynamic content.** A user query, a timestamp, a database result retrieved per-request — these must not appear in a cached block. If the user's structure embeds dynamic content in an otherwise static block, flag it before recommending the cache.
+- **One breakpoint per logical boundary.** A system prompt with three sections (instructions, reference docs, examples) can have up to three breakpoints. More than four breakpoints on a single request is a signal the structure needs rethinking.
+- **The last block caches everything before it.** This is the most common misunderstanding — the cache breakpoint is not a marker for just that block, it's a marker for the entire prefix up to that point.

skilldrop_cli/data/packs/api-builder/skills/prompt-caching-advisor/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "Where should I put cache_control in this messages array?",
+    "should_trigger": true
+  },
+  {
+    "query": "Our input costs are dominated by a static 10k-token system prompt — how do we cache it?",
+    "should_trigger": true
+  },
+  {
+    "query": "Every turn of our chat agent reprocesses the same docs; help me place cache breakpoints",
+    "should_trigger": true
+  },
+  {
+    "query": "Why is our prompt cache hit rate near zero? Here's the request structure",
+    "should_trigger": true
+  },
+  {
+    "query": "Estimate how many tokens per session our research agent will use and what drives it",
+    "should_trigger": false
+  },
+  {
+    "query": "Set a per-agent spending cap and kill switch for our autonomous agents",
+    "should_trigger": false
+  },
+  {
+    "query": "Size max_tokens for each component of this agentic workflow",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/api-builder/skills/prompt-caching-advisor/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "prompt-caching-advisor",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Our Claude contract-review service on Sonnet sends this on every request: a system prompt of about 9,000 characters of review instructions, then a 'reference' block with our 40,000-character clause library, then a line 'Today's date: {now}' appended to the end of that reference block, then 6 fixed few-shot examples (~12,000 characters), then the user's uploaded contract (varies per request). It's single-turn, roughly 2,000 requests a day. Where should the cache_control breakpoints go?",
+      "assertions": [
+        "Flags that the per-request timestamp appended to the reference block makes that block dynamic and would cause every request to miss, and recommends moving it out of the cached prefix before caching",
+        "No recommended cached block contains dynamic content — the user's contract and the date stay outside every breakpoint",
+        "Shows an annotated messages/system structure with each cache_control placement marked and commented",
+        "Explains that a breakpoint caches the entire prefix up to and including that block, not just the block itself",
+        "Uses at most three breakpoints, one per logical boundary",
+        "Checks block sizes against the Sonnet minimum (~2,048 tokens) using ~4 characters per token before recommending a cache",
+        "Gives a cache strategy summary paragraph with what is cached, why, expected hit rate, and the dominant cost driver before and after",
+        "Does not invent prompt sections, request volumes, or models beyond those in the prompt"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/api-builder/skills/prompt-caching-advisor/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "prompt-caching-advisor",
+  "version": "1.0.0",
+  "description": "Analyzes a prompt or conversation structure and identifies the highest-value cache breakpoints — where to insert cache_control checkpoints to minimize repeated token processing. Use when designing or optimizing a Claude API integration that uses prompt caching, when input costs are dominated by a static system prompt or few-shot block, or when a multi-turn conversation reprocesses the same context on every turn.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["token-budget-estimator"],
+  "tags": ["claude-api", "caching", "cost", "optimization", "prompt-engineering"],
+  "model": { "tier": "standard", "rationale": "Structural analysis of a prompt with threshold arithmetic and pattern matching — above light (needs API-specific judgment), no need for heavy." }
+}

skilldrop_cli/data/packs/api-builder/skills/token-budget-estimator/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: token-budget-estimator
+description: Estimates input and output token usage for a described agentic workflow, surfaces the dominant cost drivers, and suggests max_tokens budget controls per component. Use when planning a new Claude API integration, sizing a cost budget for a feature, or diagnosing why a workflow's token usage is higher than expected.
+---
+
+# token-budget-estimator
+
+Breaks down token usage for an agentic workflow — before you build it or while diagnosing runaway costs. The output is a component table (not a single number) because "how many tokens does this use?" has a different answer for the system prompt, the growing context window, tool results, and the final output. Knowing which component dominates tells you where to optimize.
+
+## How to respond
+
+### Step 1 — Intake
+
+Ask the user to describe their workflow. Collect:
+- What the agent does (brief description)
+- The shape of the system prompt (static instructions, injected context, few-shot examples — rough character/word count is fine)
+- How many turns or tool calls a typical session has
+- What tool results look like (small JSON blobs? Full document retrieval? Database rows?)
+- Roughly how long the final output is
+
+If they already have working code or logs, ask them to share a sample API request/response — you can count tokens more accurately from the actual content.
+
+### Step 2 — Estimate each component
+
+Build a token budget table. Token approximation: **1 token ≈ 4 characters** of English text; code/JSON runs denser (~3 chars/token).
+
+| Component | Est. tokens | Notes |
+|---|---|---|
+| System prompt | X | Static — same every call |
+| Injected context (per call) | X | User data, retrieved docs, etc. |
+| Few-shot examples | X | Static — cache candidate |
+| User turn (per call) | X | Variable per request |
+| Tool definitions | X | Sent on every call that uses tools |
+| Tool results (per turn) | X | Accumulate across turns |
+| Context accumulation | X | Previous turns retained in window |
+| Output (per call) | X | Depends on max_tokens and task |
+| **Total per session** | X | Sum across all turns |
+
+Flag the **dominant cost driver** — the single row with the largest token count — and explain why it dominates.
+
+### Step 3 — Recommend budget controls
+
+For each component, suggest a concrete control:
+
+- **System prompt too large**: split static vs dynamic; cache the static portion (`prompt-caching-advisor`)
+- **Context accumulation**: summarize earlier turns, or use a sliding window instead of full history
+- **Tool results**: truncate or paginate large results before passing to the model; never inject a 50-row database result when 5 representative rows suffice
+- **Output**: set `max_tokens` to the realistic output ceiling — open-ended `max_tokens` on a generation task wastes budget on over-generation
+- **Tool definitions**: only send the tools relevant to the current task state (tool selection narrows with progress)
+
+### Step 4 — Extended thinking note
+
+If the workflow uses extended thinking (`betas: ["interleaved-thinking"]`), add a note: thinking tokens are billed at the same input rate and are subject to a `budget_tokens` cap you set. Recommend setting `budget_tokens` to 2–4× the typical output length for reasoning tasks, and lower for classification or extraction tasks where long thinking chains rarely help.
+
+### Step 5 — Output format
+
+Produce:
+1. **Token budget table** — the component breakdown with estimates
+2. **Dominant driver** — named and explained
+3. **Three concrete controls** — ranked by expected savings, with specific API parameters where applicable (`max_tokens`, `cache_control`, tool selection logic)
+4. **Rough cost estimate** — using current public pricing for the tier the user is on (state the tier assumption; don't guess if unknown)
+
+## Anti-patterns
+
+- **A single total without a breakdown.** "~50,000 tokens per session" tells a developer nothing actionable. Always produce the component table.
+- **False precision from descriptions.** "3,142 tokens" from a description is theatre. Use ranges; tighten only when working from actual content.
+- **Optimizations without a ranking.** Listing five suggestions without saying which saves the most wastes the developer's attention.
+
+For caching-specific advice after sizing the budget, hand off to `prompt-caching-advisor`. For agent-level spending controls, see `agent-budget`.
+
+## Quality bar
+
+- **Ranges over false precision.** "~2,000–4,000 tokens" is more honest than "3,142 tokens" when you're working from a description. Use ranges when working from descriptions, tighter estimates when working from actual content.
+- **The table beats the total.** A single "~50,000 tokens per session" is nearly useless — the table that shows context accumulation accounts for 40,000 of those gives the developer somewhere to act.
+- **Name the optimization target.** Don't list five optimizations without ranking them. The one that saves 80% of the dominant component beats the one that shaves 5% off a small component.

skilldrop_cli/data/packs/api-builder/skills/token-budget-estimator/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "How many tokens will this agentic workflow use per session?",
+    "should_trigger": true
+  },
+  {
+    "query": "Size a cost budget for our new Claude integration before we build it",
+    "should_trigger": true
+  },
+  {
+    "query": "Our agent's token usage is way higher than expected — break down where it's going",
+    "should_trigger": true
+  },
+  {
+    "query": "Suggest max_tokens limits per component for this multi-turn tool-using agent",
+    "should_trigger": true
+  },
+  {
+    "query": "Exactly where should the cache_control checkpoints go in this prompt?",
+    "should_trigger": false
+  },
+  {
+    "query": "Put spending caps and budget kill-switches on our fleet of autonomous agents",
+    "should_trigger": false
+  },
+  {
+    "query": "Design the agent loop: when to stop, retry, and hand back to the user",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/api-builder/skills/token-budget-estimator/evals/evals.json

@@ -0,0 +1,18 @@
+{
+  "skill_name": "token-budget-estimator",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We're planning a Claude agent that triages inbound support tickets for Northwind. System prompt is about 6,000 characters of instructions plus 4 few-shot examples of about 1,500 characters each. Each session averages 8 tool calls: 3 calls to search_kb return about 3 KB of JSON each, and 5 calls to get_ticket_history return about 10 KB of JSON each. We keep the full conversation history. Final output is a 200-word triage note. We'll run around 5,000 sessions a day. Estimate the token budget.",
+      "assertions": [
+        "Produces a component table (system prompt, few-shot examples, tool definitions, tool results, context accumulation, output, total per session), not a single total",
+        "Estimates from the description are ranges, not falsely precise single numbers like '3,142 tokens'",
+        "Uses ~4 chars/token for prose and ~3 chars/token for the JSON tool results",
+        "Names the single dominant cost driver (likely accumulated tool results / context re-sent across turns) and explains why it dominates",
+        "Gives exactly three concrete controls ranked by expected savings, with specific API parameters (max_tokens, cache_control, truncating or paginating tool results)",
+        "The rough cost estimate states its pricing-tier assumption rather than guessing silently",
+        "Does not invent workflow components, session counts, or payload sizes not in the prompt"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/api-builder/skills/token-budget-estimator/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "token-budget-estimator",
+  "version": "1.0.0",
+  "description": "Estimates input and output token usage for a described agentic workflow, surfaces the dominant cost drivers, and suggests max_tokens budget controls per component. Use when planning a new Claude API integration, sizing a cost budget for a feature, or diagnosing why a workflow's token usage is higher than expected.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["prompt-caching-advisor", "agent-budget"],
+  "tags": ["claude-api", "cost", "tokens", "planning", "budgeting"],
+  "model": { "tier": "standard", "rationale": "Arithmetic breakdown plus heuristic judgment on dominant cost drivers — standard fits; no heavy reasoning needed." }
+}