@crouton-kit/crouter 0.1.9 → 0.2.3

package/dist/builtin-skills/.crouter-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "crtr",
+  "version": "0.2.0",
+  "description": "Builtin crouter skills — authoring guidance shipped with the binary"
+}

package/dist/builtin-skills/skills/crouter-development/marketplaces/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: crouter-development/marketplaces
+type: playbook
+description: How to author a crtr marketplace — marketplace.json index, plugin entries, symlink-based install, auto-bump CI, dual-publishing. Use when creating a marketplace or contributing plugins to one.
+keywords: [marketplace, marketplace.json, plugin, index, publishing]
+---
+
+# Authoring crtr marketplaces
+
+A **marketplace** is a git repo that indexes multiple plugins. Users register it once, then `crtr marketplace install <mkt>:<plugin>` symlinks any plugin from it. One `crtr marketplace update` pulls updates for every installed plugin at once.
+
+Audience: LLM agents creating a marketplace or adding plugins to an existing one.
+
+## When you need a marketplace (vs a single-plugin repo)
+
+A solo plugin ships from any git URL via `crtr plugin install <url>` — no marketplace needed.
+
+Reach for a marketplace when:
+- You want to publish ≥3 plugins under one brand or theme.
+- Users should install selectively without cloning each plugin's repo.
+- You want centralized version-bump automation across many plugins.
+
+If you have one plugin, ship it standalone. Promote to a marketplace later.
+
+## Directory layout
+
+```
+<marketplace-repo>/
+├── .crouter-marketplace/
+│   └── marketplace.json              # marketplace manifest — required
+└── plugins/
+    ├── plugin-a/
+    │   ├── .crouter-plugin/plugin.json
+    │   └── skills/...
+    └── plugin-b/
+        └── ...
+```
+
+Each entry under `plugins/` is a complete plugin (see [[crouter-development/plugins]]). The marketplace adds an index on top.
+
+## The manifest
+
+`.crouter-marketplace/marketplace.json`:
+
+```json
+{
+  "name": "my-marketplace",
+  "version": "0.3.0",
+  "owner": { "name": "Your Name", "email": "you@example.com" },
+  "plugins": [
+    {
+      "name": "plugin-a",
+      "version": "0.2.1",
+      "source": "https://github.com/<owner>/<repo>",
+      "description": "One sentence."
+    },
+    { "name": "plugin-b", "version": "0.1.0", "source": "…", "description": "…" }
+  ]
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `name` | yes | Lowercase kebab. |
+| `version` | yes | Semver. Bumps when any plugin bumps or when the marketplace manifest itself changes. |
+| `owner` | optional | |
+| `plugins` | yes | Array. Each entry: `name`, `version`, `source`, `description`. |
+
+The `plugins[]` array IS the index — what's installable. A plugin on disk but not in the index won't resolve. A plugin in the index but missing from disk errors on install.
+
+## Install mechanics — symlinks, not clones
+
+When a user runs `crtr marketplace install my-marketplace:plugin-a`:
+1. Crouter looks up `plugin-a` in the marketplace's manifest.
+2. **Symlinks** `<marketplace-clone>/plugins/plugin-a/` → `<user-scope>/plugins/plugin-a/`.
+3. Records the install in the scope config with `source_marketplace: my-marketplace`.
+
+Therefore one `crtr marketplace update my-marketplace` (which does `git pull` in the marketplace clone) updates every installed plugin from it — no per-plugin re-install, no second clone.
+
+## Version-bump automation (recommended)
+
+Bumping N plugin manifests + the index by hand is error-prone. The canonical pattern is a GitHub Actions workflow that bumps versions from commit subjects (conventional commits):
+
+| Commit subject | Bump |
+|---|---|
+| `feat!: …` or `BREAKING CHANGE` in body | major |
+| `feat: …` | minor |
+| anything else (`fix:`, `chore:`, `docs:`, …) | patch |
+
+Per commit:
+- For each plugin folder touched, both `plugins/<name>/.crouter-plugin/plugin.json` and the matching entry in `marketplace.json` get bumped.
+- Top-level `marketplace.json` version bumps when any plugin bumps OR the manifest itself was edited directly.
+- Newly-added plugins are skipped — they keep the version you committed.
+- Commits whose subject starts with `chore: release` are skipped to avoid loops.
+
+If you adopt this: **never edit `version` fields by hand**. CI will overwrite. Document this in the marketplace's CLAUDE.md.
+
+The crouter-official-marketplace repo's `.github/workflows/auto-bump.yml` is the reference implementation. Copy it.
+
+## Adding a plugin to a marketplace
+
+```bash
+cd <marketplace-repo>
+
+# Create the plugin (see [[crouter-development/plugins]] for plugin layout)
+mkdir -p plugins/my-new-plugin/.crouter-plugin plugins/my-new-plugin/skills
+$EDITOR plugins/my-new-plugin/.crouter-plugin/plugin.json
+
+# Add at least one skill
+crtr skill new my-new-plugin:first-skill --type playbook --description "Use when …"
+
+# Add the plugin to the marketplace index
+$EDITOR .crouter-marketplace/marketplace.json
+# (append to plugins[] with name, initial version, source, description)
+
+# Validate
+crtr doctor
+
+# Commit — CI bumps versions if you've wired up auto-bump
+git add -A
+git commit -m "feat: add my-new-plugin"
+git push
+```
+
+Existing users pick it up on their next `crtr marketplace update <marketplace-name>` (or on the next auto-update tick if they've set `auto_update.content: "apply"`).
+
+## Updating an existing plugin
+
+Edit content under `plugins/<name>/`. Commit with a conventional-commit subject. CI bumps the plugin manifest and the marketplace index entry together. No manual sync.
+
+## Removing a plugin
+
+Delete the plugin's directory AND its entry in `marketplace.json` → `plugins[]`. Commit with `feat!: remove <plugin>` to signal a major bump (the marketplace's contract changed for anyone depending on that plugin).
+
+## Marketplace registration scopes
+
+A marketplace itself registers per-scope:
+
+| Scope | Path | Use case |
+|---|---|---|
+| user | `~/.crouter/marketplaces/<name>/` | Private to your machine — your personal subscriptions |
+| project | `<project>/.crouter/marketplaces/<name>/` | Checked into the repo — anyone cloning gets the same marketplace pinned |
+
+`crtr marketplace add <git-url> --scope user` is the default. Use `--scope project` when the marketplace is integral to how the repo expects to be developed.
+
+## Validation
+
+`crtr doctor` checks marketplaces:
+- `marketplace.json` is valid JSON.
+- Every entry in `plugins[]` corresponds to a real directory under `plugins/`.
+- Each plugin under `plugins/` passes plugin-level validation.
+
+A plugin on disk but missing from the manifest is a **warning** (probably forgotten); a plugin in the manifest but missing on disk is an **error** (install would break).
+
+## Cross-publishing with Claude Code
+
+Some marketplaces ship a parallel `.claude-plugin/` tree so plugins can load directly into Claude Code without crtr. Optional. Sync the two manifests if you adopt it.

package/dist/builtin-skills/skills/crouter-development/plugins/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: crouter-development/plugins
+type: playbook
+description: How to author a crtr plugin — plugin.json manifest, directory layout, scopes, install mechanics, versioning. Use when creating a new plugin, packaging skills for distribution, or debugging install/resolution.
+keywords: [plugin, plugin.json, manifest, install, scope]
+---
+
+# Authoring crtr plugins
+
+A **plugin** is a directory shipping skills (and, in future, other artifact types like commands and hooks). Plugins are how you package skills for sharing across machines, projects, and people.
+
+Audience: LLM agents creating or maintaining a crtr plugin.
+
+## When you need a plugin (vs scope-owned skills)
+
+Scope-owned skills live at `~/.crouter/skills/` (user) or `<project>/.crouter/skills/` (project). They're personal and per-machine/per-repo.
+
+Reach for a **plugin** when:
+- You want to share skills across multiple projects or with other people.
+- You want versioning + update mechanics (`crtr plugin update`).
+- You want a marketplace to index the work — see [[crouter-development/marketplaces]].
+
+If it's a one-off note for yourself, scope-owned skills are simpler. Promote to a plugin later.
+
+## Directory layout
+
+```
+<plugin-name>/
+├── .crouter-plugin/
+│   └── plugin.json                  # manifest — required
+└── skills/
+    └── <skill-name>/
+        └── SKILL.md
+```
+
+The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Future artifact types (`commands/`, `hooks/`, etc.) will be sibling dirs to `skills/`.
+
+## The manifest
+
+`.crouter-plugin/plugin.json`:
+
+```json
+{
+  "name": "my-plugin",
+  "version": "0.1.0",
+  "description": "One sentence — shown in `crtr plugin list`.",
+  "source": "https://github.com/<owner>/<repo>",
+  "owner": {
+    "name": "Your Name",
+    "email": "you@example.com"
+  }
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `name` | yes | Must match the directory name. Lowercase kebab. |
+| `version` | yes | Semver. Marketplace CI may bump automatically — see marketplaces skill. |
+| `description` | yes | One sentence. |
+| `source` | recommended | Git URL where the plugin lives. Used by `crtr plugin update`. |
+| `owner` | optional | Author info. |
+
+## Scopes
+
+A plugin can live in either scope:
+
+| Scope | Path | Use case |
+|---|---|---|
+| user | `~/.crouter/plugins/<name>/` | Personal, available in all your projects |
+| project | `<project>/.crouter/plugins/<name>/` | Pinned to a specific repo — checked in or vendored |
+
+Project-scope plugins outrank user-scope on resolution. Both outrank marketplace-installed plugins. The builtin `crtr` plugin (ships with the CLI) sits at the bottom.
+
+## Install mechanics
+
+Three ways a plugin lands in a scope:
+
+1. **From a git URL** (`crtr plugin install <url> --scope user`):
+   - Clones into `<scope>/plugins/<name>/` using the manifest's name.
+   - `crtr plugin update <name>` does `git pull`.
+   - Independent of any marketplace.
+
+2. **From a marketplace** (`crtr marketplace install <mkt>:<name> --scope user`):
+   - **Symlinks** the marketplace's `plugins/<name>/` into `<scope>/plugins/<name>/`.
+   - One `crtr marketplace update <mkt>` pulls updates for every installed plugin from that marketplace.
+   - See [[crouter-development/marketplaces]].
+
+3. **Authored in place** (you're writing the plugin in a working repo):
+   - Symlink for tight dev loop: `ln -s $(pwd) ~/.crouter/plugins/<name>`.
+   - Or `crtr plugin install file://$(pwd) --scope project` to clone-install.
+
+## Local development loop
+
+```bash
+# Scaffold dir + manifest + first skill
+mkdir -p my-plugin/.crouter-plugin my-plugin/skills
+$EDITOR my-plugin/.crouter-plugin/plugin.json      # write the manifest
+cd my-plugin
+crtr skill new my-plugin:my-first-skill --type playbook --description "Use when …"
+
+# Symlink for fast iteration — no clone, edits land immediately
+ln -s $(pwd) ~/.crouter/plugins/my-plugin
+
+# Verify
+crtr plugin list                      # my-plugin appears
+crtr plugin show my-plugin            # lists its skills
+crtr skill list --plugin my-plugin
+crtr doctor                           # validates manifest + every skill
+```
+
+When ready to share: push to a git remote; anyone can `crtr plugin install <url>`.
+
+## Versioning
+
+Standard semver:
+
+| Change | Bump |
+|---|---|
+| Typo, wording polish | patch (0.1.0 → 0.1.1) |
+| New skill, new section, new example | minor (0.1.0 → 0.2.0) |
+| Removed skill, renamed skill, changed manifest schema | major (0.1.0 → 1.0.0) |
+
+`crtr plugin update <name>` reads the new version after pulling and updates the local config. Plugins published through a marketplace may have their `version` field bumped automatically by CI — see [[crouter-development/marketplaces]].
+
+## Enable/disable
+
+`crtr plugin disable <name>` flips the per-scope config without removing files. Disabled plugins are hidden from `crtr skill list` and don't resolve via `crtr skill show <name>`. Re-enable with `crtr plugin enable <name>`.
+
+Individual skills inside an enabled plugin can also be disabled: `crtr skill disable <plugin>:<skill>`.
+
+## What goes in a plugin
+
+Good plugin scope:
+- A coherent set of related skills (3–15 typical) sharing a theme.
+- All skills serve the same user persona or workflow.
+- Versioned together — a bump means a bump for the whole set.
+
+Bad plugin scope:
+- One mega-plugin with every skill you've ever written. Hard to install selectively, hard to version.
+- A plugin per single skill. No value-add over scope-owned skills.
+
+## Cross-plugin etiquette
+
+If your skill conceptually depends on another plugin's skill, link via `## Related` with `` `<plugin>/<skill>` ``. Don't fork content; link it.
+
+## Validation
+
+`crtr doctor` checks every plugin:
+- Manifest exists and is valid JSON.
+- Manifest `name` matches the directory name.
+- Every skill under `skills/` passes the skill-validation contract (frontmatter parses, `name` matches dir path, `type` in enum). Run `crtr skill` (no args) for the full format reference.
+- Sibling artifact dirs (`commands/`, `hooks/`, etc.) — validated by their respective specs as those land.
+
+## Cross-publishing with Claude Code
+
+Some plugins also publish a `.claude-plugin/` manifest alongside `.crouter-plugin/` so they can be loaded directly into Claude Code without going through crtr. Optional. Only worth doing when your skills/commands meaningfully stand alone in the Claude Code surface. Keep manifests in sync if you do.

package/dist/commands/doctor.js

@@ -1,10 +1,12 @@
 import { join } from 'node:path';
+import { SKILL_TYPES, isSkillType } from '../types.js';
 import { out, jsonOut, handleError, stdoutColor } from '../core/output.js';
-import { scopeRoot, pluginsDir, marketplacesDir, listScopes } from '../core/scope.js';
+import { scopeRoot, pluginsDir, marketplacesDir, listScopes, builtinSkillsRoot } from '../core/scope.js';
 import { readConfig, updateConfig } from '../core/config.js';
 import { listInstalledPlugins, listSkillsInPlugin } from '../core/resolver.js';
-import { pathExists, listDirs, removePath } from '../core/fs-utils.js';
+import { pathExists, listDirs, removePath, readText } from '../core/fs-utils.js';
 import { readPluginManifest, readMarketplaceManifest } from '../core/manifest.js';
+import { parseFrontmatter } from '../core/frontmatter.js';
 import { lsRemote } from '../core/git.js';
 import { ExitCode } from '../types.js';
 function pass(scope, name, message) {
@@ -16,7 +18,46 @@ function fail(scope, name, message) {
 function warn(scope, name, message) {
     return { scope, name, status: 'warn', message };
 }
+function readRawTypeField(skillPath) {
+    const content = readText(skillPath);
+    const { raw } = parseFrontmatter(content);
+    if (!raw)
+        return undefined;
+    const m = raw.match(/^type:\s*(.+?)\s*$/m);
+    if (!m)
+        return undefined;
+    let v = m[1].trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+    }
+    return v;
+}
+function runChecksForBuiltin() {
+    const root = builtinSkillsRoot();
+    const plugins = listInstalledPlugins('builtin');
+    if (plugins.length === 0) {
+        return [fail('builtin', 'builtin:crtr:root', `builtin-skills root missing or has no valid plugin.json: ${root}`)];
+    }
+    const results = [
+        pass('builtin', 'builtin:crtr:root', `builtin-skills root present: ${root}`),
+    ];
+    for (const plugin of plugins) {
+        results.push(pass('builtin', `builtin:${plugin.name}:manifest`, `manifest valid`));
+        const skills = listSkillsInPlugin(plugin);
+        for (const skill of skills) {
+            if (!skill.frontmatter.name) {
+                results.push(fail('builtin', `builtin:${plugin.name}:skill:${skill.name}:frontmatter`, `frontmatter missing or name field empty`));
+            }
+            else {
+                results.push(pass('builtin', `builtin:${plugin.name}:skill:${skill.name}:frontmatter`, `frontmatter valid`));
+            }
+        }
+    }
+    return results;
+}
 function runChecksForScope(scope, opts) {
+    if (scope === 'builtin')
+        return runChecksForBuiltin();
     const results = [];
     const root = scopeRoot(scope);
     if (!root)
@@ -138,6 +179,17 @@ function runChecksForScope(scope, opts) {
                     else {
                         results.push(pass(scope, `plugin:${name}:skill:${skill.name}:frontmatter`, `frontmatter valid`));
                     }
+                    const typeCheckName = `plugin:${name}:skill:${skill.name}:type`;
+                    const rawType = readRawTypeField(skill.path);
+                    if (rawType === undefined) {
+                        results.push(warn(scope, typeCheckName, `missing type field — add one of: ${SKILL_TYPES.join(' | ')}`));
+                    }
+                    else if (!isSkillType(rawType)) {
+                        results.push(fail(scope, typeCheckName, `invalid type "${rawType}" — valid: ${SKILL_TYPES.join(' | ')}`));
+                    }
+                    else {
+                        results.push(pass(scope, typeCheckName, `type: ${rawType}`));
+                    }
                 }
             }
             // Git remote check (slow, opt-in)

package/dist/commands/plugin.js

@@ -178,10 +178,13 @@ export function registerPluginCommands(program) {
         .option('--yes', 'skip confirmation in non-TTY mode')
         .action(async (name, opts) => {
         try {
+            if (name === 'crtr') {
+                throw usage(`cannot uninstall builtin plugin "crtr" — it ships with the binary`);
+            }
             if (!isTTY() && !opts.yes) {
                 throw usage(`uninstall requires --yes in non-TTY mode: crtr plugin uninstall ${name} --yes`);
             }
-            const scopes = listScopes(opts.scope);
+            const scopes = listScopes(opts.scope).filter((s) => s !== 'builtin');
             let removed = false;
             for (const scope of scopes) {
                 const pDir = pluginsDir(scope);

package/dist/commands/skill.js

@@ -1,11 +1,11 @@
 import { join } from 'node:path';
 import { writeFileSync } from 'node:fs';
-import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, } from '../types.js';
+import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, SKILL_TYPES, isSkillType, } from '../types.js';
 import { skillConfigKey } from '../types.js';
 import { notFound, usage, general } from '../core/errors.js';
 import { out, hint, info, jsonOut, handleError, } from '../core/output.js';
 import { listScopes, requireScopeRoot, resolveScopeArg, projectScopeRoot, scopeSkillsDir, } from '../core/scope.js';
-import { resolveSkill, listAllSkills, listInstalledPlugins, findPluginByName, parseSkillQualifier, } from '../core/resolver.js';
+import { resolveSkill, listAllSkills, listInstalledPlugins, findPluginByName, parseSkillQualifier, listSkillSiblings, listSkillChildren, } from '../core/resolver.js';
 import { updateConfig, ensureScopeInitialized } from '../core/config.js';
 import { parseFrontmatter, serializeFrontmatter } from '../core/frontmatter.js';
 import { ensureDir, pathExists, readText, walkFiles } from '../core/fs-utils.js';
@@ -23,14 +23,53 @@ const KNOWN_VERBS = new Set([
     'disable',
     'search',
 ]);
-const AUTHORING_GUIDE_SKILL = 'authoring-skills';
 function buildShowFooter(skillPath) {
     return (`crtr: edit this skill directly at ${skillPath} — ` +
-        `for SKILL.md authoring guidance run \`crtr skill ${AUTHORING_GUIDE_SKILL}\``);
+        `for SKILL.md format + authoring workflow run \`crtr skill\` (no args)`);
 }
 function wrapSkill(name, path, content) {
     return `<skill name="${name}" path="${path}">\n${content.endsWith('\n') ? content : content + '\n'}</skill>`;
 }
+function formatNeighborQualifier(s) {
+    return s.plugin === SCOPE_SKILL_PLUGIN ? `${s.scope}:${s.name}` : `${s.plugin}/${s.name}`;
+}
+function buildNeighborsSection(skill) {
+    const siblings = listSkillSiblings(skill);
+    const children = listSkillChildren(skill);
+    if (siblings.length === 0 && children.length === 0)
+        return null;
+    const lines = [
+        '## Neighbors',
+        '*Auto-discovered from filesystem. Use `--no-neighbors` to suppress.*',
+        '',
+    ];
+    if (siblings.length > 0) {
+        lines.push('**Siblings:**');
+        for (const s of siblings) {
+            const desc = s.frontmatter.description !== undefined ? s.frontmatter.description : '';
+            lines.push(`- \`${formatNeighborQualifier(s)}\`${desc ? ` — ${desc}` : ''}`);
+        }
+        if (children.length > 0)
+            lines.push('');
+    }
+    if (children.length > 0) {
+        lines.push('**Nested:**');
+        for (const s of children) {
+            const desc = s.frontmatter.description !== undefined ? s.frontmatter.description : '';
+            lines.push(`- \`${formatNeighborQualifier(s)}\`${desc ? ` — ${desc}` : ''}`);
+        }
+    }
+    return lines.join('\n');
+}
+function appendNeighbors(skill, body, suppress) {
+    if (suppress)
+        return body;
+    const section = buildNeighborsSection(skill);
+    if (section === null)
+        return body;
+    const sep = body.endsWith('\n') ? '\n' : '\n\n';
+    return body + sep + `<neighbors>\n${section}\n</neighbors>\n`;
+}
 const SKILL_IDENTIFIER_HELP = 'Skill identifier forms (accepted by show, path, where, enable, disable):\n' +
     '  <name>                       bare name — resolves scope-root first, then plugins\n' +
     '  <plugin>:<name>              explicit plugin (canonical)\n' +
@@ -52,7 +91,8 @@ export function registerSkillCommands(program) {
             try {
                 const skillObj = resolveSkill(nameOrVerb);
                 const content = readText(skillObj.path);
-                const body = opts.frontmatter ? content : parseFrontmatter(content).body;
+                const rawBody = opts.frontmatter ? content : parseFrontmatter(content).body;
+                const body = appendNeighbors(skillObj, rawBody, false);
                 out(wrapSkill(skillObj.name, skillObj.path, body));
                 hint(buildShowFooter(skillObj.path));
             }
@@ -117,6 +157,7 @@ export function registerSkillCommands(program) {
         .option('--scope <scope>', 'user|project')
         .option('--plugin <name>', 'filter by plugin name')
         .option('--frontmatter', 'include YAML frontmatter in the printed body')
+        .option('--no-neighbors', 'suppress the auto-appended ## Neighbors section')
         .option('--json', 'emit JSON')
         .addHelpText('after', '\nExamples:\n' +
         '  crtr skill show rules                              # bare name\n' +
@@ -133,7 +174,9 @@ export function registerSkillCommands(program) {
             }
             const skillObj = resolveSkill(name, resolveOpts);
             const content = readText(skillObj.path);
-            const body = opts.frontmatter ? content : parseFrontmatter(content).body;
+            const rawBody = opts.frontmatter ? content : parseFrontmatter(content).body;
+            const suppressNeighbors = opts.neighbors === false;
+            const body = appendNeighbors(skillObj, rawBody, suppressNeighbors);
             if (opts.json) {
                 jsonOut({
                     name: skillObj.name,
@@ -141,7 +184,7 @@ export function registerSkillCommands(program) {
                     scope: skillObj.scope,
                     path: skillObj.path,
                     content,
-                    authoring_guide_command: `crtr skill ${AUTHORING_GUIDE_SKILL}`,
+                    authoring_guide_command: `crtr skill`,
                 });
                 return;
             }
@@ -235,12 +278,20 @@ export function registerSkillCommands(program) {
         .description('scaffold a new skill — <name> (scope-direct) or <plugin>:<name>')
         .option('--scope <scope>', 'user|project (default: project then user)')
         .option('--description <text>', 'skill description for frontmatter')
+        .option('--type <type>', `skill type for frontmatter — one of: ${SKILL_TYPES.join(' | ')}`)
         .action(async (qualifier, opts) => {
         try {
             const { plugin: pluginName, name: skillName } = parseSkillQualifier(qualifier);
             if (!skillName) {
                 throw usage('skill name required');
             }
+            let skillType;
+            if (opts.type !== undefined) {
+                if (!isSkillType(opts.type)) {
+                    throw usage(`unknown skill type: ${opts.type} / valid: ${SKILL_TYPES.join(' | ')}`);
+                }
+                skillType = opts.type;
+            }
             const scopeArg = opts.scope !== undefined ? resolveScopeArg(opts.scope) : undefined;
             // Scope-direct: no plugin qualifier, or explicit `_:` sentinel
             if (pluginName === undefined || pluginName === SCOPE_SKILL_PLUGIN) {
@@ -266,11 +317,13 @@ export function registerSkillCommands(program) {
                 const fm = serializeFrontmatter({
                     name: skillName,
                     description: opts.description,
+                    type: skillType,
                 });
                 writeFileSync(skillFile, fm, 'utf8');
                 out(skillFile);
-                hint(`crtr: scaffolded ${scope}-scope skill ${skillName} — edit directly, then ` +
-                    `\`crtr skill ${AUTHORING_GUIDE_SKILL}\` for SKILL.md authoring guidance`);
+                const templateHint = skillType !== undefined ? skillType : '<type>';
+                hint(`crtr: scaffolded ${scope}-scope skill ${skillName} — edit directly; ` +
+                    `\`crtr skill template ${templateHint}\` for body skeleton`);
                 return;
             }
             let plugin;
@@ -292,11 +345,13 @@ export function registerSkillCommands(program) {
             const fm = serializeFrontmatter({
                 name: skillName,
                 description: opts.description,
+                type: skillType,
             });
             writeFileSync(skillFile, fm, 'utf8');
             out(skillFile);
-            hint(`crtr: scaffolded ${skillFile} — edit directly, then ` +
-                `\`crtr skill ${AUTHORING_GUIDE_SKILL}\` for SKILL.md authoring guidance`);
+            const templateHint = skillType !== undefined ? skillType : '<type>';
+            hint(`crtr: scaffolded ${skillFile} — edit directly; ` +
+                `\`crtr skill template ${templateHint}\` for body skeleton`);
         }
         catch (e) {
             handleError(e);
@@ -305,7 +360,7 @@ export function registerSkillCommands(program) {
     // create — pick a template type
     skill
         .command('create [topic...]')
-        .description('pick a template type for a new skill (primer | playbook | freeform)')
+        .description(`pick a template type for a new skill (${SKILL_TYPES.join(' | ')})`)
         .action(async (topic) => {
         const arg = topic && topic.length > 0 ? topic.join(' ') : '';
         out(skillCreatePrompt(arg));
@@ -313,7 +368,7 @@ export function registerSkillCommands(program) {
     // template — full workflow + skeleton for one template type
     skill
         .command('template <type> [topic...]')
-        .description('full workflow + skeleton for a template type (primer | playbook | freeform)')
+        .description(`full workflow + skeleton for a template type (${SKILL_TYPES.join(' | ')})`)
         .action(async (type, topic) => {
         const arg = topic && topic.length > 0 ? topic.join(' ') : '';
         out(skillTemplatePrompt(type, arg));

package/dist/core/frontmatter.d.ts

@@ -1,4 +1,4 @@
-import type { SkillFrontmatter } from '../types.js';
+import { type SkillFrontmatter } from '../types.js';
 export interface ParsedFrontmatter {
     data: SkillFrontmatter | null;
     body: string;

package/dist/core/frontmatter.js

@@ -1,3 +1,4 @@
+import { isSkillType } from '../types.js';
 const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
 export function parseFrontmatter(source) {
     const match = source.match(FRONTMATTER_RE);
@@ -126,6 +127,7 @@ function parseSimpleYaml(yaml) {
         name: typeof out.name === 'string' ? out.name : '',
         description: typeof out.description === 'string' ? out.description : undefined,
         keywords: Array.isArray(out.keywords) ? out.keywords : undefined,
+        type: isSkillType(out.type) ? out.type : undefined,
     };
     return fm;
 }
@@ -141,6 +143,9 @@ export function serializeFrontmatter(data) {
     if (data.description !== undefined) {
         lines.push(`description: ${quoteIfNeeded(data.description)}`);
     }
+    if (data.type !== undefined) {
+        lines.push(`type: ${data.type}`);
+    }
     if (data.keywords && data.keywords.length) {
         const inline = `[${data.keywords.map(quoteIfNeeded).join(', ')}]`;
         lines.push(`keywords: ${inline}`);

package/dist/core/resolver.d.ts

@@ -13,6 +13,8 @@ export declare function effectiveSkillEnabled(pluginName: string, skillName: str
 export declare function listSkillsInPlugin(plugin: InstalledPlugin, cfgs?: ScopeConfigs): Skill[];
 export declare function listScopeRootSkills(scope: Scope, cfgs?: ScopeConfigs): Skill[];
 export declare function listAllSkills(scopeFilter?: Scope): Skill[];
+export declare function listSkillSiblings(skill: Skill): Skill[];
+export declare function listSkillChildren(skill: Skill): Skill[];
 export interface SkillResolutionOpts {
     scope?: Scope;
     pluginFilter?: string;

package/dist/core/resolver.js

@@ -5,8 +5,29 @@ import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { ambiguous, notFound, usage } from './errors.js';
-import { marketplacesDir, pluginsDir, projectScopeRoot, scopeSkillsDir, userScopeRoot, } from './scope.js';
+import { builtinSkillsRoot, marketplacesDir, pluginsDir, projectScopeRoot, scopeSkillsDir, userScopeRoot, } from './scope.js';
+function getBuiltinPlugin() {
+    const root = builtinSkillsRoot();
+    if (!pathExists(root))
+        return null;
+    const manifest = readPluginManifest(root);
+    if (!manifest)
+        return null;
+    return {
+        name: manifest.name,
+        scope: 'builtin',
+        root,
+        manifest,
+        enabled: true,
+        builtin: true,
+        version: manifest.version,
+    };
+}
 export function listInstalledPlugins(scope) {
+    if (scope === 'builtin') {
+        const builtin = getBuiltinPlugin();
+        return builtin ? [builtin] : [];
+    }
     const dir = pluginsDir(scope);
     if (!dir || !pathExists(dir))
         return [];
@@ -40,13 +61,14 @@ export function listAllPlugins() {
     if (projectScopeRoot())
         scopes.push('project');
     scopes.push('user');
+    scopes.push('builtin');
     return scopes.flatMap(listInstalledPlugins);
 }
 export function findPluginByName(name, scope) {
     if (scope) {
         return listInstalledPlugins(scope).find((p) => p.name === name) ?? null;
     }
-    for (const s of ['project', 'user'].filter((sc) => sc === 'project' ? projectScopeRoot() !== null : true)) {
+    for (const s of ['project', 'user', 'builtin'].filter((sc) => sc === 'project' ? projectScopeRoot() !== null : true)) {
         const match = listInstalledPlugins(s).find((p) => p.name === name);
         if (match)
             return match;
@@ -100,6 +122,8 @@ export function listSkillsInPlugin(plugin, cfgs) {
     return skills.sort((a, b) => a.name.localeCompare(b.name));
 }
 export function listScopeRootSkills(scope, cfgs) {
+    if (scope === 'builtin')
+        return [];
     const skillsRoot = scopeSkillsDir(scope);
     if (!skillsRoot || !pathExists(skillsRoot))
         return [];
@@ -138,6 +162,41 @@ export function listAllSkills(scopeFilter) {
         ...plugins.filter((p) => p.enabled).flatMap((p) => listSkillsInPlugin(p, cfgs)),
     ];
 }
+function enumerateNeighborPool(skill) {
+    if (skill.plugin === SCOPE_SKILL_PLUGIN) {
+        return listScopeRootSkills(skill.scope);
+    }
+    const plugin = listInstalledPlugins(skill.scope).find((p) => p.name === skill.plugin);
+    if (!plugin)
+        return [];
+    return listSkillsInPlugin(plugin);
+}
+export function listSkillSiblings(skill) {
+    const pool = enumerateNeighborPool(skill);
+    const segs = skill.name.split('/');
+    const depth = segs.length;
+    const parentPrefix = segs.slice(0, -1).join('/');
+    return pool.filter((s) => {
+        if (s.name === skill.name)
+            return false;
+        const sSegs = s.name.split('/');
+        if (sSegs.length !== depth)
+            return false;
+        if (parentPrefix === '')
+            return !s.name.includes('/');
+        return s.name.startsWith(parentPrefix + '/');
+    });
+}
+export function listSkillChildren(skill) {
+    const pool = enumerateNeighborPool(skill);
+    const prefix = skill.name + '/';
+    return pool.filter((s) => {
+        if (!s.name.startsWith(prefix))
+            return false;
+        const rest = s.name.slice(prefix.length);
+        return rest.length > 0 && !rest.includes('/');
+    });
+}
 export function resolveSkill(rawName, opts = {}) {
     const parsed = parseSkillQualifier(rawName);
     if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
@@ -353,6 +412,8 @@ export function parseSkillQualifier(raw) {
 }
 function orderPluginsByResolution(plugins) {
     const score = (p) => {
+        if (p.scope === 'builtin')
+            return 4;
         const fromMarketplace = Boolean(p.sourceMarketplace);
         if (p.scope === 'project' && !fromMarketplace)
             return 0;

package/dist/core/scope.d.ts

@@ -1,4 +1,5 @@
 import type { Scope } from '../types.js';
+export declare function builtinSkillsRoot(): string;
 export declare function userScopeRoot(): string;
 export declare function findProjectScopeRoot(startDir?: string): string | null;
 export declare function projectScopeRoot(startDir?: string): string | null;

package/dist/core/scope.js

@@ -1,9 +1,17 @@
 import { homedir } from 'node:os';
 import { existsSync, statSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { CRTR_DIR_NAME } from '../types.js';
 import { usage } from './errors.js';
 let cachedProjectRoot;
+export function builtinSkillsRoot() {
+    // Resolve relative to this file: src/core/scope.ts → src/builtin-skills/ OR dist/core/scope.js → dist/builtin-skills/
+    const thisFile = fileURLToPath(import.meta.url);
+    const coreDir = dirname(thisFile);
+    const pkgDir = dirname(coreDir); // src/ or dist/
+    return join(pkgDir, 'builtin-skills');
+}
 export function userScopeRoot() {
     return join(homedir(), CRTR_DIR_NAME);
 }
@@ -37,6 +45,8 @@ export function projectScopeRoot(startDir) {
     return findProjectScopeRoot(startDir);
 }
 export function scopeRoot(scope) {
+    if (scope === 'builtin')
+        return builtinSkillsRoot();
     return scope === 'user' ? userScopeRoot() : projectScopeRoot();
 }
 export function requireScopeRoot(scope) {
@@ -71,9 +81,9 @@ export function resolveScopeArg(scopeArg) {
     if (scopeArg === undefined)
         return 'all';
     const value = scopeArg.toLowerCase();
-    if (value === 'user' || value === 'project' || value === 'all')
+    if (value === 'user' || value === 'project' || value === 'builtin' || value === 'all')
         return value;
-    throw usage(`invalid --scope: ${scopeArg} (expected user|project|all)`);
+    throw usage(`invalid --scope: ${scopeArg} (expected user|project|builtin|all)`);
 }
 export function listScopes(scopeArg) {
     const v = resolveScopeArg(scopeArg);
@@ -82,6 +92,7 @@ export function listScopes(scopeArg) {
         if (projectScopeRoot())
             out.push('project');
         out.push('user');
+        out.push('builtin');
         return out;
     }
     return [v];

package/dist/prompts/skill.js

@@ -48,14 +48,49 @@ crtr skill where <name>            # {scope, plugin, path} JSON
 ## Author (progressive disclosure)
 
 \`\`\`
-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
+crtr skill create [topic...]            # pick a template type
+crtr skill template <type> [topic]      # workflow + skeleton for that type
+crtr skill new <name> --type <type>     # bare scaffold with typed frontmatter
 \`\`\`
 
+Five types — pick by what the agent does after reading:
+
+- \`playbook\` — decide (judgment, heuristics, when-to-use)
+- \`primer\` — navigate (codebase facts, architecture)
+- \`reference\` — look up (stable facts, tables)
+- \`runbook\` — execute (numbered procedure)
+- \`freeform\` — none of the above (catchall)
+
 Don't load \`create\` and \`template\` in the same turn — \`create\` decides the
 type, then call \`template\`.
 
+## Format
+
+A skill is a directory; \`SKILL.md\` is its entry file. The dir IS the skill —
+siblings are assets, nested dirs are themselves skills.
+
+Frontmatter (required: \`name\`, \`type\`, \`description\`):
+- \`name\` — must equal the dir path under \`skills/\`. Slashes for nested
+  (\`skills/web/frontend/design/SKILL.md\` → \`name: web/frontend/design\`).
+- \`type\` — one of the five above.
+- \`description\` — one sentence, front-load with "Use when…" — drives discovery.
+- \`keywords\` (optional) — array of strings, improves \`crtr skill search\`.
+
+Intermediate dirs (\`web/\`, \`web/frontend/\`) don't need their own SKILL.md —
+nesting is purely path-based. Budget ~150 lines per SKILL.md body; spill
+deeper material into sibling files (\`reference.md\`, \`examples.md\`).
+
+Validate with \`crtr doctor\` — checks frontmatter, name-vs-path match, type
+enum, sibling-link reachability.
+
+## Neighbors auto-append
+
+\`crtr skill show <name>\` appends a \`## Neighbors\` section listing siblings
+(same parent dir) and nested skills. Skill bodies should write \`## Related\`
+**only** for cross-plugin or distant refs — within-plugin links are redundant.
+
+Suppress with \`crtr skill show <name> --no-neighbors\`.
+
 ## Toggle
 
 \`\`\`
@@ -81,11 +116,22 @@ ${topicLine}
 
 ## Templates
 
-- \`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).
+Pick by what the agent does after reading the skill:
+
+- \`playbook\` — **decide**. Judgment, heuristics, when-to-use / when-not-to-use.
+  Examples: skill-authoring, debugging methodology. Most skills are this.
+- \`primer\` — **navigate**. Codebase/architectural facts. *"How does this
+  subsystem work, why, what are the gotchas."* Triggers parallel-explore.
+- \`reference\` — **look up**. Stable facts: protocol fields, API surface,
+  glossaries, lookup tables. Source of truth is external (spec, docs).
+- \`runbook\` — **execute**. Numbered procedure with decision points and
+  rollback. Examples: deploy, incident response, review workflow.
+- \`freeform\` — **none of the above**. Catchall for decision records, prefs,
+  miscellany.
+
+Litmus: *"when X, do Y"* → playbook. *"these are the fields of Y"* →
+reference. *"step 1, step 2, step 3"* → runbook. *"how X is built inside
+this repo"* → primer.
 
 ## Next
 
@@ -103,6 +149,7 @@ ${topicLine}
 
 - 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.
+- Content is one-off lookup that lives elsewhere → link to it, don't mirror.
 `;
 }
 export function skillTemplatePrompt(type, topic) {
@@ -111,9 +158,13 @@ export function skillTemplatePrompt(type, topic) {
         return primerTemplatePrompt(topic);
     if (t === 'playbook')
         return playbookTemplatePrompt(topic);
+    if (t === 'reference')
+        return referenceTemplatePrompt(topic);
+    if (t === 'runbook')
+        return runbookTemplatePrompt(topic);
     if (t === 'freeform')
         return freeformTemplatePrompt(topic);
-    return `unknown template type: ${type}\nvalid: primer | playbook | freeform\nrun \`crtr skill create\` to pick.\n`;
+    return `unknown template type: ${type}\nvalid: playbook | primer | reference | runbook | freeform\nrun \`crtr skill create\` to pick.\n`;
 }
 function topicLine(topic) {
     return topic
@@ -176,7 +227,7 @@ assumptions.**
 ## 5. Scaffold
 
 \`\`\`
-crtr skill new <name> --scope project --description "<what+when, ≤250 chars, front-loaded triggers>"
+crtr skill new <name> --type primer --scope project --description "<what+when, ≤250 chars, front-loaded triggers>"
 \`\`\`
 
 ## 6. Write the body
@@ -204,11 +255,12 @@ Domain terms, invariants, non-obvious constraints.
 
 ## Gotchas
 Non-obvious coupling. Looks-broken-but-isn't. Past footguns.
-
-## Related
-- \`<other-skill>\` — interaction
 \`\`\`
 
+**No \`## Related\` for within-plugin siblings** — the CLI auto-appends a
+\`## Neighbors\` section on \`crtr skill show\`. Add a manual \`## Related\`
+only for cross-plugin or distant refs.
+
 **Density rules:**
 - \`file:line\` over prose
 - Tables where structure fits
@@ -229,7 +281,7 @@ Sharpen description if discovery misses. Cut body if bloated.
 ## Updates
 
 If updating existing primer: diff draft vs current, call out changes + why
-before writing. Update related skills' \`## Related\` sections.
+before writing.
 `;
 }
 function playbookTemplatePrompt(topic) {
@@ -275,7 +327,7 @@ PR over many small ones for refactors here, because review churn dominates"*
 ## 3. Scaffold
 
 \`\`\`
-crtr skill new <name> --scope <user|project> --description "<what it teaches + when to load, ≤250 chars, front-loaded triggers>"
+crtr skill new <name> --type playbook --scope <user|project> --description "<what it teaches + when to load, ≤250 chars, front-loaded triggers>"
 \`\`\`
 
 ## 4. Density rules
@@ -314,11 +366,12 @@ to read the whole thing for value, you've buried the judgment.
 
 ## Failure modes
 - **<name>**: what it looks like; how to avoid
-
-## Related
-- \`<other-skill>\` — interaction
 \`\`\`
 
+**No \`## Related\` for within-plugin siblings** — the CLI auto-appends a
+\`## Neighbors\` section on \`crtr skill show\`. Add a manual \`## Related\`
+only for cross-plugin or distant refs.
+
 ## 6. Progressive disclosure
 
 If deep reference is needed:
@@ -341,24 +394,11 @@ 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\`.
+- Topic fails litmus? → \`crtr skill template freeform\`, \`reference\`, or \`runbook\`.
 - No unconfirmed heuristics — if not from user experience or clear principle,
   leave it out.
-- Update related skills' \`## Related\` if interactions exist.
 `;
 }
 function freeformTemplatePrompt(topic) {
@@ -391,7 +431,7 @@ or grep, omit it.
 ## 3. Scope + name + scaffold
 
 \`\`\`
-crtr skill new <name> --scope <user|project> --description "<what+when, ≤250 chars, front-loaded triggers>"
+crtr skill new <name> --type freeform --scope <user|project> --description "<what+when, ≤250 chars, front-loaded triggers>"
 \`\`\`
 
 ## 4. Body — pick the closest skeleton
@@ -441,11 +481,226 @@ crtr skill search <keyword>
 
 ## Switch templates if needed
 
-If the content is actually methodology or codebase knowledge:
+Content actually fits a typed template?
 
 \`\`\`
-crtr skill template playbook ${topic ? topic : '<topic>'}
-crtr skill template primer ${topic ? topic : '<topic>'}
+crtr skill template playbook ${topic ? topic : '<topic>'}     # decide
+crtr skill template primer ${topic ? topic : '<topic>'}       # navigate codebase
+crtr skill template reference ${topic ? topic : '<topic>'}    # look up stable facts
+crtr skill template runbook ${topic ? topic : '<topic>'}      # execute a procedure
 \`\`\`
 `;
 }
+function referenceTemplatePrompt(topic) {
+    return `# Reference — lookup-fact skill
+
+**Audience: future LLM agent sessions.** Captures *stable lookup facts* an
+agent will grep or scan: protocol fields, API surfaces, glossaries, enum
+tables, status-code maps. Source of truth lives *outside* the skill (RFC,
+spec, vendor docs); the skill is a fast in-repo cache.
+
+${topicLine(topic)}
+
+## Litmus test
+
+> Would you *grep* this rather than *read* it?
+
+If you'd skim end-to-end → it's not reference. If you'd jump straight to
+the row you need → reference. If you'd make a decision after reading →
+\`crtr skill template playbook\`. If you'd execute steps → \`runbook\`.
+
+**Reference markers:** mostly tables · stable across releases · authoritative
+source elsewhere · agent loads to *answer*, not to *think*.
+
+## 1. Confirm reference, not playbook
+
+Use \`AskUserQuestion\` (≤4, multi-choice, best-guess first):
+
+- The lookup the agent will perform (e.g., "what does HTTP 423 mean")
+- Stability: does this change every release? If yes, push back — link the
+  upstream source instead of mirroring it.
+- Authoritative source URL (cite in the body)
+
+Skip if the topic is clearly facts (RFCs, public API). **Never invent
+field/flag/code values** — pull verbatim from source.
+
+## 2. Scope + name
+
+- **Scope**: \`user\` for cross-project facts. \`project\` for repo-specific.
+- **Name**: noun-phrase. \`http-status-codes\` not \`learn-http-status\`.
+- Check \`crtr skill where <name>\`.
+
+## 3. Scaffold
+
+\`\`\`
+crtr skill new <name> --type reference --scope <user|project> --description "<what to look up + when to load, ≤250 chars>"
+\`\`\`
+
+## 4. Density rules
+
+Reference skills are *load and scan*, not *load and read*. Optimize for jump-to-row.
+
+- Tables for anything multi-row. Columns: most-queried field first.
+- One topic per file. Split if it doesn't fit one screen.
+- Source URL at the top — agent verifies before trusting cached facts.
+- No prose paragraphs longer than 2 lines.
+- Skip *why* — playbooks teach why. Reference teaches what.
+
+## 5. Body skeleton
+
+\`\`\`markdown
+# <topic> reference
+
+**Source of truth:** <URL or spec name>
+**Last verified:** <date — when an agent should re-check>
+
+## <table 1 title>
+| <field> | <value> | <notes> |
+|---------|---------|---------|
+| …       | …       | …       |
+
+## <table 2 title>
+…
+
+## Edge cases / gotchas
+- Brief bullets. *What* is misleading, not *why*.
+\`\`\`
+
+**No \`## Related\` for within-plugin siblings** — auto-appended by the CLI.
+
+## 6. Progressive disclosure
+
+If reference is large, split:
+
+\`\`\`
+<skill-dir>/
+  SKILL.md           # top-level index + most-queried table
+  full-table.md      # the full set
+  examples.md        # rarely-needed worked examples
+\`\`\`
+
+SKILL.md links to siblings (\`see [full-table.md](full-table.md)\`).
+
+## 7. Verify
+
+\`\`\`
+crtr skill where <name>
+crtr skill show <name>
+crtr skill search <keyword>
+\`\`\`
+
+Search must surface the skill on a typical lookup query. Sharpen the
+description if it doesn't.
+
+## Constraints
+
+- No invented values. If you can't cite the source, leave the row out.
+- Topic teaches *judgment*, not facts? → \`crtr skill template playbook\`.
+- Topic is a *procedure*? → \`crtr skill template runbook\`.
+- Source updates faster than you'll update the skill? → don't capture; link.
+`;
+}
+function runbookTemplatePrompt(topic) {
+    return `# Runbook — procedure skill
+
+**Audience: future LLM agent sessions.** Captures a *procedure* the agent
+executes: numbered steps, decision points, verification, rollback. Examples:
+deploy, incident response, review workflow, release cut.
+
+${topicLine(topic)}
+
+## Litmus test
+
+> After loading this, does the agent *do steps in order*?
+
+If yes → runbook. If the agent makes a decision and stops → \`playbook\`. If
+the agent looks up a value → \`reference\`. If neither fits → \`freeform\`.
+
+**Runbook markers:** numbered steps · ordering matters · has rollback or
+verification · maps an outcome to a known sequence.
+
+## 1. Capture the procedure
+
+Use \`AskUserQuestion\` (≤4, multi-choice, best-guess first):
+
+- The trigger (when does the agent run this?)
+- Steps in order — explicit, atomic. *"Update X"* is not atomic; *"run
+  \\\`pnpm db:migrate\\\` and confirm exit 0"* is.
+- Decision points within the sequence (when does the agent branch?)
+- Rollback / verification (how to confirm success; how to undo on failure)
+
+Push back on vagueness. *"Deploy to prod"* is a label; *"run \\\`pnpm build\\\`,
+push to \\\`main\\\`, wait for green CI, click promote"* is a runbook step.
+
+## 2. Scope + name
+
+- **Scope**: \`project\` for repo-specific procedures. \`user\` for cross-project.
+- **Name**: verb-phrase. \`deploy-to-prod\` not \`production-deployment-guide\`.
+- Check \`crtr skill where <name>\`.
+
+## 3. Scaffold
+
+\`\`\`
+crtr skill new <name> --type runbook --scope <user|project> --description "<when to run + outcome, ≤250 chars, front-loaded trigger>"
+\`\`\`
+
+## 4. Density rules
+
+- Steps are commands, not advice. Each step is something the agent can verify.
+- Decision points get explicit branches, not "use judgment."
+- Verification belongs in-line, after the step that produces the change.
+- Rollback is mandatory if the procedure changes prod state.
+
+## 5. Body skeleton
+
+\`\`\`markdown
+# <procedure>
+
+## When to run
+- <trigger>
+
+## Pre-flight
+- [ ] <thing that must be true before starting>
+
+## Steps
+
+1. **<atomic action>** — \\\`<command>\\\`
+   Verify: <observation that confirms success>
+   If <error condition>: <what to do>
+
+2. **<atomic action>** — …
+
+## Decision points
+
+- After step N, if X then go to step M; else continue.
+
+## Verification (post-flight)
+- [ ] <how to confirm the procedure succeeded end-to-end>
+
+## Rollback
+1. <reverse-order undo steps with their own verification>
+\`\`\`
+
+**No \`## Related\` for within-plugin siblings** — auto-appended by the CLI.
+
+## 6. Verify
+
+\`\`\`
+crtr skill where <name>
+crtr skill show <name>
+crtr skill search <keyword>
+\`\`\`
+
+Walk through the runbook mentally. Each step verifiable? Each decision
+explicit? Rollback covers the state changes? If any answer is no, fix
+before shipping.
+
+## Constraints
+
+- Steps without verification are wishes. Add the verify line or cut the step.
+- "Use your judgment at step 4" → either turn step 4 into a playbook
+  reference, or write the decision criteria explicitly.
+- A procedure that's actually one command isn't a runbook — make it a
+  CLAUDE.md note.
+`;
+}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type Scope = 'user' | 'project';
+export type Scope = 'user' | 'project' | 'builtin';
 export declare const ExitCode: {
     readonly SUCCESS: 0;
     readonly GENERAL: 1;
@@ -71,10 +71,14 @@ export interface ScopeState {
     last_self_check?: string;
     bootstrap_done?: boolean;
 }
+export declare const SKILL_TYPES: readonly ["playbook", "primer", "reference", "runbook", "freeform"];
+export type SkillType = (typeof SKILL_TYPES)[number];
+export declare function isSkillType(v: unknown): v is SkillType;
 export interface SkillFrontmatter {
     name: string;
     description?: string;
     keywords?: string[];
+    type?: SkillType;
 }
 export interface Skill {
     name: string;
@@ -92,6 +96,7 @@ export interface InstalledPlugin {
     root: string;
     manifest: PluginManifest;
     enabled: boolean;
+    builtin?: boolean;
     sourceMarketplace?: string;
     version?: string;
 }

package/dist/types.js

@@ -7,6 +7,10 @@ export const ExitCode = {
     NETWORK: 5,
 };
 export const SCHEMA_VERSION = 1;
+export const SKILL_TYPES = ['playbook', 'primer', 'reference', 'runbook', 'freeform'];
+export function isSkillType(v) {
+    return typeof v === 'string' && SKILL_TYPES.includes(v);
+}
 export const PLUGIN_MANIFEST_DIR = '.crouter-plugin';
 export const PLUGIN_MANIFEST_FILE = 'plugin.json';
 export const MARKETPLACE_MANIFEST_DIR = '.crouter-marketplace';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.1.9",
+  "version": "0.2.3",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "bin"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && rm -rf dist/builtin-skills && cp -R src/builtin-skills dist/builtin-skills",
     "dev": "tsx src/cli.ts",
     "link": "npm link",
     "prepublishOnly": "npm run build"