@smitdev/ai-skills 0.1.0 → 0.3.0

package/README.md

@@ -14,7 +14,8 @@ No global install needed — run it with `npx`:
 # See what's available
 npx @smitdev/ai-skills list
 
-# Interactive: pick assistant(s) and skill(s)
+# Interactive: pick assistant(s) and skill(s) with the keyboard
+#   ↑/↓ move · space or tab toggle · a select all · enter confirm
 npx @smitdev/ai-skills install
 
 # Non-interactive examples
@@ -43,6 +44,11 @@ Use `--dry-run` to preview without writing anything.
 
 - **contract** — Create a build-ready spec / PRD for a feature before any code
   is written, so a coding assistant can build it without guessing.
+- **understand** — Read a whole codebase and write a connected set of
+  plain-language docs (a map plus one doc per aspect) to onboard fast.
+- **gistly** — Answer a question so it's correct, dense, and easy to hold in
+  your head: the answer first, the mental model that makes it stick, fewest
+  tokens it honestly needs.
 
 ## Authoring your own skills
 

package/bin/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 'use strict';
 
-const readline = require('readline');
 const path = require('path');
 const { listSkills } = require('../lib/skills');
 const { adapters } = require('../lib/adapters');
 const { install } = require('../lib/install');
+const { multiselect, select } = require('../lib/prompt');
 
 const ASSISTANT_IDS = Object.keys(adapters);
 
@@ -31,10 +31,6 @@ function parseArgs(argv) {
   return args;
 }
 
