progressive-explainer-cli 0.0.0-stage → 0.1.0

package/AGENTS.snippet.md

@@ -0,0 +1,7 @@
+## progressive-explainer
+
+When the user asks you to explain a topic, asks how something works, or asks for a document they will read to understand something, invoke the `progressive-explainer` skill and follow it: short first document, one running analogy, progress checklist at the end.
+
+When the user replies with a number from a progress checklist, invoke `progressive-explainer` again and cover that subtopic.
+
+Code changes, commits, pull requests and quick factual answers do not use this skill.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grégory Babonaux
+
+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

@@ -1,3 +1,95 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 🧭 progressive-explainer
+
+**English** · [Français](README.fr.md) · [Español](README.es.md) · [Deutsch](README.de.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [한국어](README.ko.md)
+
+🌐 [Website](https://gregorybabonaux.github.io/progressive-explainer/)
+
+**Explanations you can actually follow: a short overview first, then you pick what to dig into.**
+
+progressive-explainer is a skill for AI agents (Claude, Claude Code, Codex, Cursor and others). It changes how the agent explains things, not what it knows.
+
+## The problem
+
+Ask an AI agent how something works and you often get a wall of text: correct, complete, and impossible to follow if you have trouble with attention or focus. You lose the thread halfway, and the answer is wasted.
+
+## What it does
+
+The agent answers in two stages.
+
+**1. A short first document (250 to 400 words)**, always in the same order:
+
+| Part | What it gives you |
+|---|---|
+| One-sentence answer | The point, in under 20 words, before anything else |
+| The frame | What this is about, why it matters, who decides |
+| How it works | 2 to 4 short sections, with one analogy running through all of them |
+| A diagram, if useful | 5 elements at most, every arrow labelled |
+| One-sentence recap | Something you could repeat to someone else |
+
+**2. A progress checklist** that replaces the usual "want me to go deeper?":
+
+```markdown
+**Go further**
+
+🟢 easy · 🟡 intermediate · 🔴 advanced
+
+- [x] **1. Overview**: one thread for JS, slow work handed off, blocking 🟢
+- [ ] **2. What actually blocks**: which functions and patterns freeze the server? 🟢
+- [ ] **3. The `await` trap**: why can an `async` function still block everything? 🟢
+- [ ] **4. Execution order**: who goes first between Promise, `nextTick` and `setTimeout`? 🟡
+- [ ] **5. Worker threads**: how do you move a heavy computation off the main thread? 🟡
+- [ ] **6. Configuring the thread pool**: where and how do you add cooks? 🟡
+
+Reply with a number (or several).
+```
+
+Reply with a number: the agent covers that subtopic with the same rules and the same analogy, then ticks the box. You see your progress.
+
+A complete example: [`skills/progressive-explainer/references/example.md`](skills/progressive-explainer/references/example.md).
+
+## The main rules
+
+- **The conclusion comes first**, in every section, in bold. Reading only the headings and the bold text gives you the essentials.
+- **One analogy for the whole topic.** No juggling between three metaphors.
+- **No setting without its location.** If a setting is mentioned, the agent says which file or tool it lives in, and how to check it works.
+- **One number per point.** Names and sources go at the end, not in the middle of a sentence.
+- **Casual tone in the body, neutral headings.** No hook, no suspense, no filler.
+- **Your language.** The agent answers in the language you write in.
+
+The full rules are in [`SKILL.md`](skills/progressive-explainer/SKILL.md). Edit it to tune them.
+
+## Install
+
+**Step 1: install the skill (pick one)**
+
+| Where | Command | What you get |
+|---|---|---|
+| **Claude Code** (recommended) | `/plugin marketplace add GregoryBabonaux/progressive-explainer`, then `/plugin install progressive-explainer@progressive-explainer` | The skill and an `/explain <topic>` command |
+| **Any agent** (Codex, Cursor, Gemini CLI, Copilot, OpenCode…) | `npx skills add GregoryBabonaux/progressive-explainer` | The skill, in the project or globally with `-g` |
+| **No skills.sh** | `npx progressive-explainer-cli skills --yes` | The skill copied to `~/.agents/skills` and `~/.claude/skills` |
+| **Claude app** (claude.ai, desktop) | Download the [`skills/progressive-explainer`](skills/progressive-explainer) folder as a zip, then upload it in the Skills section of Claude's settings | The skill, available in every chat |
+
+**Step 2 (optional): use it for every explanation in a project**
+
+By default you call the skill when you want it (`/explain`, or "explain this progressively"). To make the agent use it whenever you ask for an explanation:
+
+- `npx progressive-explainer-cli init` shows what it will write. Nothing is written until you confirm.
+- `npx progressive-explainer-cli init --yes` adds the rule to `AGENTS.md` (and `CLAUDE.md` or `GEMINI.md` if your project uses them), between markers, without touching the rest of the file.
+
+**Step 3: check**
+
+```
+npx progressive-explainer-cli doctor
+```
+
+To update later: `npx progressive-explainer-cli update`, `claude plugin update progressive-explainer@progressive-explainer` or `npx skills update`, depending on how you installed it.
+
+## Credits
+
+Built from tests on real explanations, then compared with existing skills:
+- [patrick204nqh/skills](https://github.com/patrick204nqh/skills): the one-sentence answer, the single analogy and the recap come from `eli5`, the diagram rules from `diagram-it`.
+- [adhd-friendly-documentation](https://skillsmp.com/skills/rghamilton3-dotfiles-dot-claude-skills-adhd-friendly-documentation-skill-md): short paragraphs and the check before sending.
+
+## License
+
+MIT. Made by Grégory Babonaux.

package/bin/progressive-explainer.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+process.exitCode = await run(process.argv.slice(2), {
+  cwd: process.cwd(),
+  stdout: process.stdout,
+  stderr: process.stderr,
+  env: process.env,
+});

package/package.json

@@ -1,6 +1,32 @@
-{
-  "name": "progressive-explainer-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "progressive-explainer-cli",
+  "version": "0.1.0",
+  "description": "Installs progressive-explainer: the skill that turns AI explanations into a short overview plus a checklist to go deeper.",
+  "type": "module",
+  "bin": {
+    "progressive-explainer": "bin/progressive-explainer.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "AGENTS.snippet.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "prepack": "node ../scripts/bundle.mjs"
+  },
+  "keywords": ["skills", "agent-skills", "claude-code", "codex", "cursor", "explain", "adhd", "accessibility"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GregoryBabonaux/progressive-explainer.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/GregoryBabonaux/progressive-explainer#readme"
+}

package/skills/progressive-explainer/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: progressive-explainer
+description: Explains a topic, or writes a document someone has to understand, for a reader who loses focus in long or dense text. Short overview first, one running analogy, then a progress checklist the reader picks from to go deeper. Use when the user invokes /explain or progressive-explainer, asks for an explanation they can actually follow, or picks a number from a progress checklist this skill produced.
+license: MIT
+metadata:
+  version: "0.1.0"
+---
+
+# Progressive explainer
+
+The reader has trouble with attention and focus. A long or dense document makes them lose the thread, even when every sentence is correct. The goal: they understand the topic on the first read, then choose for themselves what to dig into.
+
+Principle: a short first document gives the big picture. Details come afterwards, one piece at a time, on request, through a progress checklist.
+
+Write in the language the user writes in. Address the reader informally (for example "tu" in French, "du" in German) unless the context clearly calls for formality.
+
+See `references/example.md` for a complete first document.
+
+## Before writing
+
+1. **Pick the analogy.** One only, from everyday life, that covers the whole topic. If none fits cleanly, use one concrete example instead.
+2. **List the subtopics** that will go into the final checklist, and sort them by difficulty.
+
+## Structure of the first document
+
+In this order:
+
+1. **The answer in one sentence.** Under 20 words, no jargon, in bold.
+2. **The frame.** Three short points: what this is about, why it matters, who decides or who uses it.
+3. **How it works**, in 2 to 4 sections. The analogy runs from start to finish.
+4. **A diagram**, only if a relationship is the heart of the topic (see the diagram rules below).
+5. **The one-sentence recap**, something the reader could repeat to someone else.
+6. **The progress checklist.**
+7. **Sources**, at the very end.
+
+Target length: 250 to 400 words, excluding code and the checklist. If the topic needs more, put the extra into the checklist instead of writing it.
+
+## Progress checklist
+
+It always ends the document.
+
+```markdown
+**Go further**
+
+🟢 easy · 🟡 intermediate · 🔴 advanced
+
+- [x] **1. Overview**: <what was just covered> 🟢
+- [ ] **2. <Title>**: <the question this subtopic answers> 🟢
+- [ ] **3. <Title>**: <question> 🟡
+- [ ] **4. <Title>**: <question> 🔴
+
+Reply with a number (or several).
+```
+
+Rules:
+- Sort from easiest to most advanced.
+- One line per subtopic: a bold title, then the question it answers.
+- Tick what has already been covered.
+- Include a "configuration" subtopic (where and how it is set) and a "diagnosis" subtopic (how to check it works) whenever the topic is technical and operational.
+- Never end with a yes/no question like "want me to dig into X?". The checklist replaces that question.
+
+## When the reader picks a number
+
+- Cover that subtopic with the same rules: one-sentence answer, conclusion first in each section, same analogy, same target length.
+- If several numbers are picked, cover them in order, each under its own heading.
+- End with the updated checklist, with the new boxes ticked. Add subtopics if the deeper dive reveals new ones.
+
+## Content rules
+
+- **One analogy, running through.** Do not switch analogies midway and do not stack several.
+- **Never mention a setting without saying where it is set.** Name the file, tool or screen, and explain how to check it works (command, metric, tab).
+- **One number per point at most**, the one that carries the message.
+- **Names and sources go at the end**, never in the body. They are there to source, not to understand.
+- **Short code examples** when something is configured, rather than a description.
+- **Unavoidable jargon is defined** in a few words the first time it appears. Technical terms stay in English (event loop, rollback, heartbeat...), even when writing in another language.
+
+## Diagram rules
+
+A diagram only if a relationship (flow, sequence, hierarchy, state transitions) is the heart of the explanation. Otherwise a sentence or a list is enough.
+
+- 5 elements at most, one idea per diagram.
+- Every arrow has a label.
+- The heading above the diagram states the conclusion, not the topic.
+- Mermaid by default, ASCII if rendering is not available.
+- 2 to 4 lines of text after the diagram say what it does not show.
+- No diagram for a comparison: use a table.
+
+## Form rules
+
+- **Informative, neutral headings.** "The 5 classic mistakes", not "The hall of horrors". The reader must be able to skim the document by its headings.
+- **The conclusion is the first sentence of each section**, in bold, then the explanation.
+- **Paragraphs of 2 or 3 lines**, one idea per sentence.
+- **Bullets start with a bold phrase.**
+- **Casual tone in the body**: informal address, spoken turns of phrase, a touch of humor when it helps. Headings stay neutral.
+- No hook, no suspense, no empty transition.
+- No condescension, no filler, no repeated "this is a simplification".
+- No em dash (—): use a comma, a period or a colon instead.
+
+## Check before sending
+
+- [ ] The first line answers the question in under 20 words.
+- [ ] The frame says what this is about, why it matters, who decides.
+- [ ] One analogy, present from start to finish.
+- [ ] Reading only the headings and the bold text gives the essentials.
+- [ ] Every setting mentioned says where it is set and how to check it.
+- [ ] No names in the body.
+- [ ] The document ends with the recap, the checklist, then the sources.
+- [ ] Under 400 words, excluding code and the checklist.

package/skills/progressive-explainer/references/example.md

@@ -0,0 +1,72 @@
+# Example: first document for "Node.js single thread"
+
+This is what a first document looks like when every rule is applied. Use it as a reference for shape and length, not as a template to copy word for word.
+
+---
+
+**Node runs your JavaScript on a single thread, and hands all the slow work to someone else.**
+
+## What this is about
+
+- **What:** the Node.js execution model. One single thread runs your code. A **thread** is a line of instructions the processor runs one after the other.
+- **Why it matters:** one greedy function is enough to freeze your whole server, along with every request in progress.
+- **Who decides:** Node manages the thread and the loop that feeds it, the **event loop**. You decide what you give it to run.
+
+## Your code goes through a single waiter
+
+**Only one line of your JS runs at any given moment.**
+
+Picture a restaurant with a single waiter. They take an order, pass it to the kitchen and move on to the next table without waiting for the dish. One waiter still serves the whole room, as long as they don't get stuck at one table.
+
+## Slow work goes to the kitchen
+
+**Network, disk and crypto do not go through your thread.**
+
+- **The network** (HTTP, database) is handled by the operating system.
+- **Files, DNS and crypto** go to the **thread pool**, a kitchen crew of 4 threads by default.
+
+So "single thread" only applies to your JS. Node itself uses several threads behind the scenes.
+
+**A finished dish waits until the waiter's hands are free.**
+
+```mermaid
+flowchart LR
+    R[Request] -->|arrives| T[JS thread]
+    T -->|hands off| C[Kitchen: OS and thread pool]
+    C -->|dish ready: callback queued| E[Event loop]
+    E -->|gives back to| T
+```
+
+The diagram does not show the priority order between waiting callbacks. Some jump the queue, and that is a topic of its own.
+
+## A long computation blocks the whole room
+
+**While your thread computes, no other request moves.**
+
+If the waiter starts peeling potatoes themselves, nobody gets served. In Node, that is a big `JSON.parse`, a loop over hundreds of thousands of items, or an `fs.readFileSync`.
+
+## In one sentence
+
+One waiter for your code, a kitchen for the slow work, and the whole room waits as soon as the waiter starts cooking.
+
+---
+
+**Go further**
+
+🟢 easy · 🟡 intermediate · 🔴 advanced
+
+- [x] **1. Overview**: one thread for JS, slow work handed off, blocking 🟢
+- [ ] **2. What actually blocks**: which functions and patterns freeze the server? 🟢
+- [ ] **3. The `await` trap**: why can an `async` function still block everything? 🟢
+- [ ] **4. Execution order**: who goes first between Promise, `nextTick` and `setTimeout`? 🟡
+- [ ] **5. Worker threads**: how do you move a heavy computation off the main thread? 🟡
+- [ ] **6. Configuring the thread pool**: where and how do you add cooks? 🟡
+- [ ] **7. Diagnosing a block**: how do you measure event loop delay and find the culprit? 🟡
+- [ ] **8. Several processes**: `cluster` and PM2 to use every core of the machine 🔴
+- [ ] **9. The starved loop**: how can microtasks stop I/O from getting through? 🔴
+
+Reply with a number (or several).
+
+---
+
+Sources: official Node.js documentation (event loop, libuv thread pool).

package/src/cli.js

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { runSkills } from './skills.js';
+import { runInit } from './init.js';
+import { runDoctor } from './doctor.js';
+import { runUpdate } from './update.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const VERSION = pkg.version;
+
+export function parseOptions(args) {
+  const o = { yes: false, dryRun: false, quiet: false, target: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--yes' || a === '-y') o.yes = true;
+    else if (a === '--dry-run') o.dryRun = true;
+    else if (a === '--quiet') o.quiet = true;
+    else if (a === '--target') o.target = args[++i] ?? null;
+  }
+  return o;
+}
+
+const HELP = `progressive-explainer ${VERSION}, explanations you can follow (short overview, one analogy, a checklist to go deeper)
+
+Usage: progressive-explainer <command> [options]
+
+  skills   install the skill into ~/.agents/skills and ~/.claude/skills [--target <dir>] [--yes]
+  init     add the explainer rule to AGENTS.md (and CLAUDE.md / GEMINI.md if the project uses them) [--yes]
+  doctor   check the installation [--quiet]
+  update   refresh skill copies and explainer rules installed by this CLI
+
+Nothing is written without --yes: without it, commands show what they would change.
+`;
+
+export async function run(argv, io) {
+  const [cmd, ...rest] = argv;
+  const opts = parseOptions(rest);
+  if (cmd === '--version' || cmd === '-v') { io.stdout.write(`${VERSION}\n`); return 0; }
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { io.stdout.write(HELP); return 0; }
+  try {
+    if (cmd === 'skills') return runSkills(io, opts, VERSION);
+    if (cmd === 'init') return runInit(io, opts, VERSION);
+    if (cmd === 'doctor') return runDoctor(io, opts, VERSION);
+    if (cmd === 'update') return runUpdate(io, opts, VERSION);
+  } catch (err) {
+    io.stderr.write(`progressive-explainer: ${err.message}\n`);
+    return 1;
+  }
+  io.stderr.write(`progressive-explainer: unknown command "${cmd}". Commands: skills, init, doctor, update\n`);
+  return 1;
+}

package/src/doctor.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { defaultTargets, STAMP } from './skills.js';
+import { gitRoot, TARGETS } from './init.js';
+import { hasBlock, blockVersion } from './writers.js';
+
+export function diagnose({ root, env, version }) {
+  const out = [];
+  const ok = (message) => out.push({ level: 'ok', message });
+  const warn = (message) => out.push({ level: 'warn', message });
+  ok(`progressive-explainer-cli ${version}`);
+
+  let skillFound = false;
+  for (const target of defaultTargets(env)) {
+    const dir = path.join(target, 'progressive-explainer');
+    if (!fs.existsSync(path.join(dir, 'SKILL.md'))) continue;
+    skillFound = true;
+    const stampFile = path.join(dir, STAMP);
+    if (!fs.existsSync(stampFile)) ok(`skill in ${target} (managed by another channel: plugin or skills.sh)`);
+    else {
+      const v = fs.readFileSync(stampFile, 'utf8').trim();
+      if (v === version) ok(`skill ${v} in ${target}`);
+      else warn(`skill ${v} in ${target}, CLI is ${version}: run progressive-explainer update`);
+    }
+  }
+  if (!skillFound) warn('no progressive-explainer skill in ~/.agents/skills or ~/.claude/skills: fine if installed in the project or by the Claude Code plugin, otherwise run progressive-explainer skills --yes');
+
+  if (!root) { warn('not inside a git repository: project checks skipped'); return out; }
+  for (const projectSkills of ['.agents/skills', '.claude/skills', '.cursor/skills', '.github/skills']) {
+    if (fs.existsSync(path.join(root, projectSkills, 'progressive-explainer', 'SKILL.md'))) ok(`skill in the project (${projectSkills})`);
+  }
+  let ruleFound = false;
+  for (const t of TARGETS) {
+    const file = path.join(root, t.file);
+    if (!fs.existsSync(file)) continue;
+    const text = fs.readFileSync(file, 'utf8');
+    if (!hasBlock(text)) {
+      if (t.always) ok(`${t.file} has no explainer rule (optional: run progressive-explainer init to use the skill for every explanation)`);
+      continue;
+    }
+    ruleFound = true;
+    const v = blockVersion(text);
+    if (v === version) ok(`explainer rule ${v} in ${t.file}`);
+    else warn(`explainer rule ${v ?? '(no version)'} in ${t.file}, CLI is ${version}: run progressive-explainer update`);
+  }
+  if (!ruleFound && !fs.existsSync(path.join(root, 'AGENTS.md'))) ok('no explainer rule in AGENTS.md (optional: run progressive-explainer init to use the skill for every explanation)');
+  return out;
+}
+
+export function runDoctor(io, opts, version) {
+  const results = diagnose({ root: gitRoot(io.cwd), env: io.env ?? process.env, version });
+  for (const r of results) {
+    if (r.level === 'ok' && opts.quiet) continue;
+    io.stdout.write(`${r.level === 'ok' ? '✓' : '!'} ${r.message}\n`);
+  }
+  return 0;
+}

package/src/init.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { snippetSource } from './paths.js';
+import { upsertBlock, toLf, matchEol } from './writers.js';
+
+const readOrNull = (p) => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null);
+
+export function gitRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return null; }
+}
+
+// Instruction files the explainer rule goes into. AGENTS.md is read by Codex, Cursor, Copilot,
+// OpenCode and most agents; CLAUDE.md and GEMINI.md only when the project already uses them.
+export const TARGETS = [
+  { file: 'AGENTS.md', always: true },
+  { file: 'CLAUDE.md', detect: ['CLAUDE.md', '.claude'] },
+  { file: 'GEMINI.md', detect: ['GEMINI.md', '.gemini'] },
+];
+
+export function ruleBody(version) {
+  const src = snippetSource();
+  if (!src) throw new Error('no bundled AGENTS.snippet.md found');
+  return `<!-- progressive-explainer ${version} -->\n${toLf(fs.readFileSync(src, 'utf8')).trim()}`;
+}
+
+export function selectTargets(root, only) {
+  return TARGETS.filter((t) => (only ? only.includes(t.file) : t.always || t.detect.some((p) => fs.existsSync(path.join(root, p)))));
+}
+
+// `only`: restrict to these files (used by update, which never adds new files).
+export function planInit(root, { version, only = null }) {
+  const body = ruleBody(version);
+  const changes = [];
+  for (const t of selectTargets(root, only)) {
+    const before = readOrNull(path.join(root, t.file));
+    const after = upsertBlock(before === null ? '' : toLf(before), body);
+    if (before !== null && toLf(before) === after) continue;
+    changes.push({ path: t.file, before, after: matchEol(before, after) });
+  }
+  return changes;
+}
+
+// Backups live under .git/ so they are never committed by accident.
+export function applyChanges(root, changes) {
+  const backupDir = path.join(root, '.git', 'progressive-explainer-backup');
+  for (const c of changes) {
+    if (c.before !== null) {
+      const backup = path.join(backupDir, c.path);
+      if (!fs.existsSync(backup)) {
+        fs.mkdirSync(path.dirname(backup), { recursive: true });
+        fs.writeFileSync(backup, c.before);
+      }
+    }
+    fs.writeFileSync(path.join(root, c.path), c.after);
+  }
+}
+
+export function runInit(io, opts, version) {
+  const root = gitRoot(io.cwd);
+  if (!root) { io.stderr.write('progressive-explainer: init must run inside a git repository\n'); return 1; }
+  const changes = planInit(root, { version });
+  if (!changes.length) { io.stdout.write('progressive-explainer: explainer rule already in place\n'); return 0; }
+  for (const c of changes) io.stdout.write(`${c.before === null ? '+ create' : '~ update'} ${c.path} (explainer rule between progressive-explainer markers)\n`);
+  if (!opts.yes || opts.dryRun) { io.stdout.write('progressive-explainer: nothing written yet, re-run with --yes to apply\n'); return 0; }
+  applyChanges(root, changes);
+  io.stdout.write(`progressive-explainer: explainer rule installed in ${changes.map((c) => c.path).join(', ')}\n`);
+  if (fs.existsSync(path.join(root, '.claude')) || fs.existsSync(path.join(root, 'CLAUDE.md'))) {
+    io.stdout.write('progressive-explainer: on Claude Code, the plugin also adds the /explain command: /plugin marketplace add GregoryBabonaux/progressive-explainer\n');
+  }
+  return 0;
+}

package/src/paths.js

@@ -0,0 +1,16 @@
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// In the repository (cli/ next to skills/), the live files win over a stale bundled copy.
+// In the npm package, prepack has bundled skills/ and AGENTS.snippet.md into cli/.
+const inRepo = () => fs.existsSync(fileURLToPath(new URL('../../.claude-plugin/plugin.json', import.meta.url)));
+
+function pick(repoRel, bundledRel) {
+  const repo = fileURLToPath(new URL(repoRel, import.meta.url));
+  const bundled = fileURLToPath(new URL(bundledRel, import.meta.url));
+  const candidates = inRepo() ? [repo, bundled] : [bundled, repo];
+  return candidates.find((p) => fs.existsSync(p)) ?? null;
+}
+
+export const skillsSource = () => pick('../../skills', '../skills');
+export const snippetSource = () => pick('../../AGENTS.snippet.md', '../AGENTS.snippet.md');

package/src/skills.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { skillsSource } from './paths.js';
+
+export const STAMP = '.progressive-explainer-version';
+
+export function listSkills(dir) {
+  return fs.readdirSync(dir).filter((d) => fs.existsSync(path.join(dir, d, 'SKILL.md'))).sort();
+}
+
+// ~/.agents/skills is read by Codex, Copilot CLI, Gemini CLI, Cursor and OpenCode; ~/.claude/skills by Claude Code.
+export function defaultTargets(env) {
+  const home = env.PROGRESSIVE_EXPLAINER_HOME || os.homedir();
+  return [path.join(home, '.agents', 'skills'), path.join(home, '.claude', 'skills')];
+}
+
+// install: not there yet; update: installed by this CLI, older version; skip: managed by another channel.
+export function planSkills({ source, targets, version }) {
+  const actions = [];
+  for (const target of targets) {
+    for (const skill of listSkills(source)) {
+      const dest = path.join(target, skill);
+      const stampFile = path.join(dest, STAMP);
+      if (!fs.existsSync(dest)) actions.push({ skill, target, dest, action: 'install' });
+      else if (!fs.existsSync(stampFile)) actions.push({ skill, target, dest, action: 'skip' });
+      else if (fs.readFileSync(stampFile, 'utf8').trim() !== version) actions.push({ skill, target, dest, action: 'update' });
+    }
+  }
+  return actions;
+}
+
+export function applySkills(actions, source, version) {
+  for (const a of actions) {
+    if (a.action === 'skip') continue;
+    fs.rmSync(a.dest, { recursive: true, force: true });
+    fs.mkdirSync(path.dirname(a.dest), { recursive: true });
+    fs.cpSync(path.join(source, a.skill), a.dest, { recursive: true });
+    fs.writeFileSync(path.join(a.dest, STAMP), `${version}\n`);
+  }
+}
+
+export function runSkills(io, opts, version) {
+  const source = skillsSource();
+  if (!source) { io.stderr.write('progressive-explainer: no bundled skills found\n'); return 1; }
+  const targets = opts.target ? [opts.target] : defaultTargets(io.env ?? process.env);
+  const actions = planSkills({ source, targets, version });
+  for (const a of actions.filter((x) => x.action === 'skip')) {
+    io.stderr.write(`progressive-explainer: ${a.skill} in ${a.target} is managed elsewhere (no ${STAMP}), left untouched\n`);
+  }
+  const work = actions.filter((a) => a.action !== 'skip');
+  if (!work.length) { io.stdout.write('progressive-explainer: skills already up to date\n'); return 0; }
+  for (const a of work) io.stdout.write(`${a.action === 'install' ? '+ install' : '~ update'} ${a.skill} → ${a.target}\n`);
+  if (!opts.yes || opts.dryRun) { io.stdout.write('progressive-explainer: re-run with --yes to apply\n'); return 0; }
+  applySkills(work, source, version);
+  io.stdout.write(`progressive-explainer: installed ${work.length} skill cop${work.length === 1 ? 'y' : 'ies'}\n`);
+  return 0;
+}
+
+// Used by `update`: refresh only copies this CLI installed (stamped), never install new ones.
+export function refreshStampedSkills(env, version) {
+  const source = skillsSource();
+  if (!env || !source) return 0;
+  const updates = planSkills({ source, targets: defaultTargets(env), version }).filter((a) => a.action === 'update');
+  applySkills(updates, source, version);
+  return updates.length;
+}

package/src/update.js

@@ -0,0 +1,33 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { refreshStampedSkills } from './skills.js';
+import { gitRoot, planInit, applyChanges, TARGETS } from './init.js';
+import { hasBlock } from './writers.js';
+
+const CHANNELS = [
+  'progressive-explainer: copies installed by another channel are updated there:\n',
+  '  claude plugin update progressive-explainer@progressive-explainer   (Claude Code plugin)\n',
+  '  npx skills update                                      (skills.sh)\n',
+];
+
+export function runUpdate(io, opts, version) {
+  // skill copies first: they live in the home directory and need no repository
+  const refreshed = refreshStampedSkills(io.env ?? process.env, version);
+  if (refreshed) io.stdout.write(`progressive-explainer: refreshed ${refreshed} skill cop${refreshed === 1 ? 'y' : 'ies'}\n`);
+
+  const root = gitRoot(io.cwd);
+  // only refresh files that already carry the block: never install by surprise
+  const only = root ? TARGETS.map((t) => t.file).filter((f) => {
+    const p = path.join(root, f);
+    return fs.existsSync(p) && hasBlock(fs.readFileSync(p, 'utf8'));
+  }) : [];
+  if (!only.length) {
+    io.stdout.write('progressive-explainer: no explainer rule in this repository, run progressive-explainer init to add one\n');
+  } else {
+    const changes = planInit(root, { version, only });
+    applyChanges(root, changes);
+    io.stdout.write(`progressive-explainer: explainer rule ${changes.length ? `updated in ${changes.map((c) => c.path).join(', ')}` : 'already up to date'}\n`);
+  }
+  for (const line of CHANNELS) io.stdout.write(line);
+  return 0;
+}

package/src/writers.js

@@ -0,0 +1,28 @@
+export const toLf = (text) => text.replace(/\r\n/g, '\n');
+
+// Write `after` with the line endings `before` already uses (a CRLF checkout stays CRLF).
+export function matchEol(before, after) {
+  return before !== null && before.includes('\r\n') ? toLf(after).replace(/\n/g, '\r\n') : after;
+}
+
+export const START = '<!-- progressive-explainer:start -->';
+export const END = '<!-- progressive-explainer:end -->';
+
+export function hasBlock(text) {
+  const i = text.indexOf(START);
+  return i !== -1 && text.indexOf(END, i + 1) !== -1;
+}
+
+// Replace the managed block if present, otherwise append it. Text outside the markers is never touched.
+export function upsertBlock(text, body) {
+  const block = `${START}\n${body}\n${END}`;
+  const i = text.indexOf(START);
+  const j = i === -1 ? -1 : text.indexOf(END, i + 1);
+  if (i !== -1 && j !== -1) return text.slice(0, i) + block + text.slice(j + END.length);
+  if (!text) return `${block}\n`;
+  return `${text}${text.endsWith('\n') ? '' : '\n'}\n${block}\n`;
+}
+
+export function blockVersion(text) {
+  return text.match(/<!-- progressive-explainer (\d+\.\d+\.\d+) -->/)?.[1] ?? null;
+}