skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/stakeholder-comms/skills/decision-log/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: decision-log
+description: Extract decisions, action items, owners, and due dates from meeting notes, Slack threads, design-review transcripts, or any unstructured discussion. Produces a clean structured log the user can paste into a doc, tracker, or ADR queue. Use when the user has notes/threads/transcripts and asks for a "decision log", "action items", "what did we agree", or "follow-ups".
+---
+
+# decision-log
+
+You help the user turn messy meeting notes or threads into a structured log of what was decided, who owns the follow-up, and what's still open.
+
+## How to respond
+
+1. **Ingest the source.** The user will paste notes, give a file path, or share a transcript. If the source is huge (e.g., a 90-minute transcript), confirm scope: "Are you only interested in decisions, or also action items and open questions?"
+
+2. **Extract four categories:**
+
+   - **Decisions made.** Things the group agreed on — even if informal. Look for phrases like "we'll go with…", "let's do…", "agreed", "fine by me", "ship it". Capture the decision in active voice, with a one-line *why* if it's in the source.
+   - **Action items.** Things someone agreed to *do*. Need an owner (a name), an action (a verb phrase), and ideally a due date. If the date is fuzzy ("by next week"), convert to an absolute date and flag it.
+   - **Open questions.** Things explicitly *not* resolved. Include who needs to answer if it's stated.
+   - **Risks raised.** Concerns that were aired but not resolved — useful for the next meeting's agenda.
+
+3. **Convert fuzzy dates to absolute dates.** "Friday" → `YYYY-MM-DD`. "End of week" → `YYYY-MM-DD (EOW)`. "Next sprint" → ask the user when the next sprint ends if it's not in the source. Mark dates as `(implied)` when you've inferred them so the user can verify.
+
+4. **Attribute every action item to a named person.** "Someone should…" is not a tracked action — flag those as "unowned" so the user can assign in the meeting.
+
+5. **Output as four tables**, in this order:
+
+   ```markdown
+   ## Decisions
+   | # | Decision | Why | Source |
+   |---|---|---|---|
+
+   ## Action items
+   | # | Owner | Action | Due | Source |
+   |---|---|---|---|---|
+
+   ## Open questions
+   | # | Question | Owner (to answer) | Source |
+   |---|---|---|---|
+
+   ## Risks raised (not yet acted on)
+   | # | Risk | Raised by | Source |
+   |---|---|---|---|
+   ```
+
+   The `Source` column quotes ~5–10 words from the original notes so the user can verify nothing was hallucinated.
+
+6. **Surface gaps.** End with a "🚩 Gaps" callout listing:
+   - Action items without an owner
+   - Action items without a date
+   - Decisions whose rationale isn't captured in the source
+   - Anything where you weren't sure whether it was a decision or a discussion
+
+## Quality bar
+
+- **Don't invent ownership.** If the source says "we should email the legal team", don't pick a name. Flag as unowned.
+- **Don't promote opinions to decisions.** "I think we should use Postgres" is not a decision unless the group acknowledged it.
+- **Quote, don't paraphrase, the source column.** A 5–10 word verbatim snippet is the audit trail.
+- **Active voice in the action column.** ✅ "Send PR for ADR-0007 to legal" — ❌ "ADR-0007 to be sent to legal".
+- **Convert relative dates.** Today's date is needed — ask if unclear.
+
+## Anti-patterns to avoid
+
+- ❌ Mixing decisions and action items in one table. They're different.
+- ❌ Capturing every utterance — pick the load-bearing ones.
+- ❌ "AOB" or generic catch-all entries — be specific or drop.
+- ❌ Hallucinating attendees, dates, or rationale that isn't in the source.
+- ❌ Skipping the Gaps section because it looks like negative feedback — gaps are the most useful part for the meeting's follow-up email.
+- ❌ **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.

skilldrop_cli/data/packs/stakeholder-comms/skills/decision-log/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Extract the decisions and action items from these meeting notes",
+    "should_trigger": true
+  },
+  {
+    "query": "Turn this Slack thread into a decision log with owners and due dates",
+    "should_trigger": true
+  },
+  {
+    "query": "What did we actually decide in this transcript, and who owns what?",
+    "should_trigger": true
+  },
+  {
+    "query": "Give me a structured log of decisions from this design review",
+    "should_trigger": true
+  },
+  {
+    "query": "Write an ADR for the decision we made",
+    "should_trigger": false
+  },
+  {
+    "query": "Summarize this meeting for executives",
+    "should_trigger": false
+  },
+  {
+    "query": "Draft the design doc for what we agreed",
+    "should_trigger": false
+  },
+  {
+    "query": "Critique the quality of this decision log",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/stakeholder-comms/skills/decision-log/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "decision-log",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Pull the decisions and action items out of this design-review transcript. [transcript: mixed opinions, a couple of agreed decisions, some unowned follow-ups, and relative dates like 'next Friday']",
+      "assertions": [
+        "Opinions are not promoted to decisions — only items the group acknowledged appear as decisions",
+        "Ownership is never invented; items with no named owner are flagged unowned rather than assigned",
+        "The source column quotes the discussion verbatim in a short snippet, not a paraphrase",
+        "Action items are written in active voice",
+        "Relative dates are converted to absolute dates, marked when inferred",
+        "The output is a structured table the user can paste into a doc or tracker"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/stakeholder-comms/skills/decision-log/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "decision-log",
+  "version": "0.1.1",
+  "description": "Extract decisions, action items, owners, and due dates from meeting notes, Slack threads, design-review transcripts, or any unstructured discussion. Produces a clean structured log the user can paste into a doc, tracker, or ADR queue. Use when the user has notes/threads/transcripts and asks for a \"decision log\", \"action items\", \"what did we agree\", or \"follow-ups\".",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [],
+  "tags": ["meetings", "decisions", "action-items", "stakeholder-communication"],
+  "model": { "tier": "light", "rationale": "Extracts decisions/owners/dates from notes. Pattern extraction; escalates on long transcripts." }
+}

skilldrop_cli/data/packs/stakeholder-comms/skills/exec-summary/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: exec-summary
+description: Compress a long technical document, design doc, or proposal into a one-page executive summary aimed at non-technical or time-poor stakeholders. Use when the user has a long doc and needs a 30-second readable version, or is writing a 1-pager for a steering committee, partner, or executive sponsor.
+---
+
+# exec-summary
+
+You help the user turn dense technical material into a one-page brief that a VP can read between meetings and act on.
+
+## How to respond
+
+1. **Get the source.** Either the user pastes the full doc, gives you a file path, or describes the project verbally. If the source is more than ~3000 words, ask them to confirm scope: "Is this for [audience X] who already knows [Y]?"
+
+2. **Identify the audience.** A one-pager for an exec sponsor is different from one for finance is different from one for a partner. Default audience is "senior leader who is not an engineer, has 60 seconds, and needs to approve or push back."
+
+3. **Use [`templates/exec-summary.md`](templates/exec-summary.md)** — six fixed sections:
+   1. **The Ask** (one line — what decision/approval are we requesting?)
+   2. **TL;DR** (three bullets — what's the project, why now, what's the recommendation)
+   3. **Business impact** (revenue / cost / risk / time — quantified where possible)
+   4. **Cost & timeline** (rough numbers — say "rough" if they are)
+   5. **Risks & how we're managing them** (max 3 — pick the ones the exec would ask about)
+   6. **What we need from you** (concrete asks — money, headcount, an exec decision, a connection)
+
+4. **Compress ruthlessly.** A one-pager is **one page** — about 300–400 words rendered, including the headers. Cut:
+   - Adjectives ("robust", "scalable", "next-generation")
+   - Hedging ("we believe", "in many cases")
+   - Technical jargon (replace or define inline once)
+   - History the audience already knows
+
+5. **Lead with the conclusion.** Execs read top-to-bottom and stop when they have what they need. The Ask + TL;DR must be self-contained — if those are all the exec reads, they should be able to make a decision.
+
+## Quality bar
+
+- **Quantify or qualify.** Numbers are best ("\$2.4M ARR at risk"), but if you don't have numbers, say "directional" rather than inventing precision.
+- **Plain language.** A non-engineer should not encounter a term they don't recognize in the first paragraph.
+- **No internal-team-speak.** "OKRs", "swimlanes", "north-star metric" are okay; "sharding strategy", "eventually consistent", "blue-green" need translation or replacement.
+- **Active voice, second person where natural.** "You'll need to approve the budget" beats "budget approval will be required".
+
+## Anti-patterns to avoid
+
+- ❌ Burying the recommendation on page 2 of a 1-pager.
+- ❌ Listing technical wins ("reduced p99 by 40ms") with no business translation.
+- ❌ Risk sections full of generic risks ("scope creep", "team turnover"). Pick the *project-specific* ones.
+- ❌ "Next steps: align with stakeholders." Empty calorie. Replace with the actual action.
+- ❌ Asking the exec to "review the full design doc for details" without saying which sections matter.

skilldrop_cli/data/packs/stakeholder-comms/skills/exec-summary/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Summarize this design doc for our executives",
+    "should_trigger": true
+  },
+  {
+    "query": "I need a one-page summary of this long proposal for a non-technical stakeholder",
+    "should_trigger": true
+  },
+  {
+    "query": "Give me the 30-second version of this technical document",
+    "should_trigger": true
+  },
+  {
+    "query": "Compress this into something our COO will actually read",
+    "should_trigger": true
+  },
+  {
+    "query": "Build me a PowerPoint of this",
+    "should_trigger": false
+  },
+  {
+    "query": "Outline the slides for this presentation",
+    "should_trigger": false
+  },
+  {
+    "query": "What should I change about how I present to a board audience?",
+    "should_trigger": false
+  },
+  {
+    "query": "Critique this document against its quality bar",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/stakeholder-comms/skills/exec-summary/evals/evals.json

@@ -0,0 +1,17 @@
+{
+  "skill_name": "exec-summary",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Compress this 14-page platform-migration design doc into a one-page summary for our non-technical COO.",
+      "assertions": [
+        "Fits one page and leads with the decision or ask, not background",
+        "Numbers are quantified where available; where they aren't, the summary says 'directional' rather than inventing precision",
+        "A non-engineer meets no unexplained technical term in the first paragraph",
+        "No internal team-speak (OKRs, swimlanes, north-star metric) survives into the summary",
+        "Nothing is asserted that isn't supported by the source document",
+        "The output is prose a reader can scan in ~30 seconds — not slides and not a deck outline"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/stakeholder-comms/skills/exec-summary/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "exec-summary",
+  "version": "0.1.0",
+  "description": "Compress a long technical document, design doc, or proposal into a one-page executive summary aimed at non-technical or time-poor stakeholders. Use when the user has a long doc and needs a 30-second readable version, or is writing a 1-pager for a steering committee, partner, or executive sponsor.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [],
+  "tags": ["executive", "summary", "stakeholder-communication", "one-pager"],
+  "model": { "tier": "standard", "rationale": "One-page compression. Needs to keep the right signal; escalates on very long source docs." }
+}

skilldrop_cli/data/packs/stakeholder-comms/skills/exec-summary/templates/exec-summary.md

@@ -0,0 +1,48 @@
+# {Project / initiative name}
+
+**To:** {Audience — e.g. "CFO + Steering Committee"}
+**From:** {Author / team}
+**Date:** {YYYY-MM-DD}
+**Status:** {For decision / FYI / For approval}
+
+## The Ask
+
+{One sentence — the specific decision, approval, or input you need from this audience. If there's no Ask, this is a status update, not an exec summary.}
+
+## TL;DR
+
+- **What:** {one bullet — what this project is, in plain language}
+- **Why now:** {one bullet — the forcing function}
+- **Recommendation:** {one bullet — what we're recommending the audience approve / change / do}
+
+## Business impact
+
+- **Revenue / cost:** {quantified where possible — "$X savings per year" or "$Y revenue protected"}
+- **Risk:** {what risk is mitigated, or what risk is incurred}
+- **Time:** {when the business sees impact}
+
+## Cost & timeline
+
+| What | Estimate | Confidence |
+|---|---|---|
+| Engineering effort | {N person-months} | {rough / directional / firm} |
+| Vendor / infra cost | {$X over N months} | {…} |
+| Calendar timeline | {N months end-to-end} | {…} |
+
+## Top risks & mitigations
+
+| Risk | Mitigation |
+|---|---|
+| {Project-specific risk #1} | {What we're doing about it} |
+| {Risk #2} | {…} |
+| {Risk #3} | {…} |
+
+## What we need from you
+
+- {Concrete ask — e.g. "Approve $400k FY26 budget by end of Q2"}
+- {Concrete ask — e.g. "Decision: build in-house vs. buy from Vendor X"}
+- {Concrete ask — e.g. "Intro to Acme's VP of Engineering"}
+
+---
+
+*Full design doc: {link} — sections {N, M} are most relevant if you want to dig in.*

skilldrop_cli/data/packs/stakeholder-comms/skills/guide-builder/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: guide-builder
+description: Turn raw notes, specs, or design material into an easy-to-follow guide, auto-styled to the content — a setup/quickstart, a design walkthrough, or an API/event-schema reference. Use when the user wants setup or getting-started instructions, an onboarding walkthrough of how a system works, or developer reference docs for an API or event schema — and it is NOT an SRE operational runbook (use runbook-generator) or a design proposal for review (use design-doc).
+---
+
+# guide-builder
+
+You help the user turn rough material — notes, a spec, an architecture description, an endpoint list — into a guide a reader can follow top-to-bottom without you in the room. This skill picks one of three styles from the content; it is **not** the SRE operational runbook (`runbook-generator`) and **not** a design proposal for review (`design-doc`). It explains and instructs; it does not propose or page.
+
+## How to respond
+
+1. **Detect the style first, and say which you picked.** Classify the input into exactly one of three styles using the table below. State the choice in one line with a one-clause why — *"Reading this as a **setup guide** (it's install + config steps); say the word if you wanted the design walkthrough."* — so the user can redirect before you draft.
+
+   | Style | Pick when the content is… | Signals in the input |
+   |---|---|---|
+   | **Setup guide** → [`templates/setup-guide.md`](templates/setup-guide.md) | install / configure / run something, step by step | "install", "set up", "getting started", prerequisites, env vars, `.env`, CLI commands, `docker`, "clone the repo" |
+   | **Design walkthrough** → [`templates/design-walkthrough.md`](templates/design-walkthrough.md) | explaining how an already-decided system works so someone can understand or build on it | components, data flow, "how X works", onboarding a new engineer, "why it's built this way" |
+   | **API reference** → [`templates/api-reference.md`](templates/api-reference.md) | contracts other developers code against | endpoints, request/response shapes, OpenAPI, event names, payload schemas, status codes, webhooks, Kafka/SNS topics, JSON Schema |
+
+2. **Handle mixed content by picking the dominant style, not blending.** If the input spans two styles (e.g. setup steps *and* the API they expose), lead with the dominant one and append the secondary as a clearly-labelled section or link out to a second guide. Only ask the user which to lead with if it's a genuine 50/50.
+
+3. **Gather only what the chosen style can't do without.** Don't run a generic intake. Cap at 2 questions, pick defaults for the rest:
+   - **Setup guide** needs the *target end state* ("running locally" vs "deployed to staging") and the *prerequisites baseline*. Without an end state, a setup guide has no finish line.
+   - **Design walkthrough** needs *who it's for* (new hire vs adjacent team) and *what they should be able to do after reading*.
+   - **API reference** needs the *transport + auth model* and *versioning scheme*. Without auth, the examples are unrunnable.
+
+   If the source is genuinely too thin, say so once and draft with gaps flagged as `> ⚠️ NEEDS INPUT: …` — don't invent.
+
+4. **Fill the matching template.** Each template is ordered the way a reader actually consumes it. Don't reorder sections to match the input's order; reorder the input to match the reader's path.
+
+5. **Apply the universal easy-to-follow rules** (these are the spine of every style):
+   - **One action per step.** Number them. No compound step hiding three commands behind one number.
+   - **Every step ends in a check.** "You should see `Listening on :3000`." A step with no success signal can't tell the reader whether to continue or stop.
+   - **Commands are complete and paste-able.** Real flags, not pseudocode. Placeholders are unmistakable (`<YOUR_API_KEY>`, never `your-key-here` buried mid-line) and listed once up front.
+   - **Lead each section with the outcome, not the backstory.** "By the end of this section the service answers on localhost." The "why" belongs in a walkthrough, not a quickstart.
+   - **Front-load the happy path.** Push edge cases, troubleshooting, and teardown to the end.
+
+## Useful references in this skill
+
+- [`templates/setup-guide.md`](templates/setup-guide.md) — install/configure/run, prerequisites → verify → troubleshooting.
+- [`templates/design-walkthrough.md`](templates/design-walkthrough.md) — mental model → components → flow → key decisions → where the code lives.
+- [`templates/api-reference.md`](templates/api-reference.md) — conventions → per-endpoint/event contracts → error catalog → changelog.
+- [`examples/local-setup-guide.md`](examples/local-setup-guide.md) — raw notes → a finished setup guide, showing the detection call and the verify-after-every-step discipline.
+
+## Quality bar
+
+- **A reader who follows top-to-bottom reaches the stated end state without leaving the doc for missing info.** Unstated prerequisites are the #1 failure — hunt them down.
+- **Every command block has an expected result or a verification step.** A command with no "how do I know it worked" is incomplete.
+- **Placeholders are unmistakable and listed once up front.** `<YOUR_API_KEY>`, not a real-looking string the reader pastes verbatim and wonders why it fails.
+- **No forward references that break linear reading.** "See step 7" before step 7 means the order is wrong, or it needs a link.
+- **API reference: every field has type + required/optional + a one-line meaning; every endpoint has ≥1 full example request and response, including at least one error response.**
+- **The detected style is stated up front with a one-line why,** so the user can redirect in one message instead of getting the wrong artifact.
+
+## When to use this skill
+
+- ✅ "Write setup instructions for getting our service running locally."
+- ✅ "Turn this architecture description into an onboarding walkthrough for new engineers."
+- ✅ "Document these endpoints / this event schema for the developers who'll consume them."
+- ✅ Converting messy notes or a spec into a doc someone can follow without you present.
+
+## When NOT to use this skill
+
+- ❌ SRE operational runbook — incidents, on-call escalation, deploy/rollback, SLOs → `runbook-generator`.
+- ❌ Proposing a design for review/approval — options, trade-offs, risks, rollout → `design-doc`.
+- ❌ Compressing a long doc for an exec audience → `exec-summary`.
+- ❌ Raw unstructured mess that isn't ready to shape (a transcript, a Slack thread) → run `brief-intake` first, then come back.
+
+## Anti-patterns to avoid
+
+- ❌ Compound steps. "Install deps, configure the DB, and run migrations" as one numbered step — split into three.
+- ❌ Commands with no expected output. The reader can't tell success from a silent failure.
+- ❌ Backstory before the first actionable step in a setup guide. Save the "why" for a walkthrough.
+- ❌ Documenting an API in prose ("it returns the user object") instead of a typed schema + example payload.
+- ❌ Blending two styles into one undifferentiated doc. Pick the dominant style; link or append the rest.
+- ❌ Optimistic examples that omit the error/failure responses an API consumer is required to handle.
+- ❌ Reinventing `runbook-generator` (incident playbooks, on-call) or `design-doc` (alternatives, approval) — stay in the explain-and-follow lane.
+- ❌ **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.

skilldrop_cli/data/packs/stakeholder-comms/skills/guide-builder/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Write setup instructions for getting our service running locally from these notes",
+    "should_trigger": true
+  },
+  {
+    "query": "Turn this architecture description into an onboarding walkthrough for new engineers",
+    "should_trigger": true
+  },
+  {
+    "query": "Document these webhook events and payloads for the developers who'll consume them",
+    "should_trigger": true
+  },
+  {
+    "query": "Make a quickstart guide out of this messy README",
+    "should_trigger": true
+  },
+  {
+    "query": "Write the on-call runbook with escalation and rollback for the billing service",
+    "should_trigger": false
+  },
+  {
+    "query": "Draft a design proposal with options and trade-offs for the new billing architecture",
+    "should_trigger": false
+  },
+  {
+    "query": "Summarize this 20-page spec for the executive team",
+    "should_trigger": false
+  },
+  {
+    "query": "Here's a raw Slack thread — structure it into a brief first",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/stakeholder-comms/skills/guide-builder/evals/evals.json

@@ -0,0 +1,18 @@
+{
+  "skill_name": "guide-builder",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Turn these notes into a guide for new engineers getting our Acme billing service running locally:\n\n- need docker + node 20\n- clone acme/billing, cp .env.example .env, set STRIPE_KEY to a test key\n- docker compose up -d postgres\n- npm ci then npm run migrate\n- npm run dev, it listens on 4000\n- if migrate fails it's usually postgres not up yet",
+      "assertions": [
+        "States the detected style (setup guide) up front with a one-line why and an invitation to redirect",
+        "Prerequisites are listed before the first step, and placeholders like <YOUR_STRIPE_TEST_KEY> are unmistakable and listed once up front",
+        "Each numbered step contains one action — 'npm ci then npm run migrate' is split into separate steps",
+        "Every command block is complete, paste-able, and followed by an expected result or verification (e.g. the service answers on port 4000)",
+        "Leads with the outcome rather than backstory, and pushes troubleshooting (migrate failing because postgres isn't up) to the end",
+        "No forward references that break top-to-bottom reading",
+        "Missing facts (e.g. the repo URL host or how to get a Stripe test key) are flagged as NEEDS INPUT rather than invented"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/stakeholder-comms/skills/guide-builder/examples/local-setup-guide.md

@@ -0,0 +1,127 @@
+# Example: raw notes → setup guide
+
+Shows the two things that make this skill earn its keep: the **style-detection call up front**, and the **verify-after-every-step** discipline that turns notes into something a stranger can follow.
+
+---
+
+## Input (what the user pasted)
+
+> need a getting-started doc for `widget-api`. it's a Go service, needs Postgres 15. clone, copy the env file (need a STRIPE_KEY from the dashboard), `make deps`, bring up postgres with docker, `make migrate`, then `make run`. it serves on 8080. there's a `/healthz`. people keep forgetting to start postgres first and then complain migrate hangs.
+
+## The skill's first line back (style detection)
+
+> Reading this as a **setup guide** — it's clone → configure → run with a defined finish line (`/healthz` answering). Two things I'm filling with defaults; correct me if wrong: end state is **running locally** (not deployed), and the prerequisite baseline assumes Go and Docker are already installed. Drafting now.
+
+## Output
+
+---
+
+# widget-api — Setup guide
+
+**Goal:** Run `widget-api` locally against a Dockerized Postgres and get a healthy response from `/healthz`.
+**Time:** ~10 minutes
+**You'll have at the end:** the API serving on `localhost:8080` with migrations applied.
+
+## Placeholders used in this guide
+
+| Placeholder | What to put | Where to get it |
+|---|---|---|
+| `<STRIPE_KEY>` | Stripe secret key for the test mode | Stripe Dashboard → Developers → API keys |
+
+## Prerequisites
+
+| Need | Version | Check it | If missing |
+|---|---|---|---|
+| Go | `>= 1.22` | `go version` | https://go.dev/dl |
+| Docker | any recent | `docker --version` | https://docs.docker.com/get-docker |
+| Postgres image | 15 | (pulled in step 3) | — |
+
+## Steps
+
+### 1. Clone the repo and enter it
+
+```bash
+git clone git@github.com:example/widget-api.git && cd widget-api
+```
+
+**You should see:** a `Makefile` in the directory — `ls Makefile`.
+
+### 2. Configure environment
+
+```bash
+cp .env.example .env
+# then set in .env:
+#   STRIPE_KEY=<STRIPE_KEY>
+```
+
+**You should see:** no placeholders left — `grep '<' .env` returns nothing.
+
+### 3. Start Postgres (do this before migrating)
+
+```bash
+docker compose up -d postgres
+```
+
+**You should see:** `docker compose ps` lists `postgres` as `healthy`. Wait for `healthy` before the next step — migrating against a not-yet-ready Postgres is what makes `make migrate` appear to hang.
+
+### 4. Install Go dependencies
+
+```bash
+make deps
+```
+
+**You should see:** `go mod download` completes with no errors.
+
+### 5. Run migrations
+
+```bash
+make migrate
+```
+
+**You should see:** `migrations applied: N` and a return to the prompt within a few seconds.
+
+### 6. Start the service
+
+```bash
+make run
+```
+
+**You should see:** `widget-api listening on :8080`.
+
+## Verify it works
+
+```bash
+curl -s localhost:8080/healthz
+```
+
+**Expected:** `{"status":"ok","db":"connected"}`
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `make migrate` hangs | Postgres not `healthy` yet | Re-check step 3; wait for `healthy`, then retry |
+| `connection refused :5432` | Postgres container not up | `docker compose up -d postgres` |
+| `/healthz` returns `db:"down"` | migrations not applied | run step 5 |
+
+## Teardown
+
+```bash
+docker compose down -v
+```
+
+Removes the Postgres container and its volume. Your `.env` is left intact.
+
+## Next steps
+
+- Run the tests: `make test`
+- Reference for the endpoints this service exposes: generate one with `/guide-builder` in **API reference** style.
+
+---
+
+### Why this passes the quality bar
+
+- **Every step ends in a check** — the reader never guesses whether to continue.
+- **The one gotcha from the notes** ("people forget to start postgres") became step 3's check *and* the first troubleshooting row, instead of buried prose.
+- **The single placeholder is listed once up front**, not left as a surprise mid-command.
+- **One end-to-end verify** (`/healthz`) proves the whole chain, not just the last command.

skilldrop_cli/data/packs/stakeholder-comms/skills/guide-builder/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "guide-builder",
+  "version": "0.1.1",
+  "description": "Turn raw notes, specs, or design material into an easy-to-follow guide, auto-styled to the content — a setup/quickstart, a design walkthrough, or an API/event-schema reference. Use when the user wants setup or getting-started instructions, an onboarding walkthrough of how a system works, or developer reference docs for an API or event schema — and it is NOT an SRE operational runbook (use runbook-generator) or a design proposal for review (use design-doc).",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["brief-intake", "design-doc", "exec-summary", "runbook-generator"],
+  "tags": ["guide", "setup", "documentation", "api-reference", "onboarding", "walkthrough"],
+  "model": { "tier": "standard", "rationale": "Shapes notes into a styled guide. Generation, not adversarial review." }
+}