-function ask(rl, question) {
-  return new Promise((resolve) => rl.question(question, (a) => resolve(a.trim())));
-}
-
 function parseList(val, valid) {
   if (val === true || !val) return [];
   const items = String(val)
@@ -55,6 +51,8 @@ Usage:
 Commands:
   list                 List the skills bundled in this package
   install              Install skills for one or more assistants
+                       (run with no flags for an interactive picker:
+                        ↑/↓ move · space/tab toggle · a all · enter confirm)
 
 Options for "install":
   --assistant <ids>    Comma-separated: ${ASSISTANT_IDS.join(', ')} (or "all")
@@ -73,20 +71,6 @@ Examples:
 `);
 }
 
-async function pickFromList(rl, label, options) {
-  console.log(`\n${label}`);
-  options.forEach((o, i) => console.log(`  ${i + 1}. ${o.label}`));
-  console.log(`  (comma-separated numbers, or "a" for all)`);
-  const ans = await ask(rl, '> ');
-  if (ans.toLowerCase() === 'a' || ans === '') return options.map((o) => o.id);
-  const picked = ans
-    .split(',')
-    .map((s) => parseInt(s.trim(), 10))
-    .filter((n) => n >= 1 && n <= options.length)
-    .map((n) => options[n - 1].id);
-  return [...new Set(picked)];
-}
-
 async function runInstall(args) {
   const skills = listSkills();
   if (skills.length === 0) {
@@ -98,31 +82,43 @@ async function runInstall(args) {
     typeof args.flags.dir === 'string' ? args.flags.dir : process.cwd()
   );
   const dryRun = !!args.flags['dry-run'];
-  const scope = args.flags.global ? 'global' : 'project';
+  const scopeFlagged = !!args.flags.global || !!args.flags.project;
+  let scope = args.flags.global ? 'global' : 'project';
 
   let assistants = parseList(args.flags.assistant, ASSISTANT_IDS);
   let skillNames = parseList(args.flags.skill, skills.map((s) => s.name));
 
-  const nonInteractive =
-    args.flags.yes || (assistants.length > 0);
+  const nonInteractive = args.flags.yes || assistants.length > 0;
 
   if (!nonInteractive && process.stdin.isTTY) {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     if (assistants.length === 0) {
-      assistants = await pickFromList(
-        rl,
-        'Which assistant(s)?',
-        ASSISTANT_IDS.map((id) => ({ id, label: adapters[id].label }))
-      );
+      assistants = await multiselect({
+        title: 'Which assistant(s)? (Claude Code, Copilot, Cursor, Windsurf)',
+        options: ASSISTANT_IDS.map((id) => ({ id, label: adapters[id].label })),
+        initial: ['claude'],
+      });
     }
     if (skillNames.length === 0) {
-      skillNames = await pickFromList(
-        rl,
-        'Which skill(s)?',
-        skills.map((s) => ({ id: s.name, label: `${s.name} — ${truncate(s.description, 60)}` }))
-      );
+      skillNames = await multiselect({
+        title: 'Which skill(s)?',
+        options: skills.map((s) => ({
+          id: s.name,
+          label: `${s.name} — ${truncate(s.description, 60)}`,
+        })),
+        initial: skills.map((s) => s.name),
+      });
+    }
+    // Only Claude Code supports a global scope; ask when relevant.
+    if (!scopeFlagged && assistants.includes('claude')) {
+      scope = await select({
+        title: 'Install scope for Claude Code?',
+        options: [
+          { id: 'project', label: 'This project  (./.claude/skills)' },
+          { id: 'global', label: 'Global         (~/.claude/skills, available everywhere)' },
+        ],
+        initial: 'project',
+      });
     }
-    rl.close();
   }
 
   if (assistants.length === 0) assistants = ASSISTANT_IDS.slice();

package/lib/prompt.js

@@ -0,0 +1,185 @@
+'use strict';
+
+const readline = require('readline');
+
+// Tiny zero-dependency interactive prompts (checkbox + radio) built on
+// readline keypress events. Falls back to nothing in non-TTY environments —
+// callers should guard with process.stdin.isTTY.
+
+const useColor = !!process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+const dim = paint('2');
+const bold = paint('1');
+const cyan = paint('36');
+const green = paint('32');
+
+function setupKeys() {
+  const input = process.stdin;
+  readline.emitKeypressEvents(input);
+  if (input.isTTY) input.setRawMode(true);
+  input.resume();
+  return input;
+}
+
+function teardownKeys(input, onKey) {
+  input.removeListener('keypress', onKey);
+  if (input.isTTY) input.setRawMode(false);
+  input.pause();
+}
+
+function hideCursor() {
+  if (useColor) process.stdout.write('\x1b[?25l');
+}
+function showCursor() {
+  if (useColor) process.stdout.write('\x1b[?25h');
+}
+
+/**
+ * Multi-select checkbox prompt.
+ *   options: [{ id, label }]
+ *   initial: array of pre-selected ids
+ * Resolves to an array of selected ids (in option order). Always returns at
+ * least one (the highlighted item) so callers never get an empty selection.
+ */
+function multiselect({ title, options, initial }) {
+  return new Promise((resolve) => {
+    const selected = new Set(initial || []);
+    let cursor = 0;
+    let rendered = 0;
+    const output = process.stdout;
+
+    const hint = dim(
+      '↑/↓ move · space/tab toggle · a all · enter confirm'
+    );
+
+    function render(first) {
+      if (!first) output.write(`\x1b[${rendered}A`);
+      const lines = [bold(title), hint];
+      options.forEach((o, i) => {
+        const active = i === cursor;
+        const pointer = active ? cyan('›') : ' ';
+        const box = selected.has(o.id) ? green('◉') : dim('◯');
+        const label = active ? cyan(o.label) : o.label;
+        lines.push(`${pointer} ${box} ${label}`);
+      });
+      output.write(lines.map((l) => '\x1b[2K' + l).join('\n') + '\n');
+      rendered = lines.length;
+    }
+
+    const input = setupKeys();
+    hideCursor();
+
+    function finish() {
+      if (selected.size === 0) selected.add(options[cursor].id);
+      teardownKeys(input, onKey);
+      showCursor();
+      resolve(options.filter((o) => selected.has(o.id)).map((o) => o.id));
+    }
+
+    function onKey(_str, key) {
+      if (!key) return;
+      if (key.ctrl && key.name === 'c') {
+        teardownKeys(input, onKey);
+        showCursor();
+        output.write('\n');
+        process.exit(130);
+      }
+      switch (key.name) {
+        case 'up':
+        case 'k':
+          cursor = (cursor - 1 + options.length) % options.length;
+          break;
+        case 'down':
+        case 'j':
+          cursor = (cursor + 1) % options.length;
+          break;
+        case 'space':
+        case 'tab':
+          if (selected.has(options[cursor].id)) selected.delete(options[cursor].id);
+          else selected.add(options[cursor].id);
+          break;
+        case 'a': {
+          if (selected.size === options.length) selected.clear();
+          else options.forEach((o) => selected.add(o.id));
+          break;
+        }
+        case 'return':
+        case 'enter':
+          finish();
+          return;
+        default:
+          return;
+      }
+      render(false);
+    }
+
+    input.on('keypress', onKey);
+    render(true);
+  });
+}
+
+/**
+ * Single-select radio prompt.
+ *   options: [{ id, label }]
+ * Resolves to one id.
+ */
+function select({ title, options, initial }) {
+  return new Promise((resolve) => {
+    let cursor = Math.max(0, options.findIndex((o) => o.id === initial));
+    if (cursor < 0) cursor = 0;
+    let rendered = 0;
+    const output = process.stdout;
+    const hint = dim('↑/↓ move · enter select');
+
+    function render(first) {
+      if (!first) output.write(`\x1b[${rendered}A`);
+      const lines = [bold(title), hint];
+      options.forEach((o, i) => {
+        const active = i === cursor;
+        const pointer = active ? cyan('›') : ' ';
+        const dot = active ? green('◉') : dim('◯');
+        const label = active ? cyan(o.label) : o.label;
+        lines.push(`${pointer} ${dot} ${label}`);
+      });
+      output.write(lines.map((l) => '\x1b[2K' + l).join('\n') + '\n');
+      rendered = lines.length;
+    }
+
+    const input = setupKeys();
+    hideCursor();
+
+    function onKey(_str, key) {
+      if (!key) return;
+      if (key.ctrl && key.name === 'c') {
+        teardownKeys(input, onKey);
+        showCursor();
+        output.write('\n');
+        process.exit(130);
+      }
+      switch (key.name) {
+        case 'up':
+        case 'k':
+          cursor = (cursor - 1 + options.length) % options.length;
+          break;
+        case 'down':
+        case 'j':
+          cursor = (cursor + 1) % options.length;
+          break;
+        case 'return':
+        case 'enter':
+          teardownKeys(input, onKey);
+          showCursor();
+          resolve(options[cursor].id);
+          return;
+        default:
+          return;
+      }
+      render(false);
+    }
+
+    input.on('keypress', onKey);
+    render(true);
+  });
+}
+
+module.exports = { multiselect, select };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smitdev/ai-skills",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Install reusable AI assistant skills (Claude Code, GitHub Copilot, Cursor, Windsurf) with one command.",
   "bin": {
     "ai-skills": "bin/cli.js"

package/skills/contract/SKILL.md

@@ -1,150 +1,150 @@
----
-name: contract
-description: Create a contract - a spec or PRD that fully explains a feature before any code is written, so a coding assistant or engineer can build it without guessing. Use this whenever the user wants to plan or spec a feature before building - things like "spec this out", "write a PRD", "let's plan this feature first", "make an implementation doc", "write the contract for X", or "I want a plan before we touch the code". Trigger it even if the user doesn't say the word "contract" - any time they want a build-ready description of a feature instead of the code itself.
----
-
-# Contract
-
-A contract is a plan that you and the user agree on before any code is written. It is the one document a coding assistant reads to build the feature without guessing or making things up. Your job here is to make that document - not to write the feature code.
-
-Do these three steps in order: understand the codebase, then ask the user questions, then write the contract. Don't jump straight to writing - a contract built on guesses is worse than no contract.
-
-## Step 1 - Understand the codebase
-
-Before you ask the user anything, read the parts of the codebase the feature will touch. You want real files, not a vague idea of the project.
-
-Find and read the files that will likely change, or that the new code has to work with. For each one, note what it does now, the patterns it follows (naming, error handling, how state and APIs are done), and where the new feature would fit in.
-
-By the end of this step you should have a short list of real file paths, what each one does today, and where the new feature connects. You'll use this directly in the contract, so write down the real paths - never write a spec that isn't connected to the real code.
-
-## Step 2 - Ask the user questions
-
-Now fill in the gaps. The user knows what they want; you know the code. The questions bring the two together and find the decisions that shape the design.
-
-Ask one question at a time - never a big list at once. After each answer, ask the next one. This keeps it easy for the user and lets each answer guide the next question.
-
-For each question, give a short list of simple answer options to pick from, not an open question. Keep the options non-technical - describe what happens, not how it's built. Mark the option you recommend and say in one line why you'd pick it, then ask if they're okay with it. Always add an "other - let me explain" option so they're not stuck with your choices.
-
-Across the questions, cover: what the feature should do for the user, what's not included (the limits of the work), edge cases and error states, and any spot where two reasonable choices exist. Stop once you can explain the whole feature start to finish with no "it depends" left.
-
-**Example of how a question should look:**
-
-> When a search returns no results, what should the user see?
->
-> - **A - A short "nothing found" message** (recommended: simplest, and it matches how the rest of the app handles empty states)
-> - **B - The empty state plus a few suggestions on what to try next**
-> - **C - Keep the last results on screen and just show a small note**
-> - **D - Something else - tell me what you have in mind**
->
-> I'd go with A. Want to go with that, or pick another?
-
-## Step 3 - Check, then write the contract
-
-Before you write the full document, say your understanding back in a few sentences and get a yes. This is a cheap way to avoid writing a long doc based on a wrong idea.
-
-Then write the contract using the template below. Leave out any section that doesn't apply (for example, no "Data model" section for a simple styling change) instead of filling it with fluff - but keep the numbers on the sections you do use. Write it so that an engineer or coding assistant who never saw the conversation could build the feature correctly from this document alone.
-
-### Contract template
-
-```markdown
-# Contract: <Feature name>
-
-**Status:** Draft
-**Date:** <YYYY-MM-DD>
-**Area:** <which part of the product / module>
-
-## 1. Summary
-
-One short paragraph, plain words: what we're building and why.
-
-## 2. Problem
-
-The problem this solves. What happens now and why that's not good enough.
-
-## 3. Goals
-
-Clear bullets - what success looks like.
-
-## 4. Not included (out of scope)
-
-What this feature does NOT do. This is just as important as the goals - it
-stops a coding assistant from adding extra work or features no one asked for.
-
-## 5. The code today (what's there now)
-
-The real files involved and what they do now:
-
-- `path/to/file.ts` - what it does today; what changes here
-- `path/to/other.py` - ...
-  Patterns and conventions the new code should follow.
-
-## 6. The plan
-
-The approach in a sentence or two, then broken down:
-
-### 6.1 UI and UX
-
-What the user sees and does. Every state: normal, loading, empty, error,
-success. Note accessibility where it matters.
-
-### 6.2 Data model
-
-New or changed data: entities, fields, types, how they relate. (Skip if none.)
-
-### 6.3 API / interface
-
-For each endpoint or function: the signature or method + path, what goes in,
-what comes back, and the error cases. For frontend: component props, events,
-and the state it gives back.
-
-### 6.4 Logic and edge cases
-
-The step-by-step behavior. List the edge cases and say how each is handled -
-this is where most of the confusion hides.
-
-## 7. Performance and optimization
-
-How fast and how cheap this has to be, made concrete (real numbers where you
-can). Cover what applies:
-
-- Expected load / scale - how many requests, rows, items, or users, etc.
-- The hot paths - the parts that run a lot or work on big data, and the target
-  (e.g. "the list should load in under X seconds with 10,000 rows").
-- Caching, batching, rate limits, concurrency - what to reuse or throttle.
-- Cost - any API quota or money limits, and how to stay under them.
-  Skip this only if the feature has no real performance concern.
-
-## 8. Other requirements
-
-Only the ones that apply: security and access, logging/monitoring, easy to
-maintain, reusable.
-
-## 9. Files to change (checklist)
-
-A checklist the coding assistant can follow:
-
-- [ ] `path/to/file.ts` - what to change
-- [ ] `path/to/new_file.py` - new; what it holds
-
-## 10. Done when (acceptance criteria)
-
-How we know it's done, written as things you can test:
-
-- Given <situation>, when <action>, then <result>.
-
-## 11. Risks and open questions
-
-Guesses you made, choices left for later, anything still unclear.
-```
-
-## Where to save it
-
-Save the contract as a Markdown file. Use the project's existing folder if there is one - look for a `specs/`, `contracts/`, `docs/specs/`, or `.specify/` folder and put it there. If there isn't one, make a `specs/` folder.
-
-Name the file after the feature, in kebab-case: `specs/<feature-slug>.md` (for example `specs/user-profile-page.md`). Tell the user the path when you're done.
-
-## Rules to keep in mind
-
-- Make the contract, not the code. If the user also wants the code, finish and confirm the contract first - that's the thing they'll read and reuse.
-- Keep the user-facing parts (Summary, Problem, Goals) in plain words, and the build-facing parts (API, done-when) exact. The coding assistant needs the exact parts to be exact.
-- If you hit a decision while writing that you didn't settle in the questions, stop and ask instead of guessing - then write the answer into the doc.
+---
+name: contract
+description: Create a contract - a spec or PRD that fully explains a feature before any code is written, so a coding assistant or engineer can build it without guessing. Use this whenever the user wants to plan or spec a feature before building - things like "spec this out", "write a PRD", "let's plan this feature first", "make an implementation doc", "write the contract for X", or "I want a plan before we touch the code". Trigger it even if the user doesn't say the word "contract" - any time they want a build-ready description of a feature instead of the code itself.
+---
+
+# Contract
+
+A contract is a plan that you and the user agree on before any code is written. It is the one document a coding assistant reads to build the feature without guessing or making things up. Your job here is to make that document - not to write the feature code.
+
+Do these three steps in order: understand the codebase, then ask the user questions, then write the contract. Don't jump straight to writing - a contract built on guesses is worse than no contract.
+
+## Step 1 - Understand the codebase
+
+Before you ask the user anything, read the parts of the codebase the feature will touch. You want real files, not a vague idea of the project.
+
+Find and read the files that will likely change, or that the new code has to work with. For each one, note what it does now, the patterns it follows (naming, error handling, how state and APIs are done), and where the new feature would fit in.
+
+By the end of this step you should have a short list of real file paths, what each one does today, and where the new feature connects. You'll use this directly in the contract, so write down the real paths - never write a spec that isn't connected to the real code.
+
+## Step 2 - Ask the user questions
+
+Now fill in the gaps. The user knows what they want; you know the code. The questions bring the two together and find the decisions that shape the design.
+
+Ask one question at a time - never a big list at once. After each answer, ask the next one. This keeps it easy for the user and lets each answer guide the next question.
+
+For each question, give a short list of simple answer options to pick from, not an open question. Keep the options non-technical - describe what happens, not how it's built. Mark the option you recommend and say in one line why you'd pick it, then ask if they're okay with it. Always add an "other - let me explain" option so they're not stuck with your choices.
+
+Across the questions, cover: what the feature should do for the user, what's not included (the limits of the work), edge cases and error states, and any spot where two reasonable choices exist. Stop once you can explain the whole feature start to finish with no "it depends" left.
+
+**Example of how a question should look:**
+
+> When a search returns no results, what should the user see?
+>
+> - **A - A short "nothing found" message** (recommended: simplest, and it matches how the rest of the app handles empty states)
+> - **B - The empty state plus a few suggestions on what to try next**
+> - **C - Keep the last results on screen and just show a small note**
+> - **D - Something else - tell me what you have in mind**
+>
+> I'd go with A. Want to go with that, or pick another?
+
+## Step 3 - Check, then write the contract
+
+Before you write the full document, say your understanding back in a few sentences and get a yes. This is a cheap way to avoid writing a long doc based on a wrong idea.
+
+Then write the contract using the template below. Leave out any section that doesn't apply (for example, no "Data model" section for a simple styling change) instead of filling it with fluff - but keep the numbers on the sections you do use. Write it so that an engineer or coding assistant who never saw the conversation could build the feature correctly from this document alone.
+
+### Contract template
+
+```markdown
+# Contract: <Feature name>
+
+**Status:** Draft
+**Date:** <YYYY-MM-DD>
+**Area:** <which part of the product / module>
+
+## 1. Summary
+
+One short paragraph, plain words: what we're building and why.
+
+## 2. Problem
+
+The problem this solves. What happens now and why that's not good enough.
+
+## 3. Goals
+
+Clear bullets - what success looks like.
+
+## 4. Not included (out of scope)
+
+What this feature does NOT do. This is just as important as the goals - it
+stops a coding assistant from adding extra work or features no one asked for.
+
+## 5. The code today (what's there now)
+
+The real files involved and what they do now:
+
+- `path/to/file.ts` - what it does today; what changes here
+- `path/to/other.py` - ...
+  Patterns and conventions the new code should follow.
+
+## 6. The plan
+
+The approach in a sentence or two, then broken down:
+
+### 6.1 UI and UX
+
+What the user sees and does. Every state: normal, loading, empty, error,
+success. Note accessibility where it matters.
+
+### 6.2 Data model
+
+New or changed data: entities, fields, types, how they relate. (Skip if none.)
+
+### 6.3 API / interface
+
+For each endpoint or function: the signature or method + path, what goes in,
+what comes back, and the error cases. For frontend: component props, events,
+and the state it gives back.
+
+### 6.4 Logic and edge cases
+
+The step-by-step behavior. List the edge cases and say how each is handled -
+this is where most of the confusion hides.
+
+## 7. Performance and optimization
+
+How fast and how cheap this has to be, made concrete (real numbers where you
+can). Cover what applies:
+
+- Expected load / scale - how many requests, rows, items, or users, etc.
+- The hot paths - the parts that run a lot or work on big data, and the target
+  (e.g. "the list should load in under X seconds with 10,000 rows").
+- Caching, batching, rate limits, concurrency - what to reuse or throttle.
+- Cost - any API quota or money limits, and how to stay under them.
+  Skip this only if the feature has no real performance concern.
+
+## 8. Other requirements
+
+Only the ones that apply: security and access, logging/monitoring, easy to
+maintain, reusable.
+
+## 9. Files to change (checklist)
+
+A checklist the coding assistant can follow:
+
+- [ ] `path/to/file.ts` - what to change
+- [ ] `path/to/new_file.py` - new; what it holds
+
+## 10. Done when (acceptance criteria)
+
+How we know it's done, written as things you can test:
+
+- Given <situation>, when <action>, then <result>.
+
+## 11. Risks and open questions
+
+Guesses you made, choices left for later, anything still unclear.
+```
+
+## Where to save it
+
+Save the contract as a Markdown file. Use the project's existing folder if there is one - look for a `specs/`, `contracts/`, `docs/specs/`, or `.specify/` folder and put it there. If there isn't one, make a `specs/` folder.
+
+Name the file after the feature, in kebab-case: `specs/<feature-slug>.md` (for example `specs/user-profile-page.md`). Tell the user the path when you're done.
+
+## Rules to keep in mind
+
+- Make the contract, not the code. If the user also wants the code, finish and confirm the contract first - that's the thing they'll read and reuse.
+- Keep the user-facing parts (Summary, Problem, Goals) in plain words, and the build-facing parts (API, done-when) exact. The coding assistant needs the exact parts to be exact.
+- If you hit a decision while writing that you didn't settle in the questions, stop and ask instead of guessing - then write the answer into the doc.

package/skills/gistly/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: gistly
+description: Answer a question so it is correct, dense, and easy to hold in your head - the right answer first, the mental model that makes it stick, and as few tokens as it takes to get there. Use this whenever the user asks a question and wants a clear answer rather than code or a document - things like "explain X", "how does Y work", "what's the difference between A and B", "why does Z happen", "help me understand this", or any plain question where a tight, well-modeled answer beats a long one. Not for documenting a codebase (use understand) or speccing a feature (use contract).
+---
+
+# Gistly
+
+The job is to answer a question so the person both gets the correct answer and walks away with a mental model they can reuse - using as few tokens as the answer honestly needs. Dense, not terse. Every sentence should carry information the reader didn't already have.
+
+Token-efficient does not mean short for its own sake. It means high signal per word: cut the filler, keep the substance. A wrong-but-short answer fails. A correct-but-bloated answer wastes the reader's attention. Aim for correct, modeled, and lean - in that order.
+
+## Answer in this order
+
+1. **Direct answer first.** Open with the actual answer in one or two sentences - the thing they asked for, before any setup. No preamble, no restating the question, no "great question".
+2. **The mental model.** Give the one organizing idea, analogy, or rule that makes the rest derivable - the "now I get it" sentence. This is the part that makes the answer stick, so it's worth the tokens even when everything else is trimmed.
+3. **Just enough detail to act on it.** The few specifics, steps, or caveats they need and no more. Stop when the question is answered, not when you run out of things to say.
+
+## What to cut
+
+- Preamble and filler: "Great question", "It's worth noting", "As you may know", "In order to", "Basically".
+- Restating the question back before answering it.
+- Hedging and apology: say the thing. If you're unsure, see the rule below - that's different from hedging.
+- Repeating the same point in three phrasings. Make it once, well.
+- Caveats nobody asked about and edge cases that don't change the answer.
+- Throat-clearing closers: "I hope this helps", "Let me know if you have questions".
+
+## What to keep
+
+- The mental model - never cut the idea that makes it click to save a sentence.
+- A concrete example when it teaches faster than the abstract rule. One sharp example beats a paragraph of theory.
+- The caveat that would actually bite them if left out.
+- The "why", when knowing why lets them figure out the next case themselves instead of asking again.
+
+## Use structure that compresses
+
+Pick the form that carries the meaning in the fewest tokens:
+
+- **Comparisons / trade-offs** -> a small table or two labeled lines, not prose.
+- **A process or causal chain** -> `A -> B -> C` or a short numbered list.
+- **A few independent points** -> tight bullets, one idea each.
+- **A single idea** -> one or two plain sentences. Don't add structure a sentence doesn't need.
+
+Match depth to the question. A quick "what's the flag for X" gets one line. A "why does this whole thing work this way" earns a model plus an example. Read which one they asked.
+
+## Stay correct
+
+Token-efficiency never comes before being right.
+
+- If you're not sure, say so in a few words and state your confidence ("I think X, but verify Y") - don't pad uncertainty into a long hedge, and don't state a guess as fact.
+- Don't invent specifics (numbers, flags, names, APIs) to sound complete. A short answer that admits a gap beats a fluent wrong one.
+- If the question is ambiguous and the answers genuinely differ, ask one sharp clarifying question instead of writing all branches. If the branches are short, just cover them.
+
+## The test
+
+Before sending, check: Is the answer right? Would the reader come away with a model they can reuse on the next case? Could I cut a third of the words without losing meaning? If yes to the last one, cut them.

package/skills/understand/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: understand
+description: Read a whole codebase and write a set of plain-language docs that explain it - one overview/map doc plus one doc per aspect (UI, styles, API, models, data, testing, features, services, and so on). Use this when someone wants to understand a project as a whole or get onboarded to a repo - things like "help me understand this codebase", "document this repo", "explain how this project is structured", "map out the code", "onboard me to this project", or "I just joined and need to learn this code". This is for the WHOLE codebase. To explain one single feature in depth, use the feature-explainer skill instead.
+---
+
+# Understanding
+
+The goal is to help someone understand a codebase fast - like a new engineer joining the team next week. You do that by reading the code and writing a small set of plain, connected docs: one map that gives the big picture, and one doc per aspect (UI, API, data, and so on) that goes deeper.
+
+Write everything for a smart person who is new to this project. No jargon dumps. Point to real files. Don't make things up - if you didn't read something, say so.
+
+Do these steps in order: survey the repo, pick the aspects, write the map, then write each aspect doc.
+
+## Step 1 - Survey the repo
+
+Get the big picture before going deep. Look at:
+
+- The entry points (main file, app start, routes, index).
+- The folder layout - what the top-level folders are for.
+- Config and dependencies (package.json, requirements, env files) - this tells you the stack and the main libraries.
+- The README, if there is one.
+
+You don't need to read every file. Read the entry points and a few important files in each area so you understand how the project is put together. Note what you did and didn't read.
+
+## Step 2 - Pick the aspects
+
+Don't force a fixed list. Look at what this repo actually has and pick the aspects that apply. A good default set:
+
+1. UI elements
+2. Styles
+3. API
+4. Models
+5. Data
+6. Testing
+7. Features
+8. Services
+
+But adjust to the repo. Drop ones that don't exist (a backend repo has no UI or styles). Add ones that matter here but aren't listed (for example: auth, config, state management, build/deploy, data flow, third-party integrations). Tell the user the list of aspects you landed on before you write.
+
+## Step 3 - Write the map doc first
+
+This is the most important doc - it ties everything together and gives the mental model. Write it before the aspect docs. Use this shape:
+
+```markdown
+# Codebase map: <project name>
+
+## What this project is
+
+One short paragraph in plain words - what it does and who it's for.
+
+## The big pieces
+
+The main parts of the system and what each one is responsible for. Link to the
+aspect doc for each (e.g. "see api.md").
+
+## How it's laid out
+
+The folder structure and what each top-level folder is for.
+
+## How a typical action flows through
+
+Follow one common action from start to finish (e.g. a user clicks X -> this
+component -> this API -> this service -> this data). This is the part that makes
+it all click. A simple diagram or step list is great here.
+
+## Stack and key dependencies
+
+The main languages, frameworks, and libraries, and what each is used for.
+
+## Where to start reading
+
+The 3-5 files a newcomer should open first, and why.
+
+## What this map skips
+
+Anything you didn't read or that's out of scope, so the reader isn't misled.
+```
+
+## Step 4 - Write one doc per aspect
+
+For each aspect from Step 2, write a doc using the same shape so they all feel consistent:
+
+```markdown
+# <Aspect> (e.g. API)
+
+## What this covers
+
+One or two sentences - what this aspect is and why it matters here.
+
+## Where it lives
+
+The key files and folders, with real paths:
+
+- `path/to/file` - what it does
+
+## How it works
+
+The mental model in plain words. How the pieces fit together. A small diagram
+or flow helps a lot.
+
+## The main pieces
+
+The important files/modules/functions and what each one does. Keep it to the
+ones that matter, not every file.
+
+## How it connects to the rest
+
+How this aspect talks to the others (e.g. the API calls these services, which
+read these models).
+
+## Gotchas
+
+The non-obvious things - surprises, tricky bits, patterns you have to know.
+Whatever would trip up a newcomer.
+
+## Where to start reading
+
+The first file or two to open to understand this aspect.
+```
+
+## Where to save the docs
+
+Put all the docs in one folder so they're a set. Reuse the project's docs folder if there is one - look for `docs/`, then use `docs/codebase/`. If there's no docs folder, create `codebase-map/`.
+
+Name the files simply: the map is `overview.md`, and each aspect is its lowercase name (`api.md`, `ui.md`, `data.md`, ...). Tell the user the folder path and the list of files when you're done.
+
+## Rules to keep in mind
+
+- Write for a newcomer. Plain words, real examples, no walls of jargon.
+- Point to real file paths. Every claim should be tied to actual code, not a guess.
+- Don't invent. If you didn't read part of the code, leave it out and say so in the "skips" section rather than guessing.
+- Keep the docs connected. The map links to the aspect docs; the aspect docs say how they connect to each other. That's what makes the set feel cohesive instead of 8 loose files.
+- Use a small diagram or step-by-step flow wherever it explains things faster than prose - especially for data flow and how an action moves through the system.