total-dumb 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kayo Elias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/OyakSaile/im-dump-skill/main/assets/banner.png" alt="total-dumb — the /dumb agent skill explains what your AI is doing right now and why" width="860">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/npm-total--dumb-CB3837?logo=npm&logoColor=white" alt="npm package total-dumb">
+  <img src="https://img.shields.io/badge/node-%E2%89%A5%2018-5FA04E?logo=node.js&logoColor=white" alt="Node 18 or newer">
+  <img src="https://img.shields.io/badge/dependencies-0-4FD1C5" alt="zero dependencies">
+  <img src="https://img.shields.io/badge/license-MIT-A78BFA" alt="MIT license">
+</p>
+
+<p align="center">
+  <b>Your agent is three files deep into a story you never asked about. Type <code>/dumb</code>.</b>
+</p>
+
+---
+
+Coding agents are very good at doing the work and very bad at telling you why they are doing it. You watch a migration appear, a job get scheduled, a column get indexed, and the honest answer to "why this, now?" is somewhere in a story file you have not opened.
+
+`/dumb` is an [Agent Skill](https://agentskills.io) that answers that question from where you actually are. It reads the story, its epic and the code around the change, then gives you the step, the bigger picture, an analogy that maps, what a senior would watch for, and where the task resumes. In your language.
+
+It works in **Claude Code, Cursor, Codex and OpenCode**, installs with one command, and has zero runtime dependencies.
+
+## What it looks like
+
+You are mid-story. The migration just landed. You type `/dumb`:
+
+```
+🧠 What we're doing
+We wrote the `webhook_retries` migration for story 5.6: the table holding every
+failed payment webhook and when to retry it.
+
+🎯 Why (the bigger picture)
+5.6 belongs to Epic 5 (Payments): "a confirmed payment becomes a paid order,
+always". 5.3 (webhook) and 5.4 (idempotency) guarantee the confirmation arrives
+and is not processed twice, but not that it arrives at all if the order processor
+is down that second. Without retry a real payment vanishes, which is why 5.7
+(status screen) is blocked: you cannot show "paid" for something that can
+disappear. AC 2 fixes the shape: 1m → 5m → 25m → 2h, 5 attempts.
+
+🪄 Analogy
+A tracked parcel: if nobody answers, the carrier does not bin it; they leave a
+notice and come back at longer and longer intervals. After 5 attempts it goes to
+the depot (dead letter) and someone collects it.
+
+👀 Senior's eye
+- `next_attempt_at` needs an index: the job asks "what is due?" every minute.
+- Retry without 5.4's idempotency = double payment; reprocessing goes down the
+  same path.
+
+🤔 One question
+Why growing intervals instead of retrying every minute?
+
+➡️ Next step: the job that reads `next_attempt_at <= now()`.
+```
+
+Note what is *not* there: no lecture on what a migration is. Every line names something real from your task. That is the whole design constraint.
+
+## Install
+
+```bash
+npx total-dumb
+```
+
+It detects the agents you have, asks global or project, and copies the skill.
+
+```bash
+npx total-dumb -y                         # all detected agents, global
+npx total-dumb --project                  # into the current repo
+npx total-dumb --agents claude,codex -g   # pick agents
+npx total-dumb --uninstall                # remove it again
+npx total-dumb --dry-run                  # show what would happen, write nothing
+```
+
+Also available through the `skills` CLI:
+
+```bash
+npx skills add OyakSaile/im-dump-skill
+```
+
+## Three levels
+
+| You type | You get |
+|---|---|
+| `/dumb` | the six slots above, for a developer who wants the why (~250 words) |
+| `/dumb zero` | for someone who has never seen this before: the analogy carries it, every technical word glossed on first use, no senior section (~300 words) |
+| `/dumb terms` | just the vocabulary: 3 to 8 terms from this step, each with a concrete example from your task |
+
+Aliases: `eli5` and `beginner` for `zero`; `termos`, `jargon` and `glossary` for `terms`.
+
+You do not have to use the slash command. "why are we doing this?", "what is this for?", "I don't get it", "explain this step" all trigger it mid-task. Ask in any language and the answer comes back in it, headers included.
+
+## Where the "why" comes from
+
+It reads at most three files and stops as soon as it can be specific.
+
+- **BMAD projects** (`docs/stories/` exists): the story file, then its epic, then the PRD. That order fills the dependency chain first, which is why the example above knows that 5.7 is blocked.
+- **Everything else**: `README`, `docs/`, `ROADMAP`, ADRs, `PLAN`/`TODO`, `AGENTS.md`, then the code around the change.
+- **No planning docs at all**: it says so in one line, then reasons from the callers, the tests and the git history instead of inventing a rationale.
+
+If the motivation is weak or the step looks unnecessary, it says that too. Learning to judge the work is part of the point.
+
+## Where it gets installed
+
+| Agent | Project (`--project`) | Global (default) |
+|---|---|---|
+| Claude Code | `.claude/skills/dumb` | `~/.claude/skills/dumb` |
+| Cursor | `.agents/skills/dumb` | `~/.cursor/skills/dumb` |
+| Codex | `.agents/skills/dumb` | `~/.codex/skills/dumb` |
+| OpenCode | `.agents/skills/dumb` | `~/.config/opencode/skills/dumb` |
+
+`CLAUDE_CONFIG_DIR`, `CODEX_HOME` and `XDG_CONFIG_HOME` are honored.
+
+## How it was built
+
+Test-first, the same way you would build a feature. The scenario was run against a fixture repo by fresh subagents **without** the skill to establish a baseline, then again with it.
+
+The baseline answers were not wrong, they were shapeless: five of five runs produced a correct 322 to 382 word essay with no analogy, no pitfalls, no reflection question and no distinct next step. Every element the skill enforces exists because a real run dropped it, and three rounds of fixes each closed a failure that was actually observed rather than imagined.
+
+## License
+
+MIT © Kayo Elias

package/bin/cli.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { sep } from "node:path";
+import { stdin, stdout, stderr, exit } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { AGENTS, AGENT_IDS } from "../src/agents.mjs";
+import { parseArgs, USAGE } from "../src/args.mjs";
+import { detectAgents, install, normalizeAgents, resolveTargets, uninstall } from "../src/install.mjs";
+
+// Abbreviates a path under the user's home directory to "~", without mangling
+// paths that merely share a prefix with it (e.g. home /Users/kay, path /Users/kayoelias).
+function abbreviateHome(path, home = homedir()) {
+  if (path === home) return "~";
+  if (path.startsWith(home + sep)) return `~${path.slice(home.length)}`;
+  return path;
+}
+
+const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+
+let opts;
+try {
+  opts = parseArgs(process.argv.slice(2));
+} catch (error) {
+  stderr.write(`${error.message}\n\n${USAGE}`);
+  exit(1);
+}
+
+if (opts.help) { stdout.write(USAGE); exit(0); }
+if (opts.version) { stdout.write(`${pkg.version}\n`); exit(0); }
+
+const detected = detectAgents();
+let agents = detected;
+if (opts.agents) {
+  try {
+    agents = normalizeAgents(opts.agents);
+  } catch (error) {
+    stderr.write(`${error.message}\n`);
+    exit(1);
+  }
+}
+let scope = opts.scope ?? "global";
+
+const interactive = Boolean(stdin.isTTY) && !opts.yes;
+if (interactive) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    if (!opts.agents) agents = await askAgents(rl, detected);
+    if (!opts.scope) scope = await askScope(rl);
+  } finally {
+    rl.close();
+  }
+}
+
+if (agents.length === 0) {
+  const looked = AGENT_IDS.map((id) => abbreviateHome(AGENTS[id].configDir(process.env, homedir()))).join(", ");
+  stderr.write(
+    `No agents found (looked for ${looked}).\n` +
+    "Choose explicitly: npx total-dumb --agents claude,cursor,codex,opencode\n",
+  );
+  exit(1);
+}
+
+const targets = resolveTargets({ agents, scope });
+let results;
+try {
+  results = opts.uninstall
+    ? await uninstall(targets, { dryRun: opts.dryRun })
+    : await install(targets, { dryRun: opts.dryRun });
+} catch (error) {
+  stderr.write(`${error.message}\n`);
+  exit(1);
+}
+
+printSummary(results);
+exit(results.some((r) => r.status === "failed") ? 1 : 0);
+
+async function askAgents(rl, detected) {
+  stdout.write("\nWhich agents?\n");
+  AGENT_IDS.forEach((id, i) => {
+    stdout.write(`  ${i + 1}) ${AGENTS[id].displayName}${detected.includes(id) ? "  (detected)" : ""}\n`);
+  });
+  const fallback = detected.length ? detected : AGENT_IDS;
+  const suggested = fallback.map((id) => AGENT_IDS.indexOf(id) + 1).join(",");
+  const answer = await rl.question(`Numbers separated by commas [${suggested}]: `);
+  const picked = answer.split(",").map((n) => AGENT_IDS[Number(n.trim()) - 1]).filter(Boolean);
+  return picked.length ? AGENT_IDS.filter((id) => picked.includes(id)) : fallback;
+}
+
+async function askScope(rl) {
+  const answer = await rl.question("Where? (g)lobal for this machine, (p)roject for this repo [g]: ");
+  return answer.trim().toLowerCase().startsWith("p") ? "project" : "global";
+}
+
+function printSummary(results) {
+  const verb = opts.uninstall ? "Removed" : "Installed";
+  stdout.write(`\n${opts.dryRun ? "[dry-run] " : ""}${verb} the "dumb" skill:\n`);
+  for (const r of results) {
+    const names = r.agents.map((id) => AGENTS[id].displayName).join(", ");
+    const icon = r.status === "failed" ? "✖" : r.status === "skipped" ? "–" : "✔";
+    const where = abbreviateHome(r.path);
+    stdout.write(`  ${icon} ${names.padEnd(26)} ${where}  ${r.status}${r.error ? ` (${r.error})` : ""}\n`);
+  }
+  const didWrite = results.some((r) => r.status === "installed" || r.status === "updated");
+  if (!opts.uninstall && !opts.dryRun && didWrite) stdout.write("\nMid-task, type:  /dumb   /dumb zero   /dumb terms\n");
+}

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "total-dumb",
+  "version": "0.1.0",
+  "description": "Agent skill that explains what your AI is doing right now and why, with an analogy. One npx install for Claude Code, Cursor, Codex and OpenCode.",
+  "type": "module",
+  "bin": { "total-dumb": "bin/cli.mjs" },
+  "files": ["bin", "src", "skills", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node --test test/*.test.mjs" },
+  "keywords": ["agent-skills", "skill", "claude-code", "cursor", "codex", "opencode", "bmad", "mentor", "learn"],
+  "author": "Kayo Elias",
+  "license": "MIT"
+}

package/skills/dumb/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: dumb
+description: Use when the user invokes /dumb or, in the middle of any task (a BMAD story, a refactor, a bug fix, a migration, a config change), asks why the current step exists or what it is for — "why are we doing this?", "what is this for?", "I don't get it", "explain this step", "não entendi", "por que isso?", "explica". Optional level after the name — dev (default), zero, terms.
+---
+
+# dumb — explain the current step and its why
+
+## Overview
+
+The user is watching work happen and wants to understand it, not just get it done. Reply with a short explanation of what is being done right now and why it matters in the bigger picture, in the user's language, then say where the task resumes.
+
+Core principle: **specific beats correct-but-generic.** Every sentence names something real from this task (the story, the file, the table, the command). "What a migration is" fails; "why this migration must land before story 5.7" passes.
+
+## Steps
+
+1. **Pick the level and the language.** The level is the first word after `dumb` in the invocation, else a cue in the message, else `dev`. The language is the one the user writes in this conversation; when the invocation is too short to tell (`/dumb terms`), take it from the surrounding conversation and the project's docs. Every word of the answer is in that language, headers included.
+
+   | Level | Aliases | Reader |
+   |---|---|---|
+   | `dev` (default) | — | a developer who knows the basics and wants the why |
+   | `zero` | `eli5`, `beginner` | someone who has never seen anything like this |
+   | `terms` | `termos`, `jargon`, `glossary` | wants the vocabulary of this step |
+
+2. **Locate the bigger picture.** Read at most 3 files; stop as soon as every slot of the template can be filled with something specific.
+   - The conversation: what task is in flight and what was just done.
+   - If `docs/stories/` exists (BMAD): the current story file, then its epic file (`docs/epics/`, `docs/epic-*.md`, `docs/prd*.md`, `docs/architecture*.md`).
+   - Otherwise: `README*`, `docs/`, `ROADMAP*`, `docs/adr/`, `CHANGELOG*`, `PLAN*.md`, `TODO*.md`, `AGENTS.md`, `.claude/`.
+   - The code: what calls or depends on the thing being changed.
+   What to pull out of each source is in [references/context.md](references/context.md).
+   Nothing found? The answer opens with one line saying so, before the first section header ("No planning docs found; explaining from the code", in the user's language), then reasons from the code.
+
+3. **Fill the template for the level**, in the user's language (headers included). Templates and a worked example are in [references/levels.md](references/levels.md). The `dev` template is below.
+
+4. **Close with `➡️ Next step`** — one line naming where the task resumes. The explanation does not redo, re-run, or re-implement anything already done. If the task was already in progress and the user has not asked to pause, continue it after this line.
+
+## The `dev` template
+
+```
+🧠 What we're doing
+<1–2 sentences. Names the story / file / function / command being touched right now.>
+
+🎯 Why (the bigger picture)
+<At most 4 sentences: the goal this serves; where it sits (epic, roadmap,
+ dependency chain); what breaks or gets harder without it; why now and not later.>
+
+🪄 Analogy
+<2–3 sentences. One real-world analogy, each part mapped to one part of this step.>
+
+👀 Senior's eye
+<2 bullets, one sentence each: trade-offs or pitfalls a senior would watch for right here.>
+
+🤔 One question
+<One question the user can answer to check they got it. Omit if it would be forced.>
+
+➡️ Next step: <one line>
+```
+
+Length: about 250 words. Cut, do not compress.
+
+## When the task is a BMAD story, the "why" slot states
+
+- which epic the story belongs to and what the epic delivers;
+- which earlier stories it builds on;
+- which later stories are blocked by it;
+- the acceptance criterion that carries the motivation.
+
+This holds at `dev` and `zero`. At `zero` the same four facts are told in the analogy's terms ("the 5.7 screen cannot start until this exists"), not dropped.
+
+## Honesty
+
+If the motivation is weak, unclear, or the step looks unnecessary, the "why" slot says so. Learning to judge work is part of becoming a better developer.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Generic lecture ("migrations let you evolve the schema") | Name the table, the story, the story that depends on it |
+| Analogy that decorates instead of maps | Each part of the analogy = one part of the step; if it does not map, choose another |
+| Answering from the conversation alone when `docs/stories/` or a PRD exists | Read the story + its epic first |
+| Replying in English to a user who wrote in another language | Language comes from the conversation and the project's docs, not from the trigger message |
+| Reasoning from the code without saying the planning docs were missing | That line opens the answer, before the first section header |
+| Continuing to implement inside the explanation | The explanation ends at `➡️ Next step`; work resumes after it |
+| Past ~300 words at `dev` | Cut to ~250 for `dev`, ~300 for `zero`; the `🎯` slot is where the padding is |

package/skills/dumb/references/context.md

@@ -0,0 +1,26 @@
+# Where the bigger picture lives
+
+Read at most 3 files. Stop when every template slot can be filled with something specific.
+
+## Sources and what to extract
+
+| Source | Extract |
+|---|---|
+| The conversation | the task in flight; the file / command just touched; what the user already knows |
+| BMAD story file (`docs/stories/<n>.<m>.story.md`, `docs/stories/*<n>.<m>*`) | the "so that" clause; `Depende de` / `Bloqueia` (or `depends on` / `blocks`); the acceptance criterion behind the current task; which task is checked and which is next |
+| BMAD epic (`docs/epics/epic-<n>*.md`, `docs/epic-<n>*.md`, `docs/prd*.md` section) | the epic's goal in one sentence; the story list and its order (what comes before and after) |
+| PRD (`docs/prd*.md`) | the product goal the epic serves |
+| Architecture doc (`docs/architecture*.md`) | the technical design or constraint this step has to respect |
+| README | what the project is, in one sentence |
+| `docs/adr/*` | the decision and the reason that constrains this step |
+| ROADMAP / PLAN / TODO / `CHANGELOG*` files | where this item sits in the sequence |
+| `AGENTS.md`, `.claude/`, `CLAUDE.md` | project conventions the step follows |
+| The code | who calls the thing being changed; what breaks if it is wrong |
+
+## Layouts
+
+**BMAD** (`docs/stories/` exists): story file → its epic → PRD → architecture doc. That order fills the dependency chain first.
+
+**Generic**: README → `docs/` (ROADMAP, ADRs, PLAN, CHANGELOG) → the code around the change.
+
+**Nothing found**: say "No planning docs found; explaining from the code" (in the user's language) and derive the why from callers, tests, and the commit history (`git log --oneline -10 -- <path>`).

package/skills/dumb/references/levels.md

@@ -0,0 +1,82 @@
+# Levels — templates and a worked example
+
+Headers below are shown in English, the canonical form; render them in the user's language.
+
+## `dev` (default) — about 250 words
+
+```
+🧠 What we're doing
+<1–2 sentences. Names the story / file / function / command being touched right now.>
+
+🎯 Why (the bigger picture)
+<At most 4 sentences: the goal this serves; where it sits (epic, roadmap,
+ dependency chain); what breaks or gets harder without it; why now and not later.>
+
+🪄 Analogy
+<2–3 sentences. One real-world analogy, each part mapped to one part of this step.>
+
+👀 Senior's eye
+<2 bullets, one sentence each: trade-offs or pitfalls a senior would watch for right here.>
+
+🤔 One question
+<One question the user can answer to check they got it. Omit if it would be forced.>
+
+➡️ Next step: <one line>
+```
+
+## `zero` — about 300 words, the analogy carries the explanation
+
+```
+🪄 Analogy
+<3–4 sentences. The real-world analogy first; the rest of the answer refers back to it.>
+
+🧠 What we're doing
+<2–3 sentences. The step, told through the analogy; every technical word appears as
+ "term (plain-words meaning)" the first time.>
+
+🎯 Why (the bigger picture)
+<2–3 sentences: what goes wrong without it, in the analogy's terms, then in the
+ project's terms. On a BMAD story this slot still names the epic, the stories it
+ builds on and the story it blocks — in plain words, not numbers alone.>
+
+🤔 One question
+<One question answerable from the analogy.>
+
+➡️ Next step: <one line>
+```
+
+No `👀 Senior's eye` section at this level.
+
+## `terms` — 3 to 8 items, no analogy
+
+```
+📚 Terms in this step
+- **<term>** — <one-sentence meaning>. Here: <one concrete example from this task>.
+- ...
+
+➡️ Next step: <one line>
+```
+
+## Worked example (`dev`, BMAD story)
+
+Situation: story 5.6 "Retry with backoff for webhook delivery", the migration `webhook_retries` was just written, the user asks "why are we doing this story?".
+
+```
+🧠 What we're doing
+We wrote the `webhook_retries` migration for story 5.6: the table holding every failed payment webhook and when to retry it.
+
+🎯 Why (the bigger picture)
+5.6 belongs to Epic 5 (Payments): "a confirmed payment becomes a paid order, always". 5.3 (webhook) and 5.4 (idempotency) guarantee the confirmation arrives and is not processed twice, but not that it arrives at all if the order processor is down that second. Without retry a real payment vanishes, which is why 5.7 (status screen) is blocked: you cannot show "paid" for something that can disappear. AC 2 fixes the shape: 1m → 5m → 25m → 2h, 5 attempts.
+
+🪄 Analogy
+A tracked parcel: if nobody answers, the carrier does not bin it; they leave a notice and come back at longer and longer intervals. After 5 attempts it goes to the depot (dead letter) and someone collects it.
+
+👀 Senior's eye
+- `next_attempt_at` needs an index: the job asks "what is due?" every minute.
+- Retry without 5.4's idempotency = double payment; reprocessing goes down the same path.
+
+🤔 One question
+Why growing intervals instead of retrying every minute?
+
+➡️ Next step: the job that reads `next_attempt_at <= now()`.
+```

package/src/agents.mjs

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+
+export const SKILL_NAME = "dumb";
+
+// Where each agent looks for skills (verified against the `skills` CLI v1.7.0 registry).
+// Global scope is <configDir>/skills for all four; project scope is relative to the repo root.
+export const AGENTS = {
+  claude: {
+    displayName: "Claude Code",
+    aliases: ["claude-code"],
+    projectDir: ".claude/skills",
+    configDir: (env, home) => env.CLAUDE_CONFIG_DIR?.trim() || join(home, ".claude"),
+  },
+  cursor: {
+    displayName: "Cursor",
+    aliases: [],
+    projectDir: ".agents/skills",
+    configDir: (_env, home) => join(home, ".cursor"),
+  },
+  codex: {
+    displayName: "Codex",
+    aliases: [],
+    projectDir: ".agents/skills",
+    configDir: (env, home) => env.CODEX_HOME?.trim() || join(home, ".codex"),
+  },
+  opencode: {
+    displayName: "OpenCode",
+    aliases: [],
+    projectDir: ".agents/skills",
+    configDir: (env, home) => join(env.XDG_CONFIG_HOME?.trim() || join(home, ".config"), "opencode"),
+  },
+};
+
+export const AGENT_IDS = Object.keys(AGENTS);
+
+export function globalSkillsDir(id, env, home) {
+  return join(AGENTS[id].configDir(env, home), "skills");
+}

package/src/args.mjs

@@ -0,0 +1,43 @@
+export const USAGE = `Usage: npx total-dumb [options]
+
+Installs the "dumb" agent skill: /dumb explains what we're doing and why.
+
+Options:
+  -g, --global          install for the whole machine (default)
+  -p, --project         install into the current repository
+  -a, --agents <list>   comma-separated: claude, cursor, codex, opencode, all
+  -y, --yes             no prompts (all detected agents, global scope)
+      --uninstall       remove the skill instead of installing it
+      --dry-run         show what would happen, write nothing
+  -h, --help            show this help
+  -v, --version         show the version
+`;
+
+export function parseArgs(argv) {
+  const opts = { help: false, version: false, yes: false, scope: null, agents: null, uninstall: false, dryRun: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "-h": case "--help": opts.help = true; break;
+      case "-v": case "--version": opts.version = true; break;
+      case "-y": case "--yes": opts.yes = true; break;
+      case "-g": case "--global": opts.scope = "global"; break;
+      case "-p": case "--project": opts.scope = "project"; break;
+      case "--uninstall": opts.uninstall = true; break;
+      case "--dry-run": opts.dryRun = true; break;
+      case "-a": case "--agents": {
+        const value = argv[++i];
+        if (!value || value.startsWith("-")) throw new Error("--agents needs a value, e.g. --agents claude,codex");
+        opts.agents = value.split(",");
+        break;
+      }
+      default:
+        if (arg.startsWith("--agents=")) {
+          opts.agents = arg.slice("--agents=".length).split(",");
+          break;
+        }
+        throw new Error(`Unknown option "${arg}"`);
+    }
+  }
+  return opts;
+}

package/src/install.mjs

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { cp, mkdir, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AGENTS, AGENT_IDS, SKILL_NAME, globalSkillsDir } from "./agents.mjs";
+
+/** ["codex", "claude-code", "all"] → ["claude", "cursor", ...] in AGENT_IDS order. Throws on unknown names. */
+export function normalizeAgents(names) {
+  const picked = new Set();
+  for (const raw of names) {
+    const name = raw.trim().toLowerCase();
+    if (!name) continue;
+    if (name === "all") {
+      AGENT_IDS.forEach((id) => picked.add(id));
+      continue;
+    }
+    const id = AGENT_IDS.find((id) => id === name || AGENTS[id].aliases.includes(name));
+    if (!id) throw new Error(`Unknown agent "${raw}". Known: ${AGENT_IDS.join(", ")}, all`);
+    picked.add(id);
+  }
+  return AGENT_IDS.filter((id) => picked.has(id));
+}
+
+/** Agents whose config directory exists on this machine. */
+export function detectAgents({ env = process.env, home = homedir() } = {}) {
+  return AGENT_IDS.filter((id) => existsSync(AGENTS[id].configDir(env, home)));
+}
+
+/** One entry per distinct destination directory (Cursor, Codex and OpenCode share .agents/skills in a repo). */
+export function resolveTargets({ agents, scope, env = process.env, home = homedir(), cwd = process.cwd() }) {
+  const byPath = new Map();
+  for (const id of agents) {
+    const base = scope === "project" ? resolve(cwd, AGENTS[id].projectDir) : globalSkillsDir(id, env, home);
+    const path = join(base, SKILL_NAME);
+    if (!byPath.has(path)) byPath.set(path, { path, agents: [] });
+    byPath.get(path).agents.push(id);
+  }
+  return [...byPath.values()];
+}
+
+export const SKILL_SOURCE = resolve(dirname(fileURLToPath(import.meta.url)), "..", "skills", SKILL_NAME);
+
+/** Copy the skill into each target. Existing copies are replaced (status "updated"). */
+export async function install(targets, { source = SKILL_SOURCE, dryRun = false } = {}) {
+  if (!existsSync(join(source, "SKILL.md"))) {
+    throw new Error(`Skill files missing at ${source} (broken package?)`);
+  }
+  const results = [];
+  for (const target of targets) {
+    const status = existsSync(target.path) ? "updated" : "installed";
+    try {
+      if (!dryRun) {
+        await mkdir(dirname(target.path), { recursive: true });
+        await rm(target.path, { recursive: true, force: true });
+        await cp(source, target.path, { recursive: true });
+      }
+      results.push({ ...target, status });
+    } catch (error) {
+      results.push({ ...target, status: "failed", error: error.message });
+    }
+  }
+  return results;
+}
+
+/** Remove the skill directory from each target; never touches the parent. */
+export async function uninstall(targets, { dryRun = false } = {}) {
+  const results = [];
+  for (const target of targets) {
+    if (!existsSync(target.path)) {
+      results.push({ ...target, status: "skipped" });
+      continue;
+    }
+    try {
+      if (!dryRun) await rm(target.path, { recursive: true, force: true });
+      results.push({ ...target, status: "removed" });
+    } catch (error) {
+      results.push({ ...target, status: "failed", error: error.message });
+    }
+  }
+  return results;
+}