@crouton-kit/crouter 0.1.6 → 0.1.8

package/dist/cli.js

@@ -13,7 +13,7 @@ import { registerPlanCommand } from './commands/plan.js';
 import { registerSpecCommand } from './commands/spec.js';
 import { registerAgentCommand } from './commands/agent.js';
 import { maybeAutoUpdate } from './core/auto-update.js';
-import { ensureBootSkill, ensureOfficialMarketplace } from './core/bootstrap.js';
+import { ensureBootSkill, ensureOfficialMarketplace, ensureProjectScope } from './core/bootstrap.js';
 function readPackageVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
     const pkgPath = join(here, '..', 'package.json');
@@ -38,6 +38,7 @@ registerSpecCommand(program);
 registerAgentCommand(program);
 ensureOfficialMarketplace(process.argv);
 ensureBootSkill(process.argv);
+ensureProjectScope(process.argv);
 maybeAutoUpdate(process.argv);
 program.parseAsync().catch((err) => {
     process.stderr.write(`crtr: ${err instanceof Error ? err.message : String(err)}\n`);

package/dist/commands/skill.js

@@ -9,7 +9,7 @@ import { resolveSkill, listAllSkills, listInstalledPlugins, findPluginByName, pa
 import { updateConfig, ensureScopeInitialized } from '../core/config.js';
 import { parseFrontmatter, serializeFrontmatter } from '../core/frontmatter.js';
 import { ensureDir, pathExists, readText, walkFiles } from '../core/fs-utils.js';
-import { skillPrompt, skillCreatePrompt } from '../prompts/skill.js';
+import { skillPrompt, skillCreatePrompt, skillTemplatePrompt } from '../prompts/skill.js';
 const KNOWN_VERBS = new Set([
     'list',
     'show',
@@ -17,6 +17,7 @@ const KNOWN_VERBS = new Set([
     'grep',
     'new',
     'create',
+    'template',
     'where',
     'enable',
     'disable',
@@ -286,14 +287,22 @@ export function registerSkillCommands(program) {
             handleError(e);
         }
     });
-    // create — walkthrough for capturing knowledge as a skill
+    // create — pick a template type
     skill
         .command('create [topic...]')
-        .description('walkthrough for capturing knowledge as a new skill')
+        .description('pick a template type for a new skill (primer | playbook | freeform)')
         .action(async (topic) => {
         const arg = topic && topic.length > 0 ? topic.join(' ') : '';
         out(skillCreatePrompt(arg));
     });
+    // template — full workflow + skeleton for one template type
+    skill
+        .command('template <type> [topic...]')
+        .description('full workflow + skeleton for a template type (primer | playbook | freeform)')
+        .action(async (type, topic) => {
+        const arg = topic && topic.length > 0 ? topic.join(' ') : '';
+        out(skillTemplatePrompt(type, arg));
+    });
     // where
     skill
         .command('where <name>')

package/dist/core/bootstrap.d.ts

@@ -3,3 +3,4 @@ export declare const OFFICIAL_MARKETPLACE_URL = "https://github.com/crouton-labs
 export declare const OFFICIAL_MARKETPLACE_REF = "main";
 export declare function ensureBootSkill(argv: string[]): void;
 export declare function ensureOfficialMarketplace(argv: string[]): void;
+export declare function ensureProjectScope(argv: string[]): void;

package/dist/core/bootstrap.js

@@ -1,11 +1,12 @@
 import { writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { userScopeRoot } from './scope.js';
+import { findProjectScopeRoot, resetScopeCache, userScopeRoot } from './scope.js';
 import { ensureDir, pathExists, readText, removePath, nowIso } from './fs-utils.js';
 import { readConfig, readState, updateConfig, updateState, ensureScopeInitialized } from './config.js';
 import { clone } from './git.js';
 import { readMarketplaceManifest } from './manifest.js';
+import { CRTR_DIR_NAME } from '../types.js';
 export const OFFICIAL_MARKETPLACE_NAME = 'crouter-official-marketplace';
 export const OFFICIAL_MARKETPLACE_URL = 'https://github.com/crouton-labs/crouter-official-marketplace.git';
 export const OFFICIAL_MARKETPLACE_REF = 'main';
@@ -23,48 +24,42 @@ function shouldSkipForArgv(argv) {
     return SKIP_SUBCOMMANDS.has(sub);
 }
 const BOOT_SKILL_NAME = 'crtr-skills';
-const BOOT_SKILL_MARKER = '<!-- crtr-boot-skill v1 -->';
+const BOOT_SKILL_MARKER = '<!-- crtr-boot-skill v2 -->';
+const BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
 function bootSkillBody() {
     return `---
 name: crtr-skills
-description: Capture, list, search, and load skills via the crtr CLI. Use when the user wants to remember something, save knowledge, build a context primer, or recall a previously saved skill. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".
+description: Capture, list, search, and load skills via the crtr CLI. Skills are durable agent memory — markdown future LLM sessions load on demand. Use when the user wants to remember/save knowledge, build a context primer, or recall a previously saved skill. Triggers: "save", "remember", "build context for", "what skills do we have", "skill for X".
 argument-hint: [topic or verb]
 ---
 
 ${BOOT_SKILL_MARKER}
 
-# /crtr:skills — the skill router
+# /crtr-skills — skill router
 
-\`crtr\` is the source of truth for skills on this machine. Every skill the
-agent should know about is discoverable via \`crtr skill\`. This file is a
-thin router; the CLI is the index.
+Skills = durable agent memory. Written for **future LLM sessions**, not the
+user. \`crtr skill\` is the index — discoverable via list/search/grep.
 
-## What the user is asking for
+## Route by intent
 
-- **Capture new knowledge** ("save this", "remember", "build context for X",
-  "make a skill that…"): run \`crtr skill create $ARGUMENTS\` and follow the
-  walkthrough it prints. It picks a template (primer/preference/runbook/
-  glossary/decision/freeform) and walks you through scoping, researching,
-  and scaffolding.
-- **Find a relevant skill** ("what do we have on X"): run
-  \`crtr skill search "$ARGUMENTS"\` and load the best hit with
-  \`crtr skill show <name>\`.
-- **Load a known skill by name**: run \`crtr skill show <name>\`.
-- **List everything**: run \`crtr skill list\`.
-- **Anything else skill-related**: run \`crtr skill\` (no args) — it prints
-  the full skill workflow guide. Follow it.
+- **Capture** ("save", "remember", "build context for", "make a skill"):
+  \`crtr skill create $ARGUMENTS\` → pick template (primer/playbook/freeform)
+  → \`crtr skill template <type> $ARGUMENTS\` for the full workflow. Follow it
+  directly.
+- **Find** ("what do we have on X"): \`crtr skill search "$ARGUMENTS"\` →
+  \`crtr skill show <name>\` on the best hit.
+- **Load by name**: \`crtr skill show <name>\`.
+- **List all**: \`crtr skill list\`.
+- **Anything else**: \`crtr skill\` (no args) prints the full workflow guide.
 
-\`$ARGUMENTS\` is the user's request as a string. Use it to seed the topic for
-\`create\` or the query for \`search\`. If it's empty, ask the user what they
-want before running anything.
+If \`$ARGUMENTS\` is empty, ask the user what they want before running.
 
-## Output rules
+## Rules
 
-The CLI's stdout is the prompt. Read it, then act on it. Don't paraphrase the
-guidance back at the user — just do the work it describes.
-
-If \`crtr\` isn't on PATH, tell the user and stop. This skill assumes
-\`@crouton-kit/crouter\` is installed globally.
+- CLI stdout is the prompt — act on it, don't paraphrase to the user.
+- Don't load \`create\` and \`template\` outputs in the same turn (progressive
+  disclosure). \`create\` decides type; \`template\` returns the workflow.
+- If \`crtr\` is not on PATH, tell the user and stop.
 `;
 }
 export function ensureBootSkill(argv) {
@@ -81,11 +76,11 @@ export function ensureBootSkill(argv) {
         const skillDir = join(claudeSkillsRoot, BOOT_SKILL_NAME);
         const skillFile = join(skillDir, 'SKILL.md');
         if (pathExists(skillFile)) {
-            // Idempotent: only rewrite if it's still our marker version.
             const existing = readText(skillFile);
-            if (!existing.includes(BOOT_SKILL_MARKER))
+            // If the user customized (no boot-skill marker at all), don't clobber.
+            if (!existing.includes(BOOT_SKILL_MARKER_PREFIX))
                 return;
-            // Same marker — check if body needs update, otherwise skip.
+            // Any marker version present → roll forward to current. Skip if identical.
             if (existing === bootSkillBody())
                 return;
         }
@@ -147,3 +142,29 @@ export function ensureOfficialMarketplace(argv) {
         }
     }
 }
+export function ensureProjectScope(argv) {
+    try {
+        if (process.env.CRTR_NO_AUTO_INIT === '1')
+            return;
+        if (shouldSkipForArgv(argv))
+            return;
+        // Already inside a project scope (here or in an ancestor) — nothing to do.
+        if (findProjectScopeRoot() !== null)
+            return;
+        const cwd = process.cwd();
+        // Never auto-init at $HOME — that path is reserved for the user scope.
+        if (cwd === homedir())
+            return;
+        const projectRoot = join(cwd, CRTR_DIR_NAME);
+        if (projectRoot === userScopeRoot())
+            return;
+        ensureScopeInitialized('project', projectRoot);
+        resetScopeCache();
+    }
+    catch (e) {
+        if (process.env.CRTR_DEBUG === '1') {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`crtr: project-init error: ${msg}\n`);
+        }
+    }
+}

package/dist/prompts/skill.d.ts

@@ -1,2 +1,3 @@
 export declare function skillPrompt(): string;
 export declare function skillCreatePrompt(topic: string): string;
+export declare function skillTemplatePrompt(type: string, topic: string): string;

package/dist/prompts/skill.js

@@ -1,176 +1,175 @@
 export function skillPrompt() {
-    return `# Skills — capture and recall knowledge
+    return `# Skills — durable agent memory
 
-\`crtr\` skills are markdown documents the agent loads on demand. Use them for
-anything you want recalled later: architectural primers, runbooks, your
-personal preferences, domain glossaries, decision records — methodology *or*
-captured knowledge. The CLI is the index; \`crtr skill list/search/grep\`
-discovers what's available so you never need a hand-maintained router file.
+Skills are markdown the agent loads on demand. **Audience: future LLM agent
+sessions, not humans.** Write for the model: terse, decision-first, dense.
+The CLI is the index — \`crtr skill list/search/grep\` discovers what's saved.
 
-Skills live in three places, in resolution order:
-1. **Scope-direct** — \`<scope-root>/skills/<name>/SKILL.md\` (no plugin wrapper, shown as \`user:<name>\` or \`project:<name>\`)
-2. **Plugin skills** — \`<plugin>/skills/<name>/SKILL.md\` (shown as \`<scope>:<plugin>/<name>\`)
-3. Project scope beats user scope; non-marketplace plugins beat marketplace ones.
+Locations (resolution order):
+1. **Scope-direct** \`<scope-root>/skills/<name>/SKILL.md\` → \`user:<name>\` / \`project:<name>\`
+2. **Plugin skills** \`<plugin>/skills/<name>/SKILL.md\` → \`<scope>:<plugin>/<name>\`
+3. Project > user; non-marketplace plugins > marketplace.
 
-Ambiguous names exit \`4\` — disambiguate with \`<plugin>:<name>\` or \`_:<name>\`
-for scope-direct.
+Ambiguous names exit \`4\` — disambiguate with \`<plugin>:<name>\` or \`_:<name>\`.
 
 ## Discover
 
 \`\`\`
-crtr skill list                    # one per line: <qualifier> — <description>
-crtr skill search <query>          # rank by name, description, keywords
-crtr skill grep <pattern>          # regex search across SKILL.md bodies
+crtr skill list                    # <qualifier> — <description>
+crtr skill search <query>          # ranked by name/description/keywords
+crtr skill grep <pattern>          # regex across SKILL.md bodies
 \`\`\`
 
 ## Load
 
 \`\`\`
-crtr skill show <name>             # print SKILL.md body to stdout
-crtr skill show <plugin>:<name>    # disambiguate when names collide
+crtr skill show <name>             # body to stdout (default verb)
 crtr skill show _:<name>           # explicit scope-direct
-crtr skill path <name>             # absolute path to SKILL.md
-crtr skill where <name>            # {scope, plugin, path} as JSON
+crtr skill path <name>             # absolute path
+crtr skill where <name>            # {scope, plugin, path} JSON
 \`\`\`
 
-\`show\` is the default verb: \`crtr skill <name>\` (with no verb) also prints
-the body.
-
-## Author
+## Author (progressive disclosure)
 
 \`\`\`
-crtr skill create [topic...]       # walkthrough — pick a template, capture knowledge
-crtr skill new <name>              # bare scaffold, scope-direct (asks for --scope)
-crtr skill new <plugin>:<name>     # bare scaffold inside an existing plugin
-crtr skill show authoring-skills   # the SKILL.md authoring guide
+crtr skill create [topic...]       # pick a template type
+crtr skill template <type> [topic] # workflow + skeleton for that type
+crtr skill new <name>              # bare scaffold, scope-direct
 \`\`\`
 
-Reach for \`create\` when capturing something new — it walks you through choosing
-a template (architectural primer, preference, runbook, glossary, decision,
-freeform) and applies the right research workflow for that template.
+Don't load \`create\` and \`template\` in the same turn — \`create\` decides the
+type, then call \`template\`.
 
 ## Toggle
 
 \`\`\`
-crtr skill enable <name>           # clear any disable in the chosen scope
-crtr skill disable <name>          # hide from list and agent discovery
+crtr skill enable <name>
+crtr skill disable <name>
 \`\`\`
 
 ## Exit codes
 
-- \`0\` — success
-- \`3\` — skill not found
-- \`4\` — ambiguous name; use \`<plugin>:<name>\`
+\`0\` success · \`3\` not found · \`4\` ambiguous (qualify name)
 `;
 }
 export function skillCreatePrompt(topic) {
     const topicLine = topic
-        ? `User-provided topic: **${topic}**`
-        : `No topic was provided — ask the user what they want to capture before continuing.`;
-    return `# Capture knowledge as a skill
+        ? `Topic: **${topic}**`
+        : `No topic provided — ask the user what to capture before proceeding.`;
+    return `# Author a skill — step 1: pick template type
 
-You are about to author a new \`crtr\` skill — a SKILL.md the agent will recall
-on demand. Skills can capture *any* kind of durable knowledge: architectural
-primers, runbooks, personal preferences, domain glossaries, decision records,
-freeform notes. Don't conflate this with "methodology only" — if the user wants
-the agent to remember something later, a skill is the right shape.
+You are about to write a skill (markdown read by future LLM agent sessions,
+not humans). Pick the template, then load its workflow.
 
 ${topicLine}
 
-## Step 1 — Decide the template
+## Templates
 
-Ask the user (use \`AskUserQuestion\` if available) which template fits, with
-your best guess pre-selected. Don't write anything until this is settled.
+- \`primer\` — codebase/architectural knowledge ("how does X work, why, what
+  are the gotchas"). Triggers parallel-explore research.
+- \`playbook\` — methodology/judgment ("how to think about X"). The
+  \`authoring:skills\`-style skill that teaches decisions, not facts.
+- \`freeform\` — anything else (glossary, decision record, runbook, prefs).
 
-| Template | When to use | Research workflow |
-|----------|-------------|-------------------|
-| \`primer\` | Architectural/codebase knowledge — "how does X work, why does it exist" | Parallel-explore (Step 3a) |
-| \`preference\` | User preferences, style guides, "remember I like X" | None — just ask 2-3 sharpening questions |
-| \`runbook\` | Operational procedure, incident response, "here's how to do X" | Light — confirm steps with the user |
-| \`glossary\` | Domain terms and invariants | None — list terms, get definitions from user |
-| \`decision\` | ADR-style record: context / decision / consequences | Confirm context and tradeoffs with user |
-| \`freeform\` | Anything else | Ask what shape they want |
+## Next
 
-If the user is asking for a codebase primer, **also** consider whether the
-subsystem is large enough to justify it. Small/self-evident systems do not
-need a primer — push back and offer to write a one-paragraph note instead.
+1. Pick a type. If unclear, use \`AskUserQuestion\` with your best guess first.
+2. Run:
 
-## Step 2 — Decide the scope and name
+   \`\`\`
+   crtr skill template <type>${topic ? ` ${topic}` : ' [topic]'}
+   \`\`\`
 
-Ask the user:
-- **Scope** — \`user\` (lives in \`~/.crouter/skills/\`, available everywhere) or
-  \`project\` (lives in \`<project>/.crouter/skills/\`, only here). Default
-  \`project\` if cwd is inside a project scope; otherwise \`user\`.
-- **Name** — kebab-case slug. Suggest one from the topic.
+   That output contains the research methodology, SKILL.md skeleton, and
+   scaffold command. Follow it directly — don't paraphrase.
 
-Check for collisions: \`crtr skill where <name>\`. If it exists, ask whether to
-update the existing one or pick a different name.
+## Push back when
 
-## Step 3 — Research (template-specific)
+- Subsystem is small/self-evident → suggest CLAUDE.md note instead of primer.
+- "Topic" is really a one-off task → don't capture; just do the work.
+`;
+}
+export function skillTemplatePrompt(type, topic) {
+    const t = type.toLowerCase();
+    if (t === 'primer')
+        return primerTemplatePrompt(topic);
+    if (t === 'playbook')
+        return playbookTemplatePrompt(topic);
+    if (t === 'freeform')
+        return freeformTemplatePrompt(topic);
+    return `unknown template type: ${type}\nvalid: primer | playbook | freeform\nrun \`crtr skill create\` to pick.\n`;
+}
+function topicLine(topic) {
+    return topic
+        ? `Topic: **${topic}**`
+        : `No topic — confirm with the user before continuing.`;
+}
+function primerTemplatePrompt(topic) {
+    return `# Primer — codebase knowledge skill
 
-### 3a. \`primer\` — parallel codebase exploration
+**Audience: future LLM agent sessions.** Captures *why* a subsystem exists +
+non-obvious facts that code alone doesn't reveal. Lets a future session skip
+re-exploration.
 
-Dispatch 4–8 \`Explore\` subagents in parallel. Partition by **slice, not by
-directory**:
+${topicLine(topic)}
 
-- **Entry points** — HTTP routes, CLI commands, cron, event handlers, public exports
-- **Data model** — schemas, types, DB tables, key invariants
-- **Control flow** — how a typical request/job traverses the system end-to-end
-- **External integrations** — third-party APIs, queues, services, env vars
-- **Tests** — what's tested reveals what's load-bearing
-- **History** — recent \`git log\` for this area surfaces ongoing work and pain
-- **Cross-cutting** — auth, errors, logging, feature flags as they apply here
+## 1. Inventory (parallel)
 
-Each subagent must return **concrete \`file:line\` references**, *non-obvious*
-facts (skip what's obvious from filenames), naming conventions, and gotchas.
-Reject vague summaries.
+- \`ls\` repo top level
+- check stack manifests
+- \`git log --oneline -15\` in this area
+- \`crtr skill search <topic>\` / \`crtr skill list\` — does a primer already exist?
 
-### 3b. \`preference\` / \`glossary\` / \`decision\` — interview
+If subsystem is small/self-evident, **stop**. Suggest a CLAUDE.md note. Primers
+are for large, complicated, or unintuitive systems only.
 
-Use \`AskUserQuestion\` to batch sharpening questions (≤4 at a time, multiple
-choice with your best guess first). Frame each as "here's my read; is this
-right?" Never write assumptions into the skill — if a fact isn't confirmed by
-code or the user, it doesn't go in.
+## 2. Scope + name
 
-### 3c. \`runbook\` — walk it
+- **Scope**: \`project\` by default. \`user\` only if cross-repo.
+- **Name**: kebab-case. Confirm no collision: \`crtr skill where <name>\`.
 
-If the procedure exists, run/grep it and confirm. Otherwise, have the user
-narrate it once and read back the steps.
+## 3. Parallel exploration
 
-## Step 4 — Verify intent
+Dispatch **4–8 \`Explore\` subagents in parallel**, partitioned by *slice* (not
+directory):
 
-Before writing, summarize your working hypothesis back to the user in 2-3
-sentences: **what this skill is about and when it should be loaded.** This is
-what code and grep can't tell you. Get a yes or correction.
+- Entry points (routes, CLI, events, public exports)
+- Data model (schemas, types, invariants)
+- Control flow (typical request/job end-to-end)
+- External integrations (APIs, queues, env vars)
+- Tests (what's tested = what's load-bearing)
+- History (recent git log surfaces pain points)
+- Cross-cutting (auth, errors, logging, flags as they apply)
 
-## Step 5 — Scaffold and write
+Each subagent returns: concrete \`file:line\` refs, *non-obvious* facts (skip
+filename-obvious), naming conventions, gotchas. Reject vague summaries.
 
-Run:
+## 4. Verify with user
 
-\`\`\`
-crtr skill new <name> --scope <user|project> --description "<one-line trigger>"
-\`\`\`
+Code = *what*. User = *why*. Use \`AskUserQuestion\` (≤4 questions,
+multi-choice, best-guess first):
 
-(For a plugin-scoped skill instead, use \`crtr skill new <plugin>:<name>\`.)
+- Business purpose / who depends on it
+- Surprising-looking architectural decisions
+- Ownership / deprecation status / expected scale
+- Canonical flow when multiple exist
 
-This creates \`SKILL.md\` with frontmatter only. Open it and fill the body
-using the template skeleton below for the kind you chose. **Density rules:**
-\`file:line\` over prose; tables where structure fits; skip anything
-self-evident from a 30-second skim of the code; no "this section covers…"
-meta-commentary.
+Skip if greppable or won't change the primer. **Never write unconfirmed
+assumptions.**
 
-The \`description:\` field drives auto-discovery — front-load the trigger
-keywords the user (or agent) would naturally say. Aim for ≤250 chars.
+## 5. Scaffold
 
-### Skeletons
+\`\`\`
+crtr skill new <name> --scope project --description "<what+when, ≤250 chars, front-loaded triggers>"
+\`\`\`
 
-**\`primer\`**
+## 6. Write the body
 
 \`\`\`markdown
 # <topic>
 
 ## Purpose
-Why this exists. The business problem it solves. Who depends on it.
+Why this exists. Problem solved. Who depends on it.
 (1–3 tight paragraphs — what code can't tell you.)
 
 ## Architecture
@@ -185,97 +184,252 @@ Components, responsibilities, data/control flow, boundaries.
 Domain terms, invariants, non-obvious constraints.
 
 ## Entry points
-Where work enters the system, with \`file:line\`.
+\`file:line\` where work enters.
 
 ## Gotchas
-Non-obvious coupling. Things that look broken but aren't. Past footguns.
+Non-obvious coupling. Looks-broken-but-isn't. Past footguns.
 
 ## Related
-- \`<other-skill>\` — how they interact
+- \`<other-skill>\` — interaction
 \`\`\`
 
-**\`preference\`**
+**Density rules:**
+- \`file:line\` over prose
+- Tables where structure fits
+- Skip 30-second-skim-obvious
+- No "this section covers…" meta
+- Budget ~150 lines; deeper reference → sibling files
 
-\`\`\`markdown
-# <topic preferences>
+## 7. Verify
 
-## Rule
-What the user wants.
+\`\`\`
+crtr skill where <name>
+crtr skill show <name>
+crtr skill search <keyword>     # confirm description triggers discovery
+\`\`\`
 
-## Why
-Reason given — past incident, strong preference, constraint.
+Sharpen description if discovery misses. Cut body if bloated.
 
-## How to apply
-When/where this guidance kicks in.
+## Updates
+
+If updating existing primer: diff draft vs current, call out changes + why
+before writing. Update related skills' \`## Related\` sections.
+`;
+}
+function playbookTemplatePrompt(topic) {
+    return `# Playbook — methodology skill
+
+**Audience: future LLM agent sessions.** Teaches *judgment*, not facts —
+decision frameworks, heuristics, when-to-use / when-not-to-use. Examples:
+skill-authoring, debugging methodology, multi-agent orchestration.
+
+${topicLine(topic)}
+
+## Litmus test
+
+> Does this teach judgment, or describe an API?
+
+If you'd write *"when X, do Y because Z"* → playbook. If you'd write tables
+of fields/flags/events → reference material (put in sibling \`reference.md\`,
+not SKILL.md). If neither fits → use \`crtr skill template freeform\` instead.
+
+**Playbook markers:** teaches a framework · has "when (not) to use" · prose
+over tables · reader makes better decisions after 30 seconds.
+
+## 1. Interview
+
+A playbook = user's accumulated judgment. Not greppable. Use
+\`AskUserQuestion\` (≤4, multi-choice, best-guess first):
+
+- The decision this skill teaches
+- 2–4 most common failure modes without it
+- Triggers (words/situations that should load it)
+- Non-obvious rules that surprise newcomers
+
+Push back on vagueness. *"Be thoughtful"* ≠ heuristic. *"Prefer one bundled
+PR over many small ones for refactors here, because review churn dominates"*
+= heuristic.
+
+## 2. Scope + name
+
+- **Scope**: \`user\` for cross-project methodology. \`project\` for repo-specific.
+- **Name**: kebab-case, verb-or-noun-phrase. Not "guide-to-X".
+- Check \`crtr skill where <name>\`.
+
+## 3. Scaffold
+
+\`\`\`
+crtr skill new <name> --scope <user|project> --description "<what it teaches + when to load, ≤250 chars, front-loaded triggers>"
 \`\`\`
 
-**\`runbook\`**
+## 4. Density rules
+
+LLM reasoning degrades past ~3k tokens. **Budget ~150 lines for SKILL.md.**
+
+- Decision-first. *"When you need X"* before *"how X works"*.
+- One well-placed "don't" > three paragraphs of explanation.
+- Reasoning chains > example outputs. Show *how to think*, not *what to produce*.
+- Section >20 lines without teaching judgment → move to \`reference.md\`.
+
+**Test:** can someone reading 30 seconds make a better decision? If they need
+to read the whole thing for value, you've buried the judgment.
+
+## 5. Body skeleton
 
 \`\`\`markdown
-# <procedure>
+# <skill name>
 
-## When to run this
-Triggering condition.
+<1-paragraph: what + when to load>
 
-## Steps
-1. …
-2. …
+## When to use
+- <trigger>
 
-## Verification
-How to confirm success.
+## When NOT to use
+- <anti-trigger>
 
-## Rollback
-How to undo if something goes wrong.
+## The core decision
+<central judgment — usually a heuristic or framework>
+
+## <heuristic 1>
+<2–6 lines, brief (anti-)example>
+
+## <heuristic 2>
+…
+
+## Failure modes
+- **<name>**: what it looks like; how to avoid
+
+## Related
+- \`<other-skill>\` — interaction
+\`\`\`
+
+## 6. Progressive disclosure
+
+If deep reference is needed:
+
+\`\`\`
+<skill-dir>/
+  SKILL.md          # judgment layer — <150 lines
+  reference.md      # lookup layer
+  examples.md       # optional worked examples
 \`\`\`
 
-**\`glossary\`**
+SKILL.md *links* to siblings (\`see [reference.md](reference.md)\`). Agent
+loads supporting files only when needed.
 
+## 7. Verify
+
+\`\`\`
+crtr skill where <name>
+crtr skill show <name>
+crtr skill search <keyword>
+\`\`\`
+
+## Deep-dive reference
+
+For canonical SKILL.md authoring (frontmatter fields, argument passing,
+dynamic context, subagent forking, hooks):
+
+\`\`\`
+crtr skill show authoring-skills
+\`\`\`
+
+The playbook above gives you structure + density rules. \`authoring-skills\`
+covers the SKILL.md surface itself.
+
+## Constraints
+
+- Topic fails litmus? → \`crtr skill template freeform\` or \`primer\`.
+- No unconfirmed heuristics — if not from user experience or clear principle,
+  leave it out.
+- Update related skills' \`## Related\` if interactions exist.
+`;
+}
+function freeformTemplatePrompt(topic) {
+    return `# Freeform — escape hatch skill
+
+**Audience: future LLM agent sessions.** Use when content doesn't fit
+\`primer\` (codebase knowledge) or \`playbook\` (methodology) — glossaries,
+decisions, runbooks, lists, preferences.
+
+${topicLine(topic)}
+
+## 1. Pick a shape
+
+What kind of thing is this?
+
+- Terms + definitions → glossary-shaped
+- "We decided X, here's why" → decision-shaped
+- Procedure with steps + rollback → runbook-shaped
+- User preferences → preference-shaped
+- None of the above → freeform
+
+No strict template; the shape just tells you what to ask for.
+
+## 2. Interview
+
+\`AskUserQuestion\` (≤4, multi-choice, best-guess first). Get only what you
+need to write the skill. **No unconfirmed assumptions** — if not from user
+or grep, omit it.
+
+## 3. Scope + name + scaffold
+
+\`\`\`
+crtr skill new <name> --scope <user|project> --description "<what+when, ≤250 chars, front-loaded triggers>"
+\`\`\`
+
+## 4. Body — pick the closest skeleton
+
+**Glossary:**
 \`\`\`markdown
 # <domain> glossary
-
 | Term | Definition | Notes |
 |------|------------|-------|
-| … | … | … |
 \`\`\`
 
-**\`decision\`**
-
+**Decision:**
 \`\`\`markdown
-# <decision title> — <date>
-
+# <decision> — <date>
 ## Context
-What forced the decision.
-
 ## Decision
-What we chose.
-
 ## Consequences
-What this costs us. What it buys us.
-
 ## Alternatives considered
-- …
 \`\`\`
 
-## Step 6 — Verify the skill is discoverable
+**Runbook:**
+\`\`\`markdown
+# <procedure>
+## When to run
+## Steps
+## Verification
+## Rollback
+\`\`\`
+
+**Preference:**
+\`\`\`markdown
+# <preference>
+## Rule
+## Why
+## How to apply
+\`\`\`
+
+Or invent your own. Stay tight — no padding.
+
+## 5. Verify
 
 \`\`\`
-crtr skill where <name>            # confirm path/scope
-crtr skill list                    # confirm it shows up
-crtr skill show <name>             # confirm the body reads well
+crtr skill where <name>
+crtr skill show <name>
+crtr skill search <keyword>
 \`\`\`
 
-If \`description:\` doesn't trigger the right discoveries, sharpen it. If the
-body is bloated, cut it. Budget ~150 lines for SKILL.md; move deep reference
-into sibling files in the same directory.
+## Switch templates if needed
 
-## Constraints
+If the content is actually methodology or codebase knowledge:
 
-- Push back on trivial captures — if a one-line note in CLAUDE.md or a code
-  comment would do, suggest that instead.
-- Never write unconfirmed assumptions into the skill.
-- For updates to an existing skill, diff your draft against the current file
-  and call out what changed and why before writing.
-- Update related skills' \`## Related\` sections if you're adding something
-  that interacts with them.
+\`\`\`
+crtr skill template playbook ${topic ? topic : '<topic>'}
+crtr skill template primer ${topic ? topic : '<topic>'}
+\`\`\`
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",