skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/ai-engineering/skills/agent-adoption-stage/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: agent-adoption-stage
+description: Place an engineering team on the agentic-coding adoption ladder (0 gated → 4 intent-steered) using observables like agents-in-flight per engineer and who writes the code, name the one bottleneck gating the next step, prescribe the single next unlock, and state which current guardrail must change. Use when a leader asks "how far along are we with coding agents", "why has our AI adoption plateaued", or "what do we do next to get more out of this". Do NOT use to assess organisational preconditions like data, policy, and culture (that's ai-readiness-assessment) or to plan a tool's human rollout (that's ai-adoption-rollout).
+---
+
+# agent-adoption-stage
+
+Answer one question honestly: **which rung is this team actually on, and what is the single next thing that moves them up?** Not a scorecard, not a tool list — a placement backed by observables, the bottleneck that gates the next step, and one unlock.
+
+Adapted from Boris Cherny's *Steps of AI Adoption* (2026-07-16). The stage names and the bottleneck-shift are his; the guardrail changes and the routing here are skilldrop's, and everything is stated as a **capability** rather than a product so it stays true across tools and across years.
+
+The load-bearing idea: **the bottleneck moves.** Each stage is limited by something different, so a fix that unlocked the last step does nothing for the next one. Diagnosing the *current* bottleneck is the whole job; the stage number is just its index.
+
+## The ladder
+
+| Stage | Shape | Observable | The bottleneck |
+|---|---|---|---|
+| **0 · Gated** | no real access | tools unapproved, gateways slow, no path to run outputs | approval process — a legacy security posture optimising cost-per-token instead of outcomes |
+| **1 · Assisted** | you + one agent | **~1 agent**, synchronous, you read nearly every change | **your attention.** Low trust and no self-verification, so you watch instead of moving on |
+| **2 · Parallel** | you orchestrate | **~5–10 agents**, isolated checkouts, agent checks its own work first | **review throughput.** You're checking six streams instead of writing one |
+| **3 · Supervised autonomy** | manager of managers | **~100**, agent writes nearly all code, agents start agents | **trust in the loop**, and token efficiency as volume climbs |
+| **4 · Intent-steered** | steer by intent | **~1000+**, loop closed, monitor by exception | **finding and automating the work**, with the right guardrail per work type |
+
+## How to respond
+
+1. **Place the team on exactly one stage, from observables.** Ask for (or extract) three things: how many agents a typical engineer has in flight, who writes most of the code now, and what gets reviewed — every diff, final diffs, or exceptions. Quote the evidence. **A range is a refusal** — pick the stage the team is *operating at*, not the best day it ever had. Cap clarifying questions at 2.
+
+2. **Discount aspiration.** A team that bought licences for 200 people and has three power users is at stage 1 with an outlier, not stage 2. Place on the median engineer, and say so when the distribution is lopsided — the spread is itself a finding.
+
+3. **Name the current bottleneck in one sentence,** and check it against the table. If the team's stated pain doesn't match the stage's bottleneck, that mismatch is the most interesting thing in the assessment — surface it. ("You say review is the constraint, but engineers still run one agent at a time; the constraint is trust, not throughput.")
+
+4. **Prescribe exactly one unlock.** The next step, never a backlog of ten. The transitions:
+   - **0 → 1:** an approved path to run agents and land their output. Executive alignment, not tooling.
+   - **1 → 2:** **a self-verification loop the engineer trusts** — tests, build, lint, typecheck running *before* they look — plus more than one agent at a time and pre-approved safe commands so permission prompts stop blocking.
+   - **2 → 3:** context and delegation — let agents read the code, docs and discussions; automate review so it isn't the queue; break work into loops and routines; let agents start agents.
+   - **3 → 4:** scaled automation of domain-specific work (migrations, fuzzing, remediation) with per-work-type guardrails.
+
+5. **State which guardrail must change**, not just what to add. Guardrails are stage-appropriate, and carrying the old one forward is what stalls teams: reading every diff is right at stage 1 and *arithmetically impossible* at stage 3, where the control moves to the loop (automated review, sandboxing, isolation) and humans review by exception. Name the one to retire and the one to introduce.
+
+6. **Route the unlock to something concrete.** Each unlock has an implementation:
+
+   | Unlock | Where it's implemented |
+   |---|---|
+   | a trusted self-verification loop | [`pre-merge-review`](../../../dev-team/skills/pre-merge-review/SKILL.md) — a mechanical gate whose exit code decides, plus the reviewer panel |
+   | automated review that isn't the queue | the reviewer panel (`devils-advocate`, `security-reviewer`, `code-quality`) |
+   | loops and routines | [`agent-loop-design`](../agent-loop-design/SKILL.md) — generate→verify→gate with exit criteria and a cap |
+   | parallel agents without collision | [`subagent-design`](../subagent-design/SKILL.md) — topology, isolation, typed contracts |
+   | token efficiency as volume climbs | [`agent-budget`](../agent-budget/SKILL.md) + a provider-neutral model tier per task |
+   | encoding standards so agents inherit them | [`agents-md-generator`](../../../dev-team/skills/agents-md-generator/SKILL.md) and skills themselves |
+   | guardrails for autonomous work | [`agent-threat-model`](../agent-threat-model/SKILL.md) |
+
+7. **End with the re-measure date and what would prove the unlock landed.** An observable: "median agents-in-flight ≥ 3 and engineers stop reading intermediate diffs, in 6 weeks."
+
+## Quality bar
+
+- **Exactly one stage, cited to observables.** No ranges, no "between 2 and 3" — and never a placement asserted from ambition or licence count.
+- **Placement is on the median engineer**, with the distribution named when it's lopsided.
+- **Exactly one unlock.** A list of ten is a backlog, and it guarantees none of them happens.
+- **The bottleneck is the one gating the *next* step**, not a general complaint about AI.
+- **A guardrail to retire is named**, not only one to add — stage-appropriateness cuts both ways.
+- **Every unlock routes to a concrete implementation**, never to a product name.
+- **Vendor-neutral throughout.** Capabilities, not SKUs; a skill that names this quarter's products is wrong by next quarter.
+- **The source framework is credited.**
+
+## When to use this skill
+
+- ✅ "How far along are we with coding agents, really?"
+- ✅ Adoption plateaued and nobody can name why.
+- ✅ A leader wants to scale agent usage and needs to know whether the loop can carry it yet.
+- ✅ Re-measuring a quarter after a previous placement.
+
+## When NOT to use this skill
+
+- ❌ Assessing organisational preconditions — data, policy ownership, incentives — that's [`ai-readiness-assessment`](../ai-readiness-assessment/SKILL.md), a different axis (a team can be governance-ready and stuck at stage 1).
+- ❌ Planning how a tool reaches people — cohorts, enablement, comms — that's [`ai-adoption-rollout`](../ai-adoption-rollout/SKILL.md).
+- ❌ Choosing which use cases to build — that's [`ai-use-case-triage`](../ai-use-case-triage/SKILL.md).
+- ❌ Reporting measured usage from telemetry — that's [`ai-usage-report`](../ai-usage-report/SKILL.md).
+- ❌ Designing one specific loop or fleet — that's `agent-loop-design` / `subagent-design`, which this skill routes *to*.
+
+## Anti-patterns to avoid
+
+- ❌ **Scaling agent count before the loop has earned trust.** The named trap of stage 2→3: more agents on an unverified loop multiplies review burden instead of output. Trust first, count second.
+- ❌ **A stage claimed from ambition.** Licences bought, a mandate announced, or one enthusiastic staff engineer are not a stage. Median engineer, observable behaviour.
+- ❌ **Carrying stage-1 guardrails upward.** "Read every diff" doesn't scale to ten streams and is arithmetically impossible at a hundred; insisting on it is what caps a team at stage 1 while everyone blames the model.
+- ❌ **Answering with a product list.** Tools don't move a team up a rung — a trusted verification loop does. Name the capability and the loop change.
+- ❌ **Prescribing the whole ladder.** Handing someone stages 2, 3 and 4 at once guarantees stage 1 forever.
+- ❌ **Treating the stage as a status symbol.** Stage 4 is not better for a team whose work doesn't need it; the right stage is the one the work and the trust support.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+
+**Non-interactive:** with no user to ask, infer the stage from whatever observables the input contains and tag the placement `[assumption]`, naming what to confirm. If the input has no observable at all — no agent counts, no review posture, no statement of who writes the code — emit `BLOCKED: need at least one observable (agents in flight per engineer, who writes most of the code, or what gets reviewed)` rather than guessing a stage, because a wrong placement prescribes the wrong unlock.

skilldrop_cli/data/packs/ai-engineering/skills/agent-adoption-stage/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "How far along are we with coding agents?",
+    "should_trigger": true
+  },
+  {
+    "query": "Our AI adoption has plateaued — what's the next unlock?",
+    "should_trigger": true
+  },
+  {
+    "query": "Which stage of agentic coding maturity is my team at?",
+    "should_trigger": true
+  },
+  {
+    "query": "We want engineers running more agents — are we ready to scale that?",
+    "should_trigger": true
+  },
+  {
+    "query": "Assess whether our organisation's data and governance are ready for AI",
+    "should_trigger": false
+  },
+  {
+    "query": "Plan the rollout cohorts and enablement for this tool",
+    "should_trigger": false
+  },
+  {
+    "query": "Which AI use cases should we build first?",
+    "should_trigger": false
+  },
+  {
+    "query": "Design the subagent topology for this specific fleet",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/ai-engineering/skills/agent-adoption-stage/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "agent-adoption-stage",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We bought Claude Code for our 60 engineers six months ago. Most people use it like autocomplete for one task at a time and still read every diff before merging. Two staff engineers run several sessions at once. Tests are flaky so nobody trusts them. Where are we and what's next?",
+      "assertions": [
+        "Places the team on exactly one stage — no range — citing the observables from the prompt (one agent at a time, every diff read)",
+        "Places on the median engineer and calls out the two power users as an outlier rather than counting them as the stage",
+        "Names the bottleneck as attention/trust rather than review throughput, and connects it to the untrusted test suite",
+        "Prescribes exactly one unlock — a self-verification loop the engineer trusts — not a list of improvements",
+        "Names a guardrail to retire (reading every diff) alongside the one to introduce",
+        "Routes the unlock to a concrete implementation rather than to a product name",
+        "Ends with an observable that would prove the unlock landed and a re-measure date",
+        "Credits the source framework"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/ai-engineering/skills/agent-adoption-stage/manifest.json

@@ -0,0 +1,39 @@
+{
+  "name": "agent-adoption-stage",
+  "version": "0.1.1",
+  "description": "Place an engineering team on the agentic-coding adoption ladder (0 gated → 4 intent-steered) using observables like agents-in-flight per engineer and who writes the code, name the one bottleneck gating the next step, prescribe the single next unlock, and state which current guardrail must change. Use when a leader asks \"how far along are we with coding agents\", \"why has our AI adoption plateaued\", or \"what do we do next to get more out of this\". Do NOT use to assess organisational preconditions like data, policy, and culture (that's ai-readiness-assessment) or to plan a tool's human rollout (that's ai-adoption-rollout).",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "agent-budget",
+    "agent-loop-design",
+    "agent-threat-model",
+    "agents-md-generator",
+    "ai-adoption-rollout",
+    "ai-readiness-assessment",
+    "ai-usage-report",
+    "ai-use-case-triage",
+    "devils-advocate",
+    "pre-merge-review",
+    "subagent-design"
+  ],
+  "tags": [
+    "ai-adoption",
+    "agentic-coding",
+    "maturity-ladder",
+    "orchestration",
+    "engineering-leadership",
+    "bottleneck"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Places a team on a fixed 5-stage ladder from observables and routes one unlock. Bounded diagnosis against a rubric; escalate via ambiguous-input when the observables are contradictory or the distribution is heavily skewed."
+  }
+}

skilldrop_cli/data/packs/ai-engineering/skills/agent-budget/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agent-budget
+description: Write the spend spec for an agentic workflow — per-stage model tiers, token caps with hard abort rules, a graceful-degradation order, and cost-per-outcome as the governing metric. Use when the user asks what an agent loop or multi-agent workflow should be allowed to spend, wants token/cost budgets and caps for AI automation, or got a surprise bill from an agent fleet.
+---
+
+# agent-budget
+
+An unbudgeted agent loop is a runaway-cost incident with an architecture diagram. This skill produces the **budget spec** that governs an agentic workflow: what each stage may spend, on which tier of model, what happens at the cap, and — the number that actually matters — what one *outcome* costs. Pairs with `agent-loop-design` (the caps land in its loop spec) and `subagent-design` (the fleet line lands in its role cards); the tier vocabulary is this repo's own light/standard/heavy routing abstraction, so the spec ports across providers. Infra spend (compute, storage, egress) is `capacity-cost-model`'s domain — this skill budgets the tokens.
+
+## How to respond
+
+1. **Pin the outcome unit and the workflow's stages.** Ask at most 2 questions, spent on: *"what is one successful outcome?"* (a merged PR, a triaged ticket, a verified report — the denominator every cost divides by) and *"what does a typical run look like today?"* (stages, rounds, models — or "not built yet", which makes this a design-time budget, the cheap time to write one). Non-interactive run (no user to ask): derive both from the input and tag `[assumption]`; no outcome unit derivable → emit `BLOCKED: need the workflow and its outcome unit`.
+
+2. **Assign each stage the cheapest adequate tier** — light / standard / heavy, per the routing rule of thumb: **light** for mechanical extraction and formatting, **standard** for most generation, **heavy** only where the hard thinking *is* the value (adversarial verification, weighted judgment) — and heavy stages are never downgraded to save money; they're where the money buys correctness. Every tier assignment carries a one-line rationale. The classic misallocation runs both directions: frontier models formatting JSON, and — worse — the cheap model doing the verify pass that exists to catch the cheap mistakes.
+
+3. **Set three numbers per stage** in [`templates/budget-spec.md`](templates/budget-spec.md): **expected** spend per run (estimate honestly, tag `[assumption]` until measured), **cap** (the hard stop — 3–5× expected, tighter for unattended loops), and **on-cap action** (abort-and-escalate, or degrade — never "continue and warn"; a warning nobody is watching is a continue). State each as tokens **and** approximate money — tokens are what the harness enforces, but money is the only unit that sums across tiers, so **all cap comparisons happen in currency**. A stage that fans out per item carries two caps: a per-item cap (that item fails to the report's needs-human list; the rest continue) and a stage-wide cap. Then the **run-level cap** for the whole workflow — in currency, *less* than the sum of stage caps: every stage simultaneously hitting its cap is not a run to finish, it's an anomaly to stop.
+
+4. **Write the degradation ladder** — what gives, in order, when spend pressure hits: first **narrow scope** (fewer items per run), then **reduce parallelism** (smaller fleet, slower wall-clock), then **cut non-verification stages** (skip the polish pass), and **last — never — verification**. Skipping verify to save tokens converts a cost problem into a correctness problem at the exact moment quality is already under pressure; a workflow that can't afford its verifier can't afford to run. State each rung's trigger and who flips it.
+
+5. **Make cost-per-outcome the governing metric.** Total tokens is noise; **spend ÷ successful outcomes** is the number with meaning — a loop that gets cheaper per run but passes fewer runs got more expensive. Give it a target and a review threshold, and put beside it the **comparison line**: what the same outcome costs today (an hour of an engineer's time, the manual process) — a $4 triaged ticket is expensive against 60 seconds of a human's glance and cheap against twenty minutes of one; without the line, nobody can say which.
+
+6. **Add measurement and emit.** Spend logged per run per stage (tagged by stage name, feeding the loop spec's telemetry row); weekly review of cost-per-outcome and cap-hit counts by a named role; alert on cap-hit rate rising (the leading indicator of drift — inputs grew, a prompt regressed, or a model changed under you) and on any run breaching the run-level cap (that's an incident, not a line item). Emit the spec in one message: stage table, run cap, degradation ladder, cost-per-outcome with comparison line, measurement plan. Flag every `[assumption]` estimate as the calibration backlog — after ~20 real runs, expected values stop being guesses. Hand off: the caps → `agent-loop-design`'s loop spec; per-agent tiers → `subagent-design`'s role cards; the verifier's quality gate → `llm-eval-harness`.
+
+## Useful references in this skill
+
+- [`templates/budget-spec.md`](templates/budget-spec.md) — stage table, degradation ladder, cost-per-outcome, and measurement skeleton
+
+## Quality bar
+
+- **The outcome unit is named** and every cost in the doc divides by it.
+- **Every stage has tier + rationale + three numbers** (expected, cap, on-cap action). No stage rides free.
+- **Heavy tiers survive.** No verification or judgment stage was downgraded to make the total look better.
+- **Caps are hard.** Every on-cap action is abort or degrade — "warn and continue" appears nowhere.
+- **The run cap is less than the sum of stage caps**, and the doc says why.
+- **Verification is last on the degradation ladder**, explicitly.
+- **The comparison line exists** — cost-per-outcome sits next to what the outcome costs without the agents.
+- **Estimates are tagged.** `[assumption]` until measured; the calibration step is scheduled, not implied.
+
+## When to use this skill
+
+- ✅ "What should this agent workflow be allowed to spend?" — at design time, the cheap time
+- ✅ A surprise token bill arrived — retrofit caps and a degradation ladder
+- ✅ An `agent-loop-design` or `subagent-design` spec needs its budget line filled in
+- ✅ "Is this automation actually cheaper than doing it by hand?" — build the comparison line
+
+## When NOT to use this skill
+
+- ❌ Infra/cloud cost modeling (compute, storage, egress) — `capacity-cost-model`
+- ❌ Choosing a model tier for a single skilldrop skill — that's `model-routing.json`'s table, already decided
+- ❌ Designing the loop or the fan-out itself — `agent-loop-design` / `subagent-design`; this skill prices what they draw
+- ❌ Negotiating provider contracts or rate limits — procurement, not a spec
+
+## Anti-patterns to avoid
+
+- ❌ **Budget-free loops.** "We'll see what it costs" means the invoice is the monitoring system.
+- ❌ **Warn-and-continue caps.** A cap whose breach action is a log line is a number, not a cap.
+- ❌ **Skimping the verifier.** Downgrading or skipping verification under spend pressure — the false economy that ships fleet-speed garbage precisely when scrutiny dropped.
+- ❌ **Token vanity metrics.** Celebrating "20% fewer tokens" while cost-per-successful-outcome rose because pass rates fell.
+- ❌ **Frontier-everything.** The orchestrator's model formatting JSON at heavy-tier prices because nobody assigned tiers per stage.
+- ❌ **Missing comparison line.** A cost-per-outcome with nothing beside it can justify anything or condemn anything.
+- ❌ **Estimates that never graduate.** `[assumption]` numbers still governing caps six months and a thousand runs later.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+- ❌ **A bare `BLOCKED` line.** Keep the `BLOCKED: need <X>` line, then write for a person: what is missing in plain words, what you will produce once you have it, and anything the request already lets you say.

skilldrop_cli/data/packs/ai-engineering/skills/agent-budget/evals/eval_queries.json

@@ -0,0 +1,11 @@
+[
+  { "query": "What should our agent workflow be allowed to spend in tokens?", "should_trigger": true },
+  { "query": "We got a surprise LLM bill from our automation — put budgets and caps on it", "should_trigger": true },
+  { "query": "Is this agent pipeline actually cheaper than doing the work manually?", "should_trigger": true },
+  { "query": "Add a budget line to this loop spec", "should_trigger": true },
+
+  { "query": "Model our service's cloud infrastructure costs at 10x scale", "should_trigger": false },
+  { "query": "Which model tier should the adr-generator skill run on?", "should_trigger": false },
+  { "query": "Design the loop with exit criteria for this automation", "should_trigger": false },
+  { "query": "Design the eval golden set for our LLM judge", "should_trigger": false }
+]

skilldrop_cli/data/packs/ai-engineering/skills/agent-budget/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill_name": "agent-budget",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Budget our nightly agent workflow: it reviews the day's merged PRs for security issues. Stages: collect diffs, one reviewer agent per PR (typically 15 PRs), an adversarial verifier on each finding, and a summary report. One outcome = a verified finding report delivered by 8am. We got a $900 bill last week and nobody can say if that's bad.",
+      "assertions": [
+        "The outcome unit is the verified report (or per-PR-reviewed), and every cost divides by it",
+        "Every stage has a tier with a one-line rationale — collection is light, review standard/heavy, verification heavy and explicitly never downgraded",
+        "Every stage has expected spend, a hard cap (roughly 3-5x expected), and an on-cap action that is abort or degrade — no warn-and-continue",
+        "A run-level cap exists and is less than the sum of stage caps, with the reason stated",
+        "The degradation ladder is ordered scope -> parallelism -> non-verification stages, with verification explicitly last/never",
+        "Cost-per-outcome gets a target and a comparison line against the manual alternative (e.g. engineer review time), addressing whether $900/week is bad",
+        "Estimates are tagged [assumption] with a calibration step after ~20 runs",
+        "Measurement includes per-stage spend logging, a review cadence, and an alert on rising cap-hit rate",
+        "Hand-offs route caps to agent-loop-design and per-agent tiers to subagent-design"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "[Non-interactive run — no user available to answer questions] Set a token budget.",
+      "assertions": [
+        "No budget is fabricated — the output is BLOCKED: need the workflow and its outcome unit",
+        "No stage table or caps appear"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/ai-engineering/skills/agent-budget/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "agent-budget",
+  "version": "0.1.1",
+  "description": "Write the spend spec for an agentic workflow — per-stage model tiers, token caps with hard abort rules, a graceful-degradation order, and cost-per-outcome as the governing metric. Use when the user asks what an agent loop or multi-agent workflow should be allowed to spend, wants token/cost budgets and caps for AI automation, or got a surprise bill from an agent fleet.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["agent-loop-design", "capacity-cost-model", "llm-eval-harness", "subagent-design"],
+  "tags": ["agent-budget", "token-budget", "cost-control", "agentic", "caps", "cost-per-outcome"],
+  "model": { "tier": "standard", "rationale": "Quantitative spec synthesis against a fixed tier vocabulary and degradation ladder. Cap-setting judgment is bounded by the 3-5x rule; escalate via ambiguous-input when the workflow itself is undefined." }
+}

skilldrop_cli/data/packs/ai-engineering/skills/agent-budget/templates/budget-spec.md

@@ -0,0 +1,30 @@
+# Agent budget: {workflow name}
+
+> Outcome unit: {one successful …} · Status: {design-time [assumption] | calibrated on {N} runs} · Owner: {role}
+
+## Stage budgets
+
+| Stage | Tier | Why this tier | Expected / run | Cap (hard) | On cap |
+|---|---|---|---|---|---|
+| {stage} | light / standard / heavy | {one line} | {tokens ≈ ${…} `[assumption]`?} | {3–5× expected, tokens ≈ $; per-item + stage-wide for fan-out stages} | abort→escalate / degrade rung {n} / per-item: fail item to needs-human, continue rest |
+
+**Run-level cap:** ${number, < sum of stage caps in currency — the only unit that sums across tiers} — all stages capping at once is an anomaly to stop, not a run to finish.
+
+## Degradation ladder (in order; trigger and owner per rung)
+
+1. Narrow scope — {fewer items per run} · trigger: {…} · flipped by: {role}
+2. Reduce parallelism — {smaller fleet} · trigger: {…}
+3. Cut non-verification stages — {which} · trigger: {…}
+4. **Verification is never cut.** A workflow that can't afford its verifier can't afford to run.
+
+## Cost per outcome
+
+- **Target:** {spend ÷ successful outcomes} · review threshold: {value that triggers investigation}
+- **Comparison line:** the same outcome today costs {manual process, time × rate} — the number that says whether this is cheap.
+
+## Measurement
+
+- Spend logged per run, per stage (stage-tagged; feeds the loop spec's telemetry row)
+- {cadence} review of cost-per-outcome + cap-hit counts by {role}
+- Alerts: cap-hit rate rising ({threshold}) → drift investigation · run-level cap breached → incident, not a line item
+- Calibration: replace `[assumption]` expecteds after {~20} real runs · date: {…}

skilldrop_cli/data/packs/ai-engineering/skills/agent-loop-design/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: agent-loop-design
+description: Design a supervised agent loop — the generate→verify→gate cycle, observable exit criteria, hard iteration cap, human gates at irreversible steps, and failure routes — as a loop spec a team can implement in any agent harness. Use when the user wants to automate a recurring task with an AI agent loop, design a work loop / review loop / research loop, or asks "how do I stop my agent from running forever or shipping junk".
+---
+
+# agent-loop-design
+
+You shouldn't be prompting agents; you should be designing the loops that prompt them — and a loop is only as good as its exits. This skill produces a **loop spec**: the states, gates, caps, and failure routes that turn "run the agent again until it looks right" into a system a team can trust unattended. `feature-implement-loop` is this repo's worked example of the pattern (generate → adversarial review → gate, capped at 3 rounds); this skill designs *new* loops for the user's own tasks. Fan-out inside a stage is `subagent-design`'s job; what the loop may spend is `agent-budget`'s.
+
+## How to respond
+
+1. **Pin the loop's job and its "done".** Ask at most 2 questions, spent on: *"what artifact does one successful run produce?"* and *"how would a human verify it's right without watching the run?"* The done-condition must be **observable** — tests pass, checklist satisfied, reviewer-agent returns zero blockers — never "output looks good". No observable done-condition derivable → the task isn't loop-ready; say what needs defining first. Non-interactive run (no user to ask): derive both from the input and tag `[assumption]`; no artifact derivable → emit `BLOCKED: need the task and its done-condition`.
+
+2. **Draw the state machine — generate, verify, gate, and nothing mushier.**
+   - **Generate**: produces or revises the artifact. Must consume the verifier's findings from the previous round as explicit input — a generate step that can't see why it failed is retry, not iteration.
+   - **Verify**: judges the artifact against the done-condition. **The verifier is never the generator** — same model grading its own homework inflates; use a different persona, prompt, or agent (`devils-advocate`-style adversarial framing where quality is the risk, or programmatic checks where they exist — cheapest adequate check wins, per `llm-eval-harness`'s grading ladder).
+   - **Gate**: routes on the verdict — pass → exit/handoff; fail → generate with findings; fail at cap → escalate. Every loop has exactly these three state types; "polish", "reflect", and "improve" states with no verdict are where loops go to wander.
+
+3. **Set the caps — both of them, as numbers.**
+   - **Revision cap**: max verify-fail rounds before escalation. Default 3 (`feature-implement-loop`'s cap); justify anything higher with what new information later rounds could possibly have.
+   - **Budget cap**: max spend per run, referencing an `agent-budget` line (or a stated token/cost number when no budget spec exists yet, tagged `[assumption]`). A loop without numeric caps is a runaway incident scheduled for later.
+
+4. **Place the human gates.** Every **irreversible or outward-facing action** — merge, deploy, send, publish, delete — sits behind a human gate: the loop stops and presents; it never proceeds on its own verdict. Reversible internal work (drafts, branches, scratch files) runs unattended; that's the point of the loop. Name each gate's presenter format: what the human sees must be a **decision-shaped digest** (the artifact + the verifier's verdict + what changed since the last gate), not a transcript.
+
+5. **Design the failure routes.** Three exits, each specified:
+   - **Cap hit** → escalate to a named role with a digest: rounds used, last findings, the diff of attempts. Raw logs are not an escalation.
+   - **Verifier can't judge** (input outside the done-condition's domain) → route out with `BLOCKED: <what's missing>`, don't loop on it.
+   - **Systemic failure** (same finding class every round) → stop early — identical findings twice means the generate step can't fix it; more rounds spend budget to relearn that.
+
+6. **Add the telemetry row and emit** with [`templates/loop-spec.md`](templates/loop-spec.md): per-run log of rounds-used, spend, verdict, and escalations — the numbers that tell you the loop is degrading before its output does (rounds-to-pass creeping up is the leading indicator). Emit the spec in one message: state machine (Mermaid `stateDiagram-v2`), caps, gates, failure routes, telemetry. Hand off: stage fan-out → `subagent-design`; the spend model → `agent-budget`; the verifier's golden set → `llm-eval-harness`.
+
+## Useful references in this skill
+
+- [`templates/loop-spec.md`](templates/loop-spec.md) — state machine, caps, gates, failure-route, and telemetry skeleton
+
+## Quality bar
+
+- **The done-condition is observable** — a person who didn't watch the run can check it in minutes.
+- **Verifier ≠ generator**, structurally: different persona, prompt, or program — stated in the spec, not implied.
+- **Both caps are numbers.** "Reasonable number of iterations" is not a cap; 3 is.
+- **Every irreversible action has a human gate**, and every gate has a decision-shaped digest format.
+- **Generate consumes findings.** The spec shows the findings flowing into the next round's input.
+- **All three failure routes are specified** — cap-hit, can't-judge, systemic — each with a destination.
+- **The Mermaid renders** and contains only generate/verify/gate states plus the human-gate and escalate exits — no "polish"/"reflect" states without a verdict.
+
+## When to use this skill
+
+- ✅ "I want an agent to keep our runbooks up to date / triage inbound bugs / draft weekly reports — design the loop"
+- ✅ "My agent keeps running forever / declaring victory on garbage" — retrofit exits onto an existing loop
+- ✅ Turning a one-shot prompt that "usually works" into something a team can run unattended
+- ✅ Reviewing a proposed automation for missing gates before it touches production
+
+## When NOT to use this skill
+
+- ❌ Implementing one feature right now — run `feature-implement-loop`; it *is* the loop
+- ❌ Splitting one task across parallel agents — `subagent-design`
+- ❌ Deciding what the loop may spend — `agent-budget`
+- ❌ One-off tasks — a loop for something that runs once is ceremony
+
+## Anti-patterns to avoid
+
+- ❌ **Self-grading.** The generator's model praising the generator's output is how confident garbage ships. The verifier is a different pass with an adversarial job description.
+- ❌ **Cap-free loops.** "It'll converge" is a hypothesis; the cap is what makes it a safe one to be wrong about.
+- ❌ **Vibes exits.** "Loop until the output is good" defers the definition of good to the loop's most tired moment.
+- ❌ **Retry cosplay.** If round N's generate can't see round N-1's findings, you built retry with extra steps — findings flow forward or the loop learns nothing.
+- ❌ **Transcript escalations.** Escalating a 40-page log teaches humans to ignore escalations. Digest: rounds, findings, attempts, the ask.
+- ❌ **Gating the reversible, freeing the irreversible.** Human approval for a draft file but auto-send on the customer email is the exact wrong way around — gate placement follows blast radius, not effort.
+- ❌ **Loops without telemetry.** A loop that doesn't log rounds-and-spend per run degrades silently until the quarter's token bill or a shipped defect announces it.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+- ❌ **A bare `BLOCKED` line.** Keep the `BLOCKED: need <X>` line, then write for a person: what is missing in plain words, what you will produce once you have it, and anything the request already lets you say.

skilldrop_cli/data/packs/ai-engineering/skills/agent-loop-design/evals/eval_queries.json

@@ -0,0 +1,11 @@
+[
+  { "query": "Design an agent loop to keep our runbooks up to date", "should_trigger": true },
+  { "query": "My agent keeps iterating forever — how do I add proper exit criteria?", "should_trigger": true },
+  { "query": "Turn this prompt we run by hand every week into a supervised automation loop", "should_trigger": true },
+  { "query": "Review this proposed agent automation for missing human gates", "should_trigger": true },
+
+  { "query": "Implement this user story with tests", "should_trigger": false },
+  { "query": "Split this task across parallel subagents", "should_trigger": false },
+  { "query": "How many tokens should this workflow be allowed to spend?", "should_trigger": false },
+  { "query": "Design the eval set for our LLM feature", "should_trigger": false }
+]

skilldrop_cli/data/packs/ai-engineering/skills/agent-loop-design/evals/evals.json

@@ -0,0 +1,28 @@
+{
+  "skill_name": "agent-loop-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design an agent loop that keeps our API reference docs in sync with the codebase: when endpoints change, the agent should update the docs, and we want to review before anything is published to the public docs site.",
+      "assertions": [
+        "One run's artifact and an observable done-condition are named (not 'docs look correct')",
+        "The state machine has exactly generate/verify/gate(/escalate) states, rendered as valid Mermaid stateDiagram-v2",
+        "The verifier is structurally different from the generator, with the independence stated",
+        "Both caps are numbers: a revision cap and a per-run budget line",
+        "Publishing to the public docs site sits behind a human gate with a decision-shaped digest format described",
+        "Findings from a failed verify flow into the next generate round explicitly",
+        "All three failure routes are specified: cap-hit escalation with digest, can't-judge BLOCKED route, systemic early-stop",
+        "A telemetry row logs rounds/spend/verdict per run with a review cadence",
+        "Hand-offs point to subagent-design for fan-out and agent-budget for the spend model"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "[Non-interactive run — no user available to answer questions] Design an agent loop.",
+      "assertions": [
+        "No loop is designed — the output is BLOCKED: need the task and its done-condition",
+        "No state machine or caps are fabricated"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,11 @@
+{
+  "name": "agent-loop-design",
+  "version": "0.1.1",
+  "description": "Design a supervised agent loop — the generate→verify→gate cycle, observable exit criteria, hard iteration cap, human gates at irreversible steps, and failure routes — as a loop spec a team can implement in any agent harness. Use when the user wants to automate a recurring task with an AI agent loop, design a work loop / review loop / research loop, or asks \"how do I stop my agent from running forever or shipping junk\".",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["agent-budget", "devils-advocate", "feature-implement-loop", "llm-eval-harness", "subagent-design"],
+  "tags": ["agent-loop", "loop-engineering", "automation", "supervised-loop", "agentic", "guardrails"],
+  "model": { "tier": "standard", "rationale": "Design synthesis against a fixed state-machine pattern and exit-criteria catalog. The gate-placement judgment is bounded by the blast-radius rule; escalate via ambiguous-input when the task itself is contested." }
+}

skilldrop_cli/data/packs/ai-engineering/skills/agent-loop-design/templates/loop-spec.md

@@ -0,0 +1,46 @@
+# Loop spec: {loop name — the task, not the tech}
+
+> One run produces: {artifact} · Done when: {observable condition} · Owner: {role}
+
+## State machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Generate: {trigger}
+    Generate --> Verify: artifact + round log
+    Verify --> Gate: verdict + findings
+    Gate --> Generate: fail (findings feed next round)
+    Gate --> HumanGate: pass
+    Gate --> Escalate: fail at cap {N}
+    HumanGate --> [*]: approved → {irreversible action}
+    Escalate --> [*]: digest → {role}
+```
+
+## Caps
+
+| Cap | Value | Rationale |
+|---|---|---|
+| Revision cap | {N, default 3} | {what could later rounds know that round 3 didn't?} |
+| Budget per run | {tokens or currency; cite the `agent-budget` line, or a stated number tagged [assumption] until that spec exists} | {…} |
+
+## Verification (never the generator)
+
+- Verifier: {persona/prompt/program, and why it's independent of the generator}
+- Judges against: {the done-condition, itemized}
+- Cheapest adequate check: {programmatic where possible → structured assertions → LLM judge last}
+
+## Human gates
+
+| Gate | Guards (irreversible action) | Digest the human sees |
+|---|---|---|
+| {name} | {merge / send / deploy / delete} | {artifact + verdict + delta since last gate} |
+
+## Failure routes
+
+- **Cap hit** → {role} with digest: rounds used, last findings, attempt diffs
+- **Verifier can't judge** → `BLOCKED: {what's missing}` to {destination}
+- **Systemic** (same finding class twice) → stop early, route to {role}
+
+## Telemetry (per run)
+
+rounds-used · spend · verdict · escalated? — reviewed {cadence} by {role}; alert when rounds-to-pass trends up {threshold}.

skilldrop_cli/data/packs/ai-engineering/skills/agent-threat-model/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: agent-threat-model
+description: Threat-model an AI agent deployment against the lethal trifecta — private data, untrusted content, and an exfiltration vector — producing a per-capability matrix, a named architectural fix for every unsafe path, and a pre-launch checklist. Use before shipping an agent, when reviewing MCP server or tool permissions, when the user asks about prompt injection or data exfiltration risk, or when deciding whether an agent's capability surface is safe to expose.
+---
+
+# agent-threat-model
+
+Answers one question about an agent deployment: **can text the agent reads cause it to send private data somewhere an attacker can see?** An LLM cannot reliably separate instructions from data, so any agent holding all three legs of the lethal trifecta — private data, untrusted content, an exfiltration vector — is compromised by construction, not by bug. The output is architectural: which leg gets broken, on which path, by which design change.
+
+Complements `threat-model`, which runs STRIDE on the system the agent lives in. That model asks how the system is attacked; this one asks what the agent can be talked into doing. Run both on an agent that handles real data.
+
+## How to respond
+
+1. **Inventory the capability surface before scoring anything.** From the input — an agent description, MCP/tool config, system prompt, `agent-loop-design` output, or repo — extract four lists:
+   - **Data reach** — everything the agent can read, *transitively*. A filesystem tool reaches every secret in `.env`; a database tool reaches every tenant the credential permits. Reach is what the credential allows, not what the feature intends.
+   - **Content sources** — everything that puts tokens into the context window: user messages, web fetches, retrieved documents, file contents, tool results, PR comments, email, calendar invites, subagent output.
+   - **Tools** — every callable, including the ones that feel inert (`read_file`, `search`, `fetch`).
+   - **Egress paths** — every way bytes leave. This is the leg that gets missed; sweep [`reference.md`](reference.md) rather than listing the obvious HTTP tool.
+
+   Ask at most 2 questions, and spend them on data reach and egress — a wrong boundary there invalidates the matrix. Everything else is tagged `[assumption]`.
+
+2. **Classify each content source trusted or untrusted, defaulting to untrusted.** A source is trusted **only if every party who can write to it is already authorized to command the agent**. A shared team wiki fails this. A support ticket fails this. The agent's own earlier output fails it once untrusted content has entered the context. State the rule's verdict per source in one clause — ✅ *"Zendesk ticket body — untrusted; any customer can write it"*.
+
+3. **Build the trifecta matrix, one row per capability path.** A path is a route from a content source, through the tools it can influence, to an egress. Mark each leg present/absent and rank with the shared markers:
+   - 🟥 all three legs on one path, no gate — data theft is a design property; requires a broken leg
+   - 🟧 all three legs, mitigated only by a human gate or an allowlist — the control is load-bearing and must be named
+   - 🟨 two legs, third reachable by a plausible change (a new tool, a widened scope)
+   - ⚪ one leg, or explicitly accepted with an owner
+
+   If every row is 🟥, the paths weren't separated finely enough. If none are, check the egress sweep — it is usually incomplete.
+
+4. **Break a leg on every 🟥, choosing from the ranked menu in [`reference.md`](reference.md).** Prefer the architectural fix over the procedural one: split the agent so the one reading untrusted content holds no privileged tools; remove the tool; allowlist egress destinations; gate the acting step on a human who sees the actual payload; narrow the credential. Each fix names *which leg it breaks* and how a reviewer verifies it — ✅ *"Retrieval subagent runs with no network tool and returns text only; verify by asserting the tool list is empty in its config test"*.
+
+5. **Run the three sweeps that get skipped.** One finding or an explicit reasoned all-clear for each:
+   - **Rendered egress** — markdown images, autolinked URLs, and HTML in any surface that renders agent output. An agent with no network tool still exfiltrates through an image the client fetches.
+   - **Transitive reach** — the tool that reads the file that holds the credential that reaches the other system. Score reach at the end of the chain.
+   - **Inherited capability** — subagents, tool-calling tools, and anything the agent can spawn. A quarantined reader that can invoke a privileged sibling is not quarantined.
+
+6. **Write residual risk with owners.** Anything not fixed is accepted, in writing, by a **named role** with the trigger that would force revisiting it. An unowned residual risk is an unrecorded decision.
+
+7. **Tag every 🟥 and 🟧 path with its OWASP IDs** from the table in [`reference.md`](reference.md): LLM Top 10 2025 (`LLM01:2025` prompt injection, `LLM02:2025` disclosure, `LLM06:2025` excessive agency, …) and, where the agent loads skills or plugins, the Agentic Skills Top 10 (`AST01`–`AST10`). A security team files findings against a framework; the tag lets them, without changing how the path is ranked.
+
+8. **Emit in one message**: capability inventory, the matrix, fixes per 🟥, the three sweeps, residual risk with owners, and a **pre-launch checklist** of what to verify before the agent faces real data. End with the revisit trigger — the model is stale the moment a tool, a content source, or a credential scope is added.
+
+**Non-interactive runs:** unstated capabilities are tagged `[assumption]` and modeled at their worst plausible scope. If no tool list, data reach, or content source can be established at all, emit `BLOCKED: need the agent's tool/permission inventory` — with nothing to inventory there is no model, and a fabricated one is worse than none.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the egress catalog (the sweep for step 1), the trust test for content sources, the ranked mitigation menu, the injection-vector bank per source type, and the OWASP ID mapping for step 7
+- [`templates/agent-threat-model.md`](templates/agent-threat-model.md) — output skeleton
+- [`examples/support-triage-agent.md`](examples/support-triage-agent.md) — worked example: a Zendesk triage agent, 4 paths, 2 🟥, one split that fixes both
+
+## Quality bar
+
+- **Every capability path is scored on all three legs.** A row with a blank leg wasn't analyzed, it was skipped.
+- **No prompt-level mitigation is presented as a control.** "The system prompt instructs the model to ignore injected instructions" mitigates nothing — it is precisely what the attack defeats. It may appear as defense in depth, never as the broken leg.
+- **No classifier is a broken leg either.** Injection detectors raise cost for the attacker; they do not remove a leg. Architecture beats instructions.
+- **Egress is enumerated past the network tool.** A model that lists only `http_request` failed the sweep — rendered markdown, error text, logs, and file writes are all channels.
+- **Every 🟥 is broken or signed off** by a named role with a revisit trigger. No silent acceptance.
+- **Every fix has a verification step** a reviewer can actually run — a config assertion, a test, an observed denial.
+- **Every 🟥 and 🟧 carries its OWASP IDs,** taken from the mapping table, not guessed from a risk's title.
+- **"Read-only" is never a safety claim.** Reading is how data reaches the attacker; the question is only where it goes next.
+
+## When to use this skill
+
+- ✅ Before shipping an agent that touches private data, internal systems, or customer content
+- ✅ Reviewing which MCP servers or tools an agent should be granted
+- ✅ "Could someone prompt-inject this?" / "Can this agent leak our data?"
+- ✅ Auditing an existing agent after a new tool, integration, or content source is added
+- ✅ Alongside `subagent-design` when deciding whether a task needs a quarantined reader
+
+## When NOT to use this skill
+
+- ❌ STRIDE on the surrounding system's architecture — that's `threat-model`
+- ❌ Reviewing written code for vulnerabilities — that's `devils-advocate` or `sonar-review`
+- ❌ Runaway loops, token burn, or infinite retries — that's `agent-budget` (a cost incident, not a security one)
+- ❌ Output quality, hallucination, or eval design — that's `llm-eval-harness`
+- ❌ After a confirmed leak — that's `postmortem-generator`
+
+## Anti-patterns to avoid
+
+- ❌ **Trusting the system prompt as a boundary.** Instructions in the prompt and instructions in a fetched web page arrive as the same tokens. Anything that relies on the model choosing correctly between them is a wish.
+- ❌ **Declaring a read-only agent safe.** Read-only means it can't write to *your* systems. It says nothing about what it hands to an attacker.
+- ❌ **Listing tools instead of paths.** The trifecta is a property of a route through the agent, not of any single tool. `fetch` is fine alone and lethal next to a secrets file.
+- ❌ **Counting a human gate as a fix without describing what the human sees.** Approving "the agent wants to call `send_email`" catches nothing; approving the rendered recipient and body catches the exfiltration.
+- ❌ **Modeling the intended flow only.** Error paths, retries, and the debug logging surface all carry data and are rarely scoped.
+- ❌ **A matrix with no owner on the accepted rows.** That is a document that files the risk, not one that assigns it.
+- ❌ **Showing the machinery.** The reply and the artifact are for the person who asked. Don't mention this skill, its files, templates, caps or internal terms, or that the run is non-interactive. Name another skill once, at the end, as a suggested next step, never inside the artifact.
+- ❌ **A bare `BLOCKED` line.** Keep the `BLOCKED: need <X>` line, then write for a person: what is missing in plain words, what you will produce once you have it, and anything the request already lets you say.