skilldrop-cli 0.2.0

package/skills/accessibility-audit/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: accessibility-audit
+description: Adversarially audit a UI (component code, page markup, screenshot, or flow) against WCAG 2.2 AA — findings cited to specific success criteria, centered on the user and assistive tech each one blocks, severity-tagged, with a concrete fix and what a scanner would miss. Use when the user wants an accessibility review, a11y audit, WCAG check, or to find what blocks screen-reader / keyboard / low-vision users before shipping.
+---
+
+# accessibility-audit
+
+Finds the barriers that lock real people out of a UI — and cites the exact success criterion, names the assistive tech that hits the wall, and separates what an automated scanner catches from what only a human with a screen reader will. The UI counterpart to `devils-advocate` (code), `doc-critique` (docs), and `threat-model` (designs): one adversarial pass, severity-tagged, evidence-first. Automated tools catch perhaps a third of WCAG issues; this audit is built for the other two thirds.
+
+## How to respond
+
+1. **Establish what's auditable from the input, and say what isn't.** Inputs vary in what they reveal:
+   - **Component/page code or markup** — the richest: roles, labels, semantics, focus management, tab order are all inspectable.
+   - **Screenshot/image** — visual only: contrast, target size, text-as-image, visible focus *if* captured. Keyboard behavior, screen-reader output, and focus order are **not** observable — list them as "must verify with live AT", never guess a pass.
+   - **A described flow** — reason about it, flag the checks that need the real thing.
+   Default standard is **WCAG 2.2 level AA**; note if the user wants A or AAA. State the input's coverage limits up front so a clean section never reads as a guarantee it can't be.
+
+2. **Sweep all four POUR principles** using the success-criterion catalog in [`reference.md`](reference.md) — Perceivable, Operable, Understandable, Robust. Don't transcribe the catalog; run it as a lens and report only what the UI actually fails or can't be verified for. The high-yield manual checks scanners miss, swept explicitly: **keyboard-only operability** (every interactive element reachable and operable, visible focus, no traps, logical order), **screen-reader semantics** (name/role/value, headings, landmarks, alt-text *quality* not just presence), **meaningful sequence and focus order**, **error identification and recovery**, **reflow/zoom to 400%**, **target size (2.2)**, and **motion/animation** preferences.
+
+3. **Center every finding on the user it blocks and the AT involved.** A finding without a victim is abstract. ✅ *"Submit button is a `<div>` with a click handler — keyboard users cannot reach or activate it (Tab skips it, Enter does nothing), and a screen reader announces nothing actionable. Blocks: keyboard-only and screen-reader users from completing checkout."* — ❌ *"Button not accessible."* Name the assistive tech (VoiceOver/NVDA/JAWS, keyboard-only, 400% zoom, switch control, reduced-motion) so the fix is testable.
+
+4. **Cite the specific success criterion** — number, name, level — for every finding: `1.4.3 Contrast (Minimum) [AA]`, `2.1.1 Keyboard [A]`, `4.1.2 Name, Role, Value [A]`, `2.4.7 Focus Visible [AA]`, `2.5.8 Target Size (Minimum) [AA]`. "Make it accessible" is not a finding; a criterion citation is what makes it actionable and arguable.
+
+5. **Severity-tag with the shared markers**, by impact on task completion:
+   - 🟥 **blocker** — a user group cannot complete the task at all (keyboard trap, unlabeled critical control, contrast that renders text unreadable, a form that can't be submitted via keyboard).
+   - 🟧 **major** — significant barrier with a painful workaround (poor focus order, vague link text, missing error association).
+   - 🟨 **minor** — friction, not a wall (redundant alt text, a non-essential decorative image with empty-but-present alt).
+   - ⚪ **nit** — best-practice polish.
+   If everything is a blocker, the severity call failed — calibrate to whether the task can actually be completed.
+
+6. **Compute contrast and sizes where the input allows it.** Given colors, state the actual ratio against the 4.5:1 (normal) / 3:1 (large) threshold: ✅ *"`#767676` on `#fff` = 4.54:1, passes AA for normal text by a hair; fails for the 14px placeholder which needs the same 4.5:1 and gets it — but `#999` on `#fff` = 2.85:1 fails."* Numbers, not eyeballing.
+
+7. **Separate scanner-catchable from human-only**, explicitly, per finding (tag `[auto]` vs `[manual]`). It tells the team what to gate in CI (axe/Lighthouse) and what needs the screen-reader pass that no tool replaces — and it's honest that the audit's manual findings are the ones a pipeline won't keep catching. End with a **"what's solid"** section (the patterns done right, so they're preserved on refactor) and a prioritized fix order.
+
+8. **Emit in one message**: coverage note (input limits), findings grouped by severity with SC citation + affected user/AT + `[auto]`/`[manual]` + concrete fix, contrast/size computations, what's solid, and the must-verify-with-live-AT checklist for anything the input couldn't confirm.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the WCAG 2.2 AA success-criterion catalog by POUR, the affected-user/assistive-tech map, the severity rubric, and the "what automated tools miss" list
+- [`examples/login-form.md`](examples/login-form.md) — worked example: a login form component audited to severity-tagged findings
+
+## Quality bar
+
+- **Every finding cites a specific success criterion** (number + name + level). Uncited "issues" are opinions.
+- **Every finding names the user group and assistive tech it blocks.** No victim, no finding.
+- **Severity reflects task-completion impact**, calibrated — not everything is a blocker, and a real keyboard trap is never a minor.
+- **Contrast and target-size claims are computed numbers** against the threshold, not visual guesses.
+- **Coverage limits are stated** and unverifiable checks are listed as must-test-with-AT, never silently passed. A screenshot audit never claims keyboard operability is fine.
+- **`[auto]` vs `[manual]` is tagged**, so CI-gateable findings are separated from the human-only ones.
+- **"What's solid" is present**, so good semantics survive the next refactor.
+
+## When to use this skill
+
+- ✅ Auditing a component, page, or flow against WCAG before shipping
+- ✅ "Is this accessible? / find the a11y issues" for real markup, a screenshot, or a flow
+- ✅ Pre-launch accessibility gate, or fixing a failed audit
+- ✅ Reviewing a design/screenshot for the accessibility issues catchable before build
+
+## When NOT to use this skill
+
+- ❌ Setting the accessibility *target* (which WCAG level, on which scope) — that's `nfr-spec`
+- ❌ General code correctness/security review — that's `devils-advocate`
+- ❌ Writing the component — fix findings in your normal build loop, or hand to `feature-implement-loop`
+- ❌ A full certified VPAT/conformance attestation — this audit feeds one, but legal sign-off is a formal process beyond a review
+
+## Anti-patterns to avoid
+
+- ❌ **"Make it accessible" findings.** Uncited, unactionable, unarguable. Every finding pins a success criterion.
+- ❌ **Faulting alt-text presence, not quality.** `alt="image"` passes a scanner and fails a human; `alt="chart"` on a data chart conveys nothing. Audit what the alt *says*.
+- ❌ **Claiming keyboard/SR passes from a screenshot.** You cannot see focus order or AT output in a PNG — list them as must-verify, don't invent a pass.
+- ❌ **Severity inflation.** Tagging a decorative-image nit as a blocker burns the credibility the real keyboard trap needs.
+- ❌ **Eyeballing contrast.** "Looks low" isn't a finding; "2.85:1, fails 4.5:1 AA" is.
+- ❌ **Scanner-only thinking.** Reporting only what axe would catch and calling it an audit — the two-thirds it misses (focus order, label accuracy, meaningful sequence, error recovery) is where users actually get stuck.
+- ❌ **Color as the only signal flagged once.** Reliance on color (1.4.1) shows up in status, charts, form errors, links-in-text — sweep every instance, not the first one.

package/skills/accessibility-audit/examples/login-form.md

@@ -0,0 +1,76 @@
+# Worked example — login form component → severity-tagged audit
+
+## Input (React component, verbatim)
+
+```jsx
+function LoginForm() {
+  const [err, setErr] = useState(false);
+  return (
+    <div className="login">
+      <div className="title" style={{fontSize: 22, fontWeight: 700}}>Sign in</div>
+      <input type="text" placeholder="Email" style={{color: '#999'}} />
+      <input type="password" placeholder="Password" />
+      {err && <span style={{color: 'red'}}>✕</span>}
+      <div className="btn" onClick={submit} style={{background:'#5b9', color:'#fff', padding:'6px 10px'}}>
+        Log in
+      </div>
+      <span className="link" onClick={forgot}>Forgot?</span>
+    </div>
+  );
+}
+```
+
+## Output
+
+### Coverage note
+Audited from component code: semantics, labels, roles, keyboard reachability, and contrast (from inline styles) are inspectable. Live focus-order and screen-reader output still need a real AT pass — flagged below.
+
+### 🟥 Blockers
+
+**A11Y-1 — Submit control is a `<div>`, unreachable and unoperable by keyboard** · `2.1.1 Keyboard [A]`, `4.1.2 Name, Role, Value [A]` · `[auto]`+`[manual]`
+A `<div onClick>` is not in the tab order, doesn't fire on Enter/Space, and exposes no button role or name to AT.
+Blocks: keyboard-only and screen-reader users from logging in at all — there is no other submit path.
+Fix: use `<button type="submit">Log in</button>` inside a `<form onSubmit>`. Same for `Forgot?` → `<button>` (or `<a href>` if it navigates).
+
+**A11Y-2 — Inputs have no programmatic label** · `3.3.2 Labels or Instructions [A]`, `1.3.1 Info and Relationships [A]`, `4.1.2 [A]` · `[auto]`
+Placeholders are not labels: they vanish on input and many screen readers don't announce them reliably. A screen-reader user hears "edit text, blank".
+Fix: add `<label htmlFor>` tied to each input (visible label preferred), or at minimum `aria-label`. Placeholders stay as hints, not the only label.
+
+### 🟧 Major
+
+**A11Y-3 — Error is conveyed by color and an icon glyph only, not associated with a field** · `1.4.1 Use of Color [A]`, `3.3.1 Error Identification [A]`, `4.1.3 Status Messages [AA]` · `[manual]`
+A red `✕` with no text tells a blind or color-blind user nothing about what failed or which field. It's also not announced (no live region) and not linked to an input.
+Blocks: blind users get no error info; color-blind users may miss the signal.
+Fix: render text ("Incorrect email or password"), associate via `aria-describedby` on the relevant input, and put the message in `role="alert"` so it's announced.
+
+**A11Y-4 — Email input text contrast fails AA** · `1.4.3 Contrast (Minimum) [AA]` · `[auto]`
+`#999` on `#fff` = **2.85:1**, below the 4.5:1 minimum for normal text. Low-vision users can't read typed input.
+Fix: darken to ≥ `#767676` (4.54:1) or darker.
+
+### 🟨 Minor
+
+**A11Y-5 — Submit button color contrast borderline / unverifiable focus ring** · `1.4.3 [AA]`, `2.4.7 Focus Visible [AA]` · `[auto]`+`[manual]`
+White text `#fff` on `#5b9` (`#55bb99`) = **2.35:1** — fails 4.5:1 for the button label. Also, once it's a real `<button>`, confirm a visible focus indicator exists (can't verify from static code).
+Fix: darken the button background to clear 4.5:1 — e.g. `#1f7a57` = 5.28:1 (`#2e8b6f` is only 4.17:1 and still fails, the classic "looks dark enough" trap) — and ensure a visible `:focus-visible` outline.
+
+### ⚪ Nits
+
+**A11Y-6 — Title is a styled `<div>`, not a heading** · `1.3.1 [A]`, `2.4.6 [AA]`
+Screen-reader users navigate by headings; a visual-only "Sign in" isn't in the outline.
+Fix: `<h1>` (or appropriate level) instead of `<div className="title">`.
+
+### What's solid
+- `type="password"` is correct (masking + manager integration).
+- Touch targets: padding gives the button adequate size once it's a real control — keep ≥ 24×24 (`2.5.8`).
+
+### Must verify with live AT
+- Focus **order** through the form (DOM order looks correct, but confirm).
+- Screen-reader announcement of the error live region after a failed submit.
+- Visible focus indicator on all controls (`2.4.7`) once they're focusable.
+- Behavior at 400% zoom / reflow (`1.4.10`).
+
+### Fix order
+1. A11Y-1, A11Y-2 (blockers — nobody can log in via AT).
+2. A11Y-3 (error semantics).
+3. A11Y-4, A11Y-5 (contrast — quick CSS).
+4. A11Y-6 (heading).

package/skills/accessibility-audit/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "accessibility-audit",
+  "version": "0.1.0",
+  "description": "Adversarially audit a UI (component code, page markup, screenshot, or flow) against WCAG 2.2 AA — findings cited to specific success criteria, centered on the user and assistive tech each one blocks, severity-tagged, with a concrete fix and what a scanner would miss. Use when the user wants an accessibility review, a11y audit, WCAG check, or to find what blocks screen-reader / keyboard / low-vision users before shipping.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": ["devils-advocate", "doc-critique", "feature-implement-loop", "nfr-spec", "threat-model"],
+  "tags": ["accessibility", "a11y", "wcag", "audit", "review", "inclusive-design"],
+  "model": { "tier": "heavy", "rationale": "Adversarial review against WCAG success criteria — cheaper models fault alt-text presence over quality, under-call severity, miss focus-order/name-role-value issues, and claim AT passes from screenshots. Never downgrade." }
+}

package/skills/accessibility-audit/reference.md

@@ -0,0 +1,69 @@
+# accessibility-audit reference — WCAG 2.2 AA catalog, AT map, severity, scanner gaps
+
+Run the catalog as a lens, not a transcript. Report only what the UI fails or what the input can't verify. Citations use the SC number + name + level.
+
+## The high-yield success criteria by POUR (WCAG 2.2, A + AA)
+
+### Perceivable
+- **1.1.1 Non-text Content [A]** — every image/icon/control has a text alternative; decorative images have empty alt; alt *says something useful* (not "image").
+- **1.3.1 Info and Relationships [A]** — structure conveyed visually is in the markup: headings are `<h*>`, lists are lists, labels are programmatically associated, tables have headers.
+- **1.3.2 Meaningful Sequence [A]** — DOM/reading order matches the intended order (CSS can lie; screen readers follow DOM).
+- **1.3.5 Identify Input Purpose [AA]** — inputs use `autocomplete` for known data (name, email).
+- **1.4.1 Use of Color [A]** — color is never the *only* way info is conveyed (errors, status, chart series, links in body text).
+- **1.4.3 Contrast (Minimum) [AA]** — text ≥ 4.5:1; large text (≥24px, or ≥19px bold) ≥ 3:1.
+- **1.4.4 Resize Text [AA]** / **1.4.10 Reflow [AA]** — usable at 200% text and 400% zoom with no loss of content/function, no horizontal scroll at 320px-equivalent.
+- **1.4.11 Non-text Contrast [AA]** — UI components and graphical objects (input borders, icons, focus rings) ≥ 3:1.
+- **1.4.12 Text Spacing [AA]** — no clipping when users override line/letter/word spacing.
+- **1.4.13 Content on Hover/Focus [AA]** — tooltips/popovers are dismissable, hoverable, persistent.
+
+### Operable
+- **2.1.1 Keyboard [A]** — all functionality available from the keyboard.
+- **2.1.2 No Keyboard Trap [A]** — focus can always move away.
+- **2.1.4 Character Key Shortcuts [A]** — single-key shortcuts can be turned off/remapped.
+- **2.4.3 Focus Order [A]** — tab order is logical and meaningful.
+- **2.4.4 Link Purpose [A]** — link text makes sense (no bare "click here"/"read more" islands).
+- **2.4.6 Headings and Labels [AA]** — descriptive; **2.4.7 Focus Visible [AA]** — a visible focus indicator on every focusable element.
+- **2.4.11 Focus Not Obscured (Minimum) [AA, new in 2.2]** — focused element isn't hidden behind sticky headers/footers.
+- **2.5.3 Label in Name [A]** — the accessible name contains the visible label text (voice control).
+- **2.5.7 Dragging Movements [AA, 2.2]** — drag actions have a single-pointer alternative.
+- **2.5.8 Target Size (Minimum) [AA, 2.2]** — targets ≥ 24×24 CSS px (or adequate spacing).
+
+### Understandable
+- **3.1.1 Language of Page [A]** — `lang` set.
+- **3.2.1 On Focus / 3.2.2 On Input [A]** — focus/input doesn't trigger surprise context changes.
+- **3.2.6 Consistent Help [A, 2.2]** — help mechanisms appear consistently.
+- **3.3.1 Error Identification [A]** — errors are described in text, programmatically associated with their field.
+- **3.3.2 Labels or Instructions [A]** — inputs have visible labels/instructions.
+- **3.3.3 Error Suggestion [AA]** — fixable errors offer a suggestion.
+- **3.3.7 Redundant Entry [A, 2.2]** / **3.3.8 Accessible Authentication (Minimum) [AA, 2.2]** — don't force re-entry; don't require a cognitive function test (e.g. solving a puzzle) with no alternative.
+
+### Robust
+- **4.1.2 Name, Role, Value [A]** — every UI component exposes a correct name, role, and state to AT (the #1 source of custom-widget failures).
+- **4.1.3 Status Messages [AA]** — dynamic status (toasts, validation, live results) announced via `role="status"`/`aria-live` without moving focus.
+
+## Affected-user / assistive-tech map (name the victim)
+
+| Barrier | Who it blocks | Tech that hits it |
+|---|---|---|
+| No keyboard access / trap / no focus ring | motor-impaired, power users, anyone without a mouse | keyboard-only, switch control |
+| Missing/wrong name-role-value, bad alt | blind, low-vision | VoiceOver, NVDA, JAWS |
+| Low contrast, color-only signal | low-vision, color-blind, sunlight/poor-screen users | screen magnifier, everyone outdoors |
+| No reflow / breaks at zoom | low-vision | 200–400% zoom, mobile |
+| Surprise context change, complex auth | cognitive, low-literacy, anxiety | all |
+| Tiny targets, drag-only | motor, tremor, touch | touch, switch, eye-tracking |
+| Unannounced dynamic updates | blind | screen readers |
+
+## Severity rubric (by task-completion impact)
+
+- 🟥 **blocker** — a group cannot complete the core task at all.
+- 🟧 **major** — significant barrier; a painful or non-obvious workaround exists.
+- 🟨 **minor** — friction or confusion, task still completable.
+- ⚪ **nit** — best practice / polish.
+
+Calibrate: a keyboard trap on the only submit path is 🟥; `alt` slightly verbose is ⚪. If everything is 🟥, recheck against "can the task be completed?"
+
+## What automated scanners catch vs miss (tag findings [auto] / [manual])
+
+**Caught by axe/Lighthouse [auto]** (~30–40% of issues): missing alt attribute, missing form label, low text contrast (computed), missing `lang`, duplicate IDs, ARIA attribute misuse, empty buttons/links, missing document title.
+
+**Human + AT only [manual]** (the majority): alt-text *quality*, label *accuracy* (right label on right field), logical focus *order*, meaningful reading sequence, keyboard *operability* of custom widgets, focus *visibility* in practice, error-recovery *usability*, whether color is the *only* signal, reflow at zoom, sensible heading *outline*, live-region *announcements* firing correctly, whether a context change is *surprising*. These don't stay fixed without a recurring manual pass — say so.

package/skills/adr-generator/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: adr-generator
+description: Generate an Architecture Decision Record (ADR) from a context-decision-consequences brief. Supports the two common formats — MADR (Markdown Any Decision Records) and Michael Nygard's original ADR template. Use whenever the user wants to capture an architectural decision, write an ADR, or document a "we decided X because Y" moment.
+---
+
+# adr-generator
+
+You help the user produce a clean, properly-numbered Architecture Decision Record.
+
+## How to respond
+
+1. **Pick the format.** Default to **MADR** (richer, has decision drivers + pros/cons per option). Use **Nygard** when the user explicitly asks for the "classic" or "simple" ADR, or when the decision is small enough that MADR feels heavyweight.
+
+2. **Gather the essentials.** Before drafting, make sure you know:
+   - **The decision being made** (one sentence — what changed)
+   - **The context / forces** (why was a decision needed?)
+   - **The options that were considered** (at least 2 — if only one option exists, this isn't really a decision)
+   - **Why the chosen option won** (the trade-off)
+
+   Ask at most 2 clarifying questions if essentials are missing. Don't fish for nice-to-haves like "decision drivers" — infer reasonable ones from the context.
+
+3. **Number it correctly.** ADRs are numbered sequentially starting at `0001`. Ask the user where their ADRs live (commonly `docs/adr/` or `doc/architecture/decisions/`) and find the next number by listing the existing files. If no ADRs exist yet, start at `0001`.
+
+4. **Pick the filename.** Use the slug form: `NNNN-short-title-in-kebab-case.md`. Examples:
+   - `0001-record-architecture-decisions.md`
+   - `0007-use-postgres-as-primary-datastore.md`
+   - `0014-adopt-event-driven-checkout.md`
+
+5. **Output.** Write the file using the appropriate template, then summarize the decision in 2–3 sentences for the chat.
+
+## Templates
+
+- [`templates/madr.md`](templates/madr.md) — MADR 3.0 format (recommended)
+- [`templates/nygard.md`](templates/nygard.md) — Nygard's original (simpler, 4 sections)
+
+## Quality bar
+
+- **Status** must be one of: `Proposed`, `Accepted`, `Deprecated`, `Superseded by ADR-NNNN`. Default to `Proposed` unless the user says it's already been agreed.
+- **Title is a noun phrase**, not a verb phrase. ✅ "Use Postgres as primary datastore" — ❌ "Decide what database to use".
+- **Consequences must include trade-offs, not just upsides.** If you can't list a downside, the decision wasn't real.
+- **Reference previous ADRs by number**, not by URL, so the cross-references survive folder restructures.
+- **Don't editorialize.** An ADR records what was decided, not what you (the AI) think was wisest.
+
+## Anti-patterns to avoid
+
+- ❌ Writing an ADR for a non-decision ("use industry best practices"). If the title could appear in a textbook, it's not a decision record.
+- ❌ Listing 6 options when only 2 were seriously considered. Cut the noise.
+- ❌ "Pros: it's better" with no "Cons:" line.
+- ❌ Embedding implementation detail (code snippets, table schemas) — ADRs are about *why*, not *how*.

package/skills/adr-generator/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "adr-generator",
+  "version": "0.1.0",
+  "description": "Generate an Architecture Decision Record (ADR) from a context-decision-consequences brief. Supports the two common formats — MADR (Markdown Any Decision Records) and Michael Nygard's original ADR template. Use whenever the user wants to capture an architectural decision, write an ADR, or document a \"we decided X because Y\" moment.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [],
+  "tags": ["adr", "documentation", "decisions", "architecture"],
+  "model": { "tier": "standard", "rationale": "Structures a decision into MADR/Nygard. Bounded judgment, not adversarial." }
+}

package/skills/adr-generator/templates/madr.md

@@ -0,0 +1,56 @@
+# {Short noun phrase — the decision, not the question}
+
+- Status: {Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](nnnn-...md)}
+- Date: {YYYY-MM-DD}
+- Deciders: {names or roles}
+- Tags: {comma-separated, optional}
+
+## Context and Problem Statement
+
+{Two to four sentences. What forces are at play? Why does a decision need to be made *now*? Use neutral language — the context is the same regardless of which option is chosen.}
+
+## Decision Drivers
+
+- {Driver — e.g. "must run on existing AWS estate"}
+- {Driver — e.g. "team has 5 years of Postgres expertise"}
+- {Driver — e.g. "must support 10k QPS at p99 < 50ms"}
+
+## Considered Options
+
+- {Option 1}
+- {Option 2}
+- {Option 3}
+
+## Decision Outcome
+
+Chosen option: **{Option N}**, because {one-sentence rationale tied to the decision drivers above}.
+
+### Consequences
+
+- ✅ {Positive — what becomes easier?}
+- ⚠️ {Trade-off — what's acceptable but worth noting?}
+- ❌ {Negative — what becomes harder or constrains future choices?}
+
+## Pros and Cons of the Options
+
+### {Option 1}
+
+- ✅ Good, because {reason}
+- ✅ Good, because {reason}
+- ❌ Bad, because {reason}
+
+### {Option 2}
+
+- ✅ Good, because {reason}
+- ❌ Bad, because {reason}
+- ❌ Bad, because {reason}
+
+### {Option 3}
+
+- ✅ Good, because {reason}
+- ❌ Bad, because {reason}
+
+## Links
+
+- {Related ADR — e.g. [ADR-0003](0003-...md)}
+- {External reference — e.g. RFC, vendor doc, benchmark}

package/skills/adr-generator/templates/nygard.md

@@ -0,0 +1,19 @@
+# {NNNN}. {Short noun phrase — the decision}
+
+Date: {YYYY-MM-DD}
+
+## Status
+
+{Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN](nnnn-...md)}
+
+## Context
+
+{What is the issue that we're seeing that is motivating this decision or change? Describe the forces at play, including technological, political, social, and project-local. Use value-neutral language.}
+
+## Decision
+
+{What is the change that we're actually proposing or doing?}
+
+## Consequences
+
+{What becomes easier or more difficult to do because of this change? List both positive and negative consequences. If you can't list a downside, you haven't thought hard enough.}

package/skills/ai-usage-report/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ai-usage-report
+description: Generate a per-user or team-level report on how AI tools are being used — volume, breadth, and effectiveness signals (e.g. whether AI outputs landed in shipped artifacts vs were generated and discarded). Consumes usage-event logs exported from an MCP server or other telemetry source. Use when a manager or team lead needs to understand AI adoption beyond raw counts — including spotting "AI theater" where people invoke AI to claim usage but don't act on the outputs.
+---
+
+# ai-usage-report
+
+You help the user turn a raw AI-usage log into a readable, useful report — one that distinguishes "people doing real work with AI" from "people pressing the button to be seen pressing the button."
+
+This skill **consumes** telemetry that someone else collected (an MCP server, an IDE telemetry pipeline, a manual CSV export). It does **not** collect the data itself. Your job is to:
+
+1. Take the input file from the user.
+2. Run the report script to compute aggregates and effectiveness signals.
+3. Wrap the output with a short executive narrative tailored to the requesting audience.
+
+## How to respond
+
+1. **Confirm three inputs** before generating anything:
+
+   - **Input file.** A CSV or JSONL of usage events. Schema lives in [`templates/usage-event-schema.md`](templates/usage-event-schema.md). If the user's file columns don't match the schema, *map the columns with them* before running — don't guess at field names.
+
+   - **Reporting period.** `week`, `month`, or explicit `--from <date> --to <date>`. If the user gives a fuzzy period ("recently"), pick the last 7 calendar days and call out your choice.
+
+   - **View.** Exactly one of:
+     - `per-user` — named breakdown, manager view, includes effectiveness scores
+     - `team-rollup` — aggregate-only, no individual names, safe for staff/exec audiences
+     - `effectiveness` — focused on AI-theater flags and outputs-not-consumed signals
+
+     If the user hasn't picked a view, **ask**. Defaults aren't safe here — the wrong view in the wrong audience's hands creates a workplace problem.
+
+2. **Call out what the data does NOT support before running.** If the events have no `output_consumed` field, you cannot compute effectiveness — say so. If `session_id` is missing, you cannot compute breadth-per-session. The report should not invent numbers it doesn't have evidence for. Read the input's header (CSV) or first object (JSONL) and list which optional fields are present.
+
+3. **Run the build script.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/build_report.py" /path/to/events.csv \
+     --view per-user --period week --out ./out/ai-usage-week.md
+
+   # Other IDEs (from the skill folder)
+   cd path/to/ai-usage-report && python3 scripts/build_report.py /path/to/events.csv \
+     --view per-user --period week --out ./out/ai-usage-week.md
+   ```
+
+   The script writes a markdown file using the matching template in `templates/`. Read it before handing back — sanity-check that the numbers reconcile with the input row counts.
+
+4. **Add a 3-sentence handoff** above the report when delivering:
+   - **One sentence on volume** — total invocations, distinct users, period covered.
+   - **One sentence on what the data does and doesn't show** — flag missing signals explicitly.
+   - **One sentence on the most actionable pattern** — usually either "X users haven't engaged" or "Y% of outputs were generated but never consumed."
+
+   Then the report itself.
+
+5. **Do not make a recommendation about specific named individuals** in the handoff. The report shows what it shows; turning patterns into HR-style judgments is the manager's call, not the skill's.
+
+## Useful references in this skill
+
+- [`templates/usage-event-schema.md`](templates/usage-event-schema.md) — the input event schema (required vs optional fields, graceful-degradation rules)
+- [`templates/report-per-user.md`](templates/report-per-user.md) — per-user named-report layout
+- [`templates/report-team-rollup.md`](templates/report-team-rollup.md) — aggregate team-level layout
+- [`examples/weekly-engineering-team.md`](examples/weekly-engineering-team.md) — worked example: stub events → both report views
+- [`scripts/build_report.py`](scripts/build_report.py) — the generator (stdlib only)
+
+## Effectiveness signals (what "performative vs effective" actually means here)
+
+The skill has **no magic classifier**. It exposes a set of signals the user interprets. Each signal is a column or counter in the report.
+
+| Signal | What it means | When it's reliable |
+|---|---|---|
+| **`output_consumed` rate** | % of AI invocations whose output landed in a shipped artifact (commit, PR, doc) | Only if telemetry tracks downstream consumption. If absent, this column is omitted, not faked. |
+| **Single-shot rate** | % of sessions with exactly one invocation and no follow-up | High single-shot + low effectiveness = a starting place to ask about engagement |
+| **Breadth** | Number of distinct tools/skills the user invoked | Low breadth + high volume = one-trick usage pattern |
+| **Session depth** | Avg invocations per session | High depth often correlates with iterative, engaged use |
+| **Output-to-shipped lag** | Median hours between AI invocation and artifact ship | Only meaningful if downstream consumption is tracked |
+| **Discard rate** | % of outputs explicitly rejected (IDE-level signal) | Requires IDE instrumentation; many sources lack this |
+
+**None of these signals is a verdict.** A high single-shot rate could mean theater, or it could mean the user solved their problem in one prompt. Low breadth could mean focused expertise. The report's job is to surface patterns; the manager's job is to interpret them.
+
+## Quality bar
+
+- **Numbers are computed from the input, not estimated.** If the script cannot compute a metric (missing field), the column is omitted with a note. Never fill with `~` or `est.` placeholders.
+- **Per-user reports include only users present in the input.** Don't infer missing users from elsewhere.
+- **The "AI theater" framing lives in section headers, not in per-user judgments.** Say "Single-shot rate: 87%" — never "Alice is doing AI theater."
+- **Privacy posture matches the view.** `per-user` names individuals; `team-rollup` never names anyone, even in passing.
+- **Recommendations target patterns, not people.** "Consider a deeper-engagement workshop for the team" — never "Coach Alice to engage more deeply."
+- **Period is explicit on the report header.** Every report shows the dates it covers.
+- **Sample size is honored.** If `n_users < 5` in a team-rollup, the report is no longer anonymous — refuse to generate the team-rollup view and tell the user why.
+
+## When to use this skill
+
+- ✅ A manager has a CSV/JSONL of AI usage events and wants a weekly/monthly read.
+- ✅ A team lead wants to spot adoption gaps without naming individuals.
+- ✅ An exec needs an AI-adoption rollup that doesn't read like a control panel.
+- ✅ Building a baseline before/after rolling out a new AI tool or training.
+
+## When NOT to use this skill
+
+- ❌ You don't have usage telemetry yet — the skill consumes data, doesn't collect it. See [[ai-usage-telemetry-design]] for the collection side.
+- ❌ You want to *judge* specific named people. The skill surfaces patterns; performance judgments based on AI usage are a different (and harder) decision.
+- ❌ The input lacks every effectiveness field. You can still produce a volume report, but call out the limitation explicitly — don't ship a report that looks like effectiveness analysis when it isn't.
+- ❌ Your team is < 5 people *and* the view is team-rollup. Aggregate views aren't anonymous at that size.
+
+## Anti-patterns to avoid
+
+- ❌ Inferring effectiveness from prompt length, prompt count, or session count alone. These measure *activity*, not *value*.
+- ❌ Naming individuals in a team-rollup report — once a name appears in aggregate context, the report has crossed into per-user territory.
+- ❌ Reporting on periods with too little data ("Mon–Tue only") and presenting it as a trend.
+- ❌ Faking effectiveness columns when the input lacks them. Omit, don't estimate.
+- ❌ Generating an "AI theater leaderboard" of named users. That's a workplace incident, not a report.
+- ❌ Embedding the input prompts verbatim in the report. Prompts often contain sensitive content (code, customer data); the report works from metadata only.
+- ❌ Comparing two periods that aren't normalized (e.g. a 7-day week against a 10-business-day window). If the script can't normalize, say so.

package/skills/ai-usage-report/examples/weekly-engineering-team.md

@@ -0,0 +1,133 @@
+# Example: Weekly engineering-team rollup
+
+A small synthetic event log demonstrating the three views — including graceful degradation when optional fields are missing and the privacy-floor refusal on `team-rollup` for small teams.
+
+## Input — `events.csv`
+
+```csv
+timestamp,user,tool,session_id,output_consumed,consumed_at,outcome
+2026-05-19T09:14:23Z,alice@acme.com,claude-code,sess-001,1,2026-05-19T11:02:00Z,success
+2026-05-19T09:14:55Z,alice@acme.com,claude-code,sess-001,1,2026-05-19T11:02:00Z,success
+2026-05-19T09:18:02Z,alice@acme.com,deck-builder,sess-001,1,2026-05-19T14:30:00Z,success
+2026-05-19T10:01:11Z,bob@acme.com,cursor,sess-014,0,,success
+2026-05-19T10:01:30Z,bob@acme.com,cursor,sess-015,0,,success
+2026-05-19T10:02:11Z,bob@acme.com,cursor,sess-016,0,,success
+2026-05-19T10:03:11Z,bob@acme.com,cursor,sess-017,0,,success
+2026-05-19T10:04:11Z,bob@acme.com,cursor,sess-018,0,,success
+2026-05-20T14:22:08Z,carol@acme.com,claude-code,sess-029,1,2026-05-22T08:11:00Z,success
+2026-05-20T15:22:08Z,carol@acme.com,adr-generator,sess-029,1,2026-05-22T08:11:00Z,success
+2026-05-20T16:22:08Z,carol@acme.com,design-doc,sess-030,1,2026-05-22T08:11:00Z,success
+2026-05-19T11:14:23Z,dan@acme.com,claude-code,sess-101,1,2026-05-19T13:00:00Z,success
+2026-05-19T11:15:23Z,dan@acme.com,claude-code,sess-101,0,,success
+2026-05-20T08:14:23Z,eve@acme.com,claude-code,sess-201,1,2026-05-20T09:00:00Z,success
+2026-05-20T08:15:23Z,eve@acme.com,claude-code,sess-201,1,2026-05-20T09:00:00Z,success
+2026-05-20T08:16:23Z,eve@acme.com,cursor,sess-202,1,2026-05-20T10:00:00Z,success
+```
+
+16 events, 5 users, 5 tools, period 2026-05-19 → 2026-05-20.
+
+## Generate the three views
+
+```bash
+# Per-user (manager view, names individuals)
+python3 scripts/build_report.py events.csv \
+  --view per-user --from 2026-05-18 --to 2026-05-21 \
+  --team-name "Acme Eng" -o out/per-user.md
+
+# Team-rollup (aggregate, no names, safe for skip-level/exec)
+python3 scripts/build_report.py events.csv \
+  --view team-rollup --from 2026-05-18 --to 2026-05-21 \
+  --team-name "Acme Eng" -o out/team-rollup.md
+
+# Effectiveness (per-user template, sorted by descending single-shot rate)
+python3 scripts/build_report.py events.csv \
+  --view effectiveness --from 2026-05-18 --to 2026-05-21 \
+  --team-name "Acme Eng" -o out/effectiveness.md
+```
+
+## Output — per-user view (excerpt)
+
+```markdown
+# AI Usage Report — Acme Eng
+
+**Period:** 2026-05-18 → 2026-05-21 (3 days)
+**Users in scope:** 5
+**Total invocations:** 16
+
+| User | Invocations | Sessions | Avg / session | Distinct tools | Effectiveness rate | Single-shot rate |
+|---|---:|---:|---:|---:|---:|---:|
+| alice@acme.com | 3 | 1 | 3.0 | 2 | 100% | 0% |
+| bob@acme.com | 5 | 5 | 1.0 | 1 | 0% | 100% |
+| carol@acme.com | 3 | 2 | 1.5 | 3 | 100% | 50% |
+| dan@acme.com | 2 | 1 | 2.0 | 1 | 50% | 0% |
+| eve@acme.com | 3 | 2 | 1.5 | 2 | 100% | 50% |
+```
+
+**Reading the data:**
+- **Alice** — 3 invocations in 1 session, all consumed, 2 tools. Deep, engaged use.
+- **Bob** — 5 invocations across 5 different sessions, 0% consumed, 1 tool only. **This is the AI-theater pattern**: high single-shot rate + low effectiveness + low breadth. Worth a conversation — *but the conversation, not the verdict.*
+- **Carol** — varied tools, mixed effectiveness. Healthy exploratory pattern.
+- **Dan** — small sample. Don't over-read.
+- **Eve** — engaged use, good breadth.
+
+## Output — team-rollup (excerpt)
+
+```markdown
+# AI Usage Rollup — Acme Eng
+
+| Metric | Value |
+|---|---:|
+| Invocations / user / day (median) | 1.0 |
+| Distinct tools per user (median) | 2 |
+| Effectiveness rate (team avg) | 62% |
+| Single-shot session rate (team avg) | 64% |
+| Active users (≥1 invocation in period) | 5 of 5 |
+
+| Engagement tier | Users | What it means |
+|---|---:|---|
+| **Heavy** (>20 invocations/week) | 0 | … |
+| **Moderate** (5–20 / week) | 4 | … |
+| **Light** (1–4 / week) | 1 | … |
+| **Inactive** (0 / week) | 0 | … |
+```
+
+No names appear. The "Bob is doing AI theater" insight is invisible from this view by design — if a manager needs that signal, they switch to `per-user` and take ownership of the privacy boundary.
+
+## Demonstrating graceful degradation
+
+If the input is missing optional fields, columns drop silently to `—`:
+
+```csv
+timestamp,user,tool
+2026-05-19T09:14:23Z,alice@acme.com,claude-code
+2026-05-19T09:14:55Z,alice@acme.com,claude-code
+```
+
+```markdown
+| User | Invocations | Sessions | Avg / session | Distinct tools | Effectiveness rate | Single-shot rate |
+| alice@acme.com | 2 | — | — | 1 | — | — |
+```
+
+The "Where signals are missing" section then explains *what* couldn't be computed and *why*.
+
+## Demonstrating the privacy floor
+
+With fewer than 5 users in scope, `team-rollup` refuses to generate:
+
+```
+$ python3 scripts/build_report.py small_team.csv --view team-rollup ...
+error: team-rollup requires ≥5 users in scope; got 3. Aggregate views aren't
+anonymous at that size. Use --view per-user and treat the output as identifying.
+```
+
+This is the contract — the tool won't be the one to anonymize-by-accident a team that's too small to be anonymous.
+
+## Hand-off to the user (what the agent would say)
+
+> Generated `out/per-user.md` — 5 users, 16 invocations, period 2026-05-19 to 2026-05-20.
+>
+> Two things to know before reading:
+> 1. **All optional signals were present**, so the report includes effectiveness and single-shot columns. The numbers are real, not estimated.
+> 2. **The most actionable pattern** is in the single-shot + effectiveness columns. One user shows 100% single-shot and 0% effectiveness — a starting place to ask about engagement, *not* a verdict on intent. The report flags the pattern; interpretation is yours.
+>
+> Want me to also produce the team-rollup view? It hides individual names and is safer for broader audiences.

package/skills/ai-usage-report/manifest.json

@@ -0,0 +1,11 @@
+{
+  "name": "ai-usage-report",
+  "version": "0.1.0",
+  "description": "Generate a per-user or team-level report on how AI tools are being used — volume, breadth, and effectiveness signals (e.g. whether AI outputs landed in shipped artifacts vs were generated and discarded). Consumes usage-event logs exported from an MCP server or other telemetry source. Use when a manager or team lead needs to understand AI adoption beyond raw counts — including spotting \"AI theater\" where people invoke AI to claim usage but don't act on the outputs.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [],
+  "tags": ["ai-usage", "reporting", "telemetry", "adoption", "observability", "manager-tools"],
+  "model": { "tier": "standard", "rationale": "Tabulates telemetry; the 'AI theater' effectiveness call needs some judgment." }
+}