@crouton-kit/crouter 0.2.6 → 0.3.2

package/dist/commands/skill.js

@@ -1,37 +1,24 @@
+// `crtr skill` subtree handlers — P3 implementation.
+// Sub-branches: find {list, search, grep}, read {show, where}, author {guide, scaffold}, state {enable, disable}.
 import { join } from 'node:path';
 import { writeFileSync } from 'node:fs';
-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 { defineBranch, defineLeaf } from '../core/command.js';
+import { usage, general, notFound } from '../core/errors.js';
+import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, SKILL_TYPES, isSkillType, skillConfigKey, } from '../types.js';
 import { resolveSkill, listAllSkills, listInstalledPlugins, findPluginByName, parseSkillQualifier, listSkillSiblings, listSkillChildren, } from '../core/resolver.js';
-import { updateConfig, ensureScopeInitialized } from '../core/config.js';
+import { listScopes, resolveScopeArg, requireScopeRoot, scopeSkillsDir, projectScopeRoot, } from '../core/scope.js';
 import { parseFrontmatter, serializeFrontmatter } from '../core/frontmatter.js';
+import { updateConfig, ensureScopeInitialized } from '../core/config.js';
+import { paginate } from '../core/pagination.js';
 import { ensureDir, pathExists, readText, walkFiles } from '../core/fs-utils.js';
-import { skillPrompt, skillCreatePrompt, skillTemplatePrompt } from '../prompts/skill.js';
-const KNOWN_VERBS = new Set([
-    'list',
-    'show',
-    'path',
-    'grep',
-    'new',
-    'create',
-    'template',
-    'where',
-    'enable',
-    'disable',
-    'search',
-]);
-function buildShowFooter(skillPath) {
-    return (`crtr: edit this skill directly at ${skillPath} — ` +
-        `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>`;
-}
+import { skillCreatePrompt, skillTemplatePrompt } from '../prompts/skill.js';
+// ---------------------------------------------------------------------------
+// Neighbors section (ported from old impl)
+// ---------------------------------------------------------------------------
 function formatNeighborQualifier(s) {
-    return s.plugin === SCOPE_SKILL_PLUGIN ? `${s.scope}:${s.name}` : `${s.plugin}/${s.name}`;
+    return s.plugin === SCOPE_SKILL_PLUGIN
+        ? `${s.scope}:${s.name}`
+        : `${s.plugin}/${s.name}`;
 }
 function formatNeighborKeywords(s) {
     const kw = s.frontmatter.keywords;
@@ -46,8 +33,7 @@ function buildNeighborsSection(skill) {
         return null;
     const lines = [
         '## Neighbors',
-        '*Auto-discovered from filesystem. Use `--no-neighbors` to suppress. ' +
-            'Run `crtr skill show <name>` for full description + body.*',
+        '*Auto-discovered from filesystem. Run `crtr skill read show <name>` for full description + body.*',
         '',
     ];
     if (siblings.length > 0) {
@@ -66,473 +52,644 @@ function buildNeighborsSection(skill) {
     }
     return lines.join('\n');
 }
-function appendNeighbors(skill, body, suppress) {
-    if (suppress)
-        return body;
+function appendNeighbors(skill, 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' +
-    '  <scope>:<name>               scope-root skill in a specific scope (user|project)\n' +
-    '  <scope>:<plugin>/<name>      fully qualified — matches `skill list` / `skill search` output\n' +
-    '  <plugin>/<name>              shorthand for <plugin>:<name> when unambiguous';
-export function registerSkillCommands(program) {
-    const skill = program
-        .command('skill [nameOrVerb] [rest...]')
-        .description('manage and inspect skills')
-        .option('--frontmatter', 'include YAML frontmatter in the printed body')
-        .addHelpText('before', '\n' + skillPrompt() + '\n')
-        .addHelpText('after', '\n' + SKILL_IDENTIFIER_HELP)
-        .action(async (nameOrVerb, _rest, opts) => {
-        if (nameOrVerb === undefined) {
-            skill.help();
-            return;
+// ---------------------------------------------------------------------------
+// Resolve scope for enable/disable/scaffold
+// ---------------------------------------------------------------------------
+function resolveWriteScope(scopeStr) {
+    if (scopeStr !== undefined) {
+        const resolved = resolveScopeArg(scopeStr);
+        if (resolved === 'all') {
+            throw usage('scope must be user or project, not all');
         }
-        if (!KNOWN_VERBS.has(nameOrVerb)) {
-            try {
-                const skillObj = resolveSkill(nameOrVerb);
-                const content = readText(skillObj.path);
-                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));
-            }
-            catch (e) {
-                handleError(e);
+        return resolved;
+    }
+    return projectScopeRoot() !== null ? 'project' : 'user';
+}
+// ---------------------------------------------------------------------------
+// find sub-branch
+// ---------------------------------------------------------------------------
+const findList = defineLeaf({
+    name: 'list',
+    help: {
+        name: 'skill find list',
+        summary: 'paginated list of installed skills',
+        params: [
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Default: all.' },
+            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Filter to a single plugin name.' },
+            { kind: 'flag', name: 'include-disabled', type: 'bool', required: false, constraint: 'When present, includes disabled skills.' },
+            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 50, constraint: 'Max 200.' },
+            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
+            { kind: 'flag', name: 'full', type: 'bool', required: false, constraint: 'When present, includes each skill\'s description in items. Off by default to keep enumerations cheap; pair with --plugin or --limit to bound cost.' },
+        ],
+        output: [
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {name, plugin, scope, enabled, disabled_in?}. With --full, each item also includes description. Sorted by scope then plugin then name ascending.' },
+            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'null means no more items.' },
+            { name: 'total', type: 'integer | null', required: true, constraint: 'Exact when cheap; null otherwise.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands for drilling into an item or refining the list.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const scopeStr = input['scope'];
+        const pluginFilter = input['plugin'];
+        const includeDisabled = input['includeDisabled'];
+        const limitRaw = input['limit'];
+        const limit = Math.min(Math.max(1, limitRaw), 200);
+        const cursor = input['cursor'];
+        const full = input['full'];
+        const scopes = listScopes(scopeStr);
+        const skills = scopes
+            .flatMap((s) => listAllSkills(s))
+            .filter((sk) => {
+            if (pluginFilter !== undefined && sk.plugin !== pluginFilter)
+                return false;
+            if (!includeDisabled && !sk.enabled)
+                return false;
+            return true;
+        });
+        // Sort by scope then plugin then name ascending
+        const scopeOrder = { project: 0, user: 1, builtin: 2 };
+        skills.sort((a, b) => {
+            const so = (scopeOrder[a.scope] !== undefined ? scopeOrder[a.scope] : 3) -
+                (scopeOrder[b.scope] !== undefined ? scopeOrder[b.scope] : 3);
+            if (so !== 0)
+                return so;
+            const po = a.plugin.localeCompare(b.plugin);
+            if (po !== 0)
+                return po;
+            return a.name.localeCompare(b.name);
+        });
+        const keyOf = (sk) => `${sk.scope}:${sk.plugin}/${sk.name}`;
+        const params = {};
+        if (limit !== undefined)
+            params.limit = limit;
+        if (cursor !== undefined)
+            params.cursor = cursor;
+        const result = paginate(skills, params, {
+            defaultLimit: 50,
+            maxLimit: 200,
+            keyOf,
+            total: 'count',
+        });
+        return {
+            items: result.items.map((sk) => {
+                const base = {
+                    name: sk.name,
+                    plugin: sk.plugin,
+                    scope: sk.scope,
+                    enabled: sk.enabled,
+                    disabled_in: sk.disabledIn !== undefined ? sk.disabledIn : null,
+                };
+                if (full) {
+                    base['description'] = sk.frontmatter.description !== undefined ? sk.frontmatter.description : null;
+                }
+                return base;
+            }),
+            next_cursor: result.next_cursor,
+            total: result.total,
+            follow_up: 'Use `crtr skill read show <name>` for the full SKILL.md body. Run `crtr skill find list -h` for filters and verbosity.',
+        };
+    },
+});
+const findSearch = defineLeaf({
+    name: 'search',
+    help: {
+        name: 'skill find search',
+        summary: 'search skills by name, description, and keywords',
+        params: [
+            { kind: 'positional', name: 'query', required: true, constraint: 'Whitespace-separated terms matched case-insensitively against name, description, and keywords; skills matching more terms rank higher.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Default: all.' },
+            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Filter to a single plugin name.' },
+            { kind: 'flag', name: 'include-disabled', type: 'bool', required: false, constraint: 'When present, includes disabled skills.' },
+            { kind: 'flag', name: 'search-body', type: 'bool', required: false, constraint: 'When present, also searches inside SKILL.md body text.' },
+        ],
+        output: [
+            { name: 'query', type: 'string', required: true, constraint: 'Echo of the input query.' },
+            { name: 'hits', type: 'object[]', required: true, constraint: 'Each: {name, plugin, scope, score, description}. Sorted by score descending. description is the frontmatter line — the discriminator for picking which hit to read in full.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands for drilling into a hit or refining the search.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const query = input['query'];
+        const scopeStr = input['scope'];
+        const pluginFilter = input['plugin'];
+        const includeDisabled = input['includeDisabled'];
+        const searchBody = input['searchBody'];
+        const terms = query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((t) => t.length > 0);
+        if (terms.length === 0)
+            throw usage('query must contain at least one non-whitespace term');
+        const scopes = listScopes(scopeStr);
+        const candidates = scopes
+            .flatMap((s) => listAllSkills(s))
+            .filter((sk) => {
+            if (pluginFilter !== undefined && sk.plugin !== pluginFilter)
+                return false;
+            if (!includeDisabled && !sk.enabled)
+                return false;
+            return true;
+        });
+        const hits = [];
+        for (const sk of candidates) {
+            const matchedSet = new Set();
+            let score = 0;
+            const nameLc = sk.name.toLowerCase();
+            const descLc = sk.frontmatter.description !== undefined ? sk.frontmatter.description.toLowerCase() : null;
+            const kwsLc = sk.frontmatter.keywords !== undefined ? sk.frontmatter.keywords.map((k) => k.toLowerCase()) : null;
+            const bodyLc = searchBody ? readText(sk.path).toLowerCase() : null;
+            for (const term of terms) {
+                if (nameLc.includes(term)) {
+                    score += 10;
+                    matchedSet.add('name');
+                }
+                if (descLc !== null && descLc.includes(term)) {
+                    score += 4;
+                    matchedSet.add('description');
+                }
+                if (kwsLc !== null && kwsLc.some((k) => k.includes(term))) {
+                    score += 6;
+                    matchedSet.add('keywords');
+                }
+                if (bodyLc !== null && bodyLc.includes(term)) {
+                    score += 1;
+                    matchedSet.add('body');
+                }
             }
+            if (score > 0)
+                hits.push({ skill: sk, score, matched: Array.from(matchedSet) });
         }
-    });
-    // list
-    skill
-        .command('list')
-        .description('list installed skills (disabled hidden unless -a)')
-        .option('--scope <scope>', 'user|project|all (default: all)')
-        .option('--plugin <name>', 'filter by plugin name')
-        .option('-a, --all', 'include disabled skills')
-        .option('--json', 'emit JSON')
-        .addHelpText('after', '\nOutput format: <scope>:<plugin>/<name> — paste this identifier into ' +
-        '`crtr skill show` to read the skill.')
-        .action(async (opts) => {
+        hits.sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
+        return {
+            query,
+            hits: hits.map((h) => ({
+                name: h.skill.name,
+                plugin: h.skill.plugin,
+                scope: h.skill.scope,
+                score: h.score,
+                description: h.skill.frontmatter.description !== undefined ? h.skill.frontmatter.description : null,
+            })),
+            follow_up: 'Use `crtr skill read show <name>` for the full SKILL.md body. Run `crtr skill find search -h` for filters.',
+        };
+    },
+});
+const findGrep = defineLeaf({
+    name: 'grep',
+    help: {
+        name: 'skill find grep',
+        summary: 'search skill file contents for a regex pattern',
+        params: [
+            { kind: 'positional', name: 'pattern', required: true, constraint: 'ECMAScript regex. Applied to each line of every SKILL.md file.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project', 'all'], required: false, constraint: 'Default: all.' },
+            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Filter to a single plugin name.' },
+        ],
+        output: [
+            { name: 'matches', type: 'object[]', required: true, constraint: 'Each: {path, line, text}. path is absolute. Sorted by path then line ascending.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const pattern = input['pattern'];
+        const scopeStr = input['scope'];
+        const pluginFilter = input['plugin'];
+        let regex;
         try {
-            const scopes = listScopes(opts.scope);
-            const skills = scopes
-                .flatMap((s) => listAllSkills(s))
-                .filter((sk) => {
-                if (opts.plugin !== undefined && sk.plugin !== opts.plugin)
-                    return false;
-                if (!opts.all && !sk.enabled)
-                    return false;
-                return true;
-            });
-            if (opts.json) {
-                jsonOut({
-                    skills: skills.map((sk) => ({
-                        name: sk.name,
-                        plugin: sk.plugin,
-                        scope: sk.scope,
-                        path: sk.path,
-                        description: sk.frontmatter.description,
-                        enabled: sk.enabled,
-                        disabled_in: sk.disabledIn,
-                    })),
-                });
-                return;
-            }
-            for (const sk of skills) {
-                const desc = sk.frontmatter.description !== undefined ? sk.frontmatter.description : '';
-                const marker = sk.enabled ? '' : ` [disabled${sk.disabledIn ? `@${sk.disabledIn}` : ''}]`;
-                const qualified = sk.plugin === SCOPE_SKILL_PLUGIN
-                    ? `${sk.scope}:${sk.name}`
-                    : `${sk.scope}:${sk.plugin}/${sk.name}`;
-                out(`${qualified}${marker}${desc ? `  — ${desc}` : ''}`);
-            }
+            regex = new RegExp(pattern);
         }
-        catch (e) {
-            handleError(e, { json: opts.json });
+        catch {
+            throw usage(`invalid regex pattern: ${pattern}`);
         }
-    });
-    // show
-    skill
-        .command('show <name>')
-        .description('print SKILL.md body to stdout (default verb)')
-        .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' +
-        '  crtr skill show claude-authoring:rules             # plugin:name (canonical)\n' +
-        '  crtr skill show user:claude-authoring/rules        # scope:plugin/name (matches search/list output)\n' +
-        '  crtr skill show claude-authoring/rules             # plugin/name shorthand\n\n' +
-        SKILL_IDENTIFIER_HELP)
-        .action(async (name, opts) => {
-        try {
-            const scopeArg = resolveScopeArg(opts.scope);
-            const resolveOpts = scopeArg !== 'all' ? { scope: scopeArg } : {};
-            if (opts.plugin !== undefined) {
-                Object.assign(resolveOpts, { pluginFilter: opts.plugin });
+        const scopes = listScopes(scopeStr);
+        const skillsDirs = [];
+        for (const s of scopes) {
+            if (pluginFilter === undefined || pluginFilter === SCOPE_SKILL_PLUGIN) {
+                const root = scopeSkillsDir(s);
+                if (root)
+                    skillsDirs.push(root);
             }
-            const skillObj = resolveSkill(name, resolveOpts);
-            const content = readText(skillObj.path);
-            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,
-                    plugin: skillObj.plugin,
-                    scope: skillObj.scope,
-                    path: skillObj.path,
-                    content,
-                    authoring_guide_command: `crtr skill`,
+            for (const plugin of listInstalledPlugins(s)) {
+                if (!plugin.enabled)
+                    continue;
+                if (pluginFilter !== undefined && plugin.name !== pluginFilter)
+                    continue;
+                skillsDirs.push(join(plugin.root, SKILLS_DIR));
+            }
+        }
+        const matchLines = [];
+        for (const skillsDir of skillsDirs) {
+            const files = walkFiles(skillsDir);
+            for (const file of files) {
+                const content = readText(file);
+                const lines = content.split('\n');
+                lines.forEach((lineText, idx) => {
+                    if (regex.test(lineText)) {
+                        matchLines.push({ path: file, line: idx + 1, text: lineText });
+                    }
                 });
-                return;
             }
-            out(wrapSkill(skillObj.name, skillObj.path, body));
-            hint(buildShowFooter(skillObj.path));
         }
-        catch (e) {
-            handleError(e, { json: opts.json });
+        // Sort by path then line ascending
+        matchLines.sort((a, b) => {
+            const pc = a.path.localeCompare(b.path);
+            return pc !== 0 ? pc : a.line - b.line;
+        });
+        return { matches: matchLines };
+    },
+});
+const findBranch = defineBranch({
+    name: 'find',
+    help: {
+        name: 'skill find',
+        summary: 'discover skills by listing, keyword search, or body grep',
+        children: [
+            { name: 'list', desc: 'paginated list of installed skills', useWhen: 'enumerating all available skills' },
+            { name: 'search', desc: 'keyword search across name/description/keywords', useWhen: 'looking for skills matching a topic' },
+            { name: 'grep', desc: 'regex search across SKILL.md bodies', useWhen: 'finding skills containing specific text or patterns' },
+        ],
+    },
+    children: [findList, findSearch, findGrep],
+});
+// ---------------------------------------------------------------------------
+// read sub-branch
+// ---------------------------------------------------------------------------
+const readShow = defineLeaf({
+    name: 'show',
+    help: {
+        name: 'skill read show',
+        summary: 'print SKILL.md body for a named skill',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Forms: <name>, <plugin>:<name>, <scope>:<name>, <scope>:<plugin>/<name>.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution when name is ambiguous.' },
+            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Narrows resolution to a specific plugin.' },
+            { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes YAML frontmatter in the output.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
+            { name: 'plugin', type: 'string', required: true, constraint: 'Plugin the skill belongs to.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the skill was resolved from.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to SKILL.md.' },
+            { name: 'content', type: 'string', required: true, constraint: 'SKILL.md body (with or without frontmatter per the --frontmatter flag).' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        const scopeStr = input['scope'];
+        const pluginFilter = input['plugin'];
+        const includeFrontmatter = input['frontmatter'];
+        const resolveOpts = {};
+        if (scopeStr !== undefined) {
+            const resolved = resolveScopeArg(scopeStr);
+            if (resolved !== 'all')
+                resolveOpts.scope = resolved;
         }
-    });
-    // path
-    skill
-        .command('path <name>')
-        .description('print absolute path to SKILL.md')
-        .option('--scope <scope>', 'user|project')
-        .option('--plugin <name>', 'filter by plugin name')
-        .action(async (name, opts) => {
-        try {
-            const scopeArg = resolveScopeArg(opts.scope);
-            const resolveOpts = scopeArg !== 'all' ? { scope: scopeArg } : {};
-            if (opts.plugin !== undefined) {
-                Object.assign(resolveOpts, { pluginFilter: opts.plugin });
-            }
-            const skillObj = resolveSkill(name, resolveOpts);
-            out(skillObj.path);
+        if (pluginFilter !== undefined)
+            resolveOpts.pluginFilter = pluginFilter;
+        const skillObj = resolveSkill(nameRaw, resolveOpts);
+        const rawContent = readText(skillObj.path);
+        const rawBody = includeFrontmatter ? rawContent : parseFrontmatter(rawContent).body;
+        const content = appendNeighbors(skillObj, rawBody);
+        return {
+            name: skillObj.name,
+            plugin: skillObj.plugin,
+            scope: skillObj.scope,
+            path: skillObj.path,
+            content,
+        };
+    },
+});
+const readWhere = defineLeaf({
+    name: 'where',
+    help: {
+        name: 'skill read where',
+        summary: 'show resolution metadata for a named skill without reading its body',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read show.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
+            { kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: 'Narrows resolution to a specific plugin.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
+            { name: 'plugin', type: 'string', required: true, constraint: 'Plugin the skill belongs to.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the skill was resolved from.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to SKILL.md.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const nameRaw = input['name'];
+        const scopeStr = input['scope'];
+        const pluginFilter = input['plugin'];
+        const resolveOpts = {};
+        if (scopeStr !== undefined) {
+            const resolved = resolveScopeArg(scopeStr);
+            if (resolved !== 'all')
+                resolveOpts.scope = resolved;
         }
-        catch (e) {
-            handleError(e);
+        if (pluginFilter !== undefined)
+            resolveOpts.pluginFilter = pluginFilter;
+        const skillObj = resolveSkill(nameRaw, resolveOpts);
+        return {
+            name: skillObj.name,
+            plugin: skillObj.plugin,
+            scope: skillObj.scope,
+            path: skillObj.path,
+        };
+    },
+});
+const readBranch = defineBranch({
+    name: 'read',
+    help: {
+        name: 'skill read',
+        summary: 'read skill content or resolve its location',
+        children: [
+            { name: 'show', desc: 'print SKILL.md body', useWhen: 'loading skill content to act on it' },
+            { name: 'where', desc: 'show resolution metadata only', useWhen: 'verifying which skill resolves and from where, without loading its body' },
+        ],
+    },
+    children: [readShow, readWhere],
+});
+// ---------------------------------------------------------------------------
+// author sub-branch
+// ---------------------------------------------------------------------------
+const VALID_TYPES = ['playbook', 'primer', 'reference', 'runbook', 'freeform'];
+const authorGuide = defineLeaf({
+    name: 'guide',
+    help: {
+        name: 'skill author guide',
+        summary: 'load the skill authoring workflow — two stages: omit type to pick one, pass type for its full skeleton',
+        params: [
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...VALID_TYPES], required: false, constraint: 'OMIT to receive the template-picker guide first; pass on the second call for that type\'s full workflow + skeleton.' },
+            { kind: 'flag', name: 'topic', type: 'string', required: false, constraint: 'Optional topic context injected into the guide.' },
+        ],
+        output: [
+            { name: 'guide', type: 'string', required: true, constraint: 'Stage 1 (no type): the template-picker workflow. Stage 2 (type given): that type\'s authoring workflow + skeleton.' },
+            { name: 'type', type: 'string | null', required: true, constraint: 'Echo of the requested type, or null on the picker stage.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const type = input['type'];
+        const topic = input['topic'];
+        const topicArg = topic !== undefined ? topic : '';
+        // Progressive disclosure: no type → template picker (stage 1);
+        // type given → that type's full workflow + skeleton (stage 2).
+        if (type === undefined) {
+            return { guide: skillCreatePrompt(topicArg), type: null };
         }
-    });
-    // grep
-    skill
-        .command('grep <pattern>')
-        .description('search skill file contents for a regex pattern')
-        .option('--scope <scope>', 'user|project|all')
-        .option('--plugin <name>', 'filter by plugin name')
-        .option('--json', 'emit JSON')
-        .action(async (pattern, opts) => {
-        try {
-            let regex;
-            try {
-                regex = new RegExp(pattern);
-            }
-            catch {
-                throw usage(`invalid regex pattern: ${pattern}`);
-            }
-            const scopes = listScopes(opts.scope);
-            const skillsDirs = [];
-            for (const s of scopes) {
-                if (opts.plugin === undefined || opts.plugin === SCOPE_SKILL_PLUGIN) {
-                    const root = scopeSkillsDir(s);
-                    if (root)
-                        skillsDirs.push(root);
-                }
-                for (const plugin of listInstalledPlugins(s)) {
-                    if (!plugin.enabled)
-                        continue;
-                    if (opts.plugin !== undefined && plugin.name !== opts.plugin)
-                        continue;
-                    skillsDirs.push(join(plugin.root, SKILLS_DIR));
-                }
-            }
-            const matchLines = [];
-            for (const skillsDir of skillsDirs) {
-                const files = walkFiles(skillsDir);
-                for (const file of files) {
-                    const content = readText(file);
-                    const lines = content.split('\n');
-                    lines.forEach((lineText, idx) => {
-                        if (regex.test(lineText)) {
-                            matchLines.push({ path: file, line: idx + 1, text: lineText });
-                        }
-                    });
-                }
-            }
-            if (opts.json) {
-                jsonOut({ matches: matchLines });
-                return;
-            }
-            for (const m of matchLines) {
-                out(`${m.path}:${m.line}: ${m.text}`);
-            }
+        return { guide: skillTemplatePrompt(type, topicArg), type };
+    },
+});
+const authorScaffold = defineLeaf({
+    name: 'scaffold',
+    help: {
+        name: 'skill author scaffold',
+        summary: 'create an empty SKILL.md stub at the given qualifier',
+        params: [
+            { kind: 'positional', name: 'qualifier', required: true, constraint: 'Skill identifier in <plugin>:<skill> form.' },
+            { kind: 'flag', name: 'type', type: 'enum', choices: [...VALID_TYPES], required: false, constraint: 'One of: playbook, primer, reference, runbook, freeform.' },
+            { kind: 'flag', name: 'description', type: 'string', required: false, constraint: 'Short description written to frontmatter.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
+        ],
+        output: [
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the scaffolded SKILL.md.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Recommended next call to load the authoring guide.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Creates the skill directory and SKILL.md stub at the resolved location.',
+            'Writes frontmatter with name, description (if provided), and type (if provided).',
+        ],
+    },
+    run: async (input) => {
+        const qualifier = input['qualifier'];
+        const typeStr = input['type'];
+        const description = input['description'];
+        const scopeStr = input['scope'];
+        const { plugin: pluginName, name: skillName } = parseSkillQualifier(qualifier);
+        if (!skillName) {
+            throw usage('skill name required in qualifier');
         }
-        catch (e) {
-            handleError(e, { json: opts.json });
+        if (typeStr !== undefined && !isSkillType(typeStr)) {
+            throw usage(`unknown skill type: ${typeStr} / valid: ${SKILL_TYPES.join(' | ')}`);
         }
-    });
-    // new
-    skill
-        .command('new <qualifier>')
-        .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');
+        const skillType = typeStr !== undefined && isSkillType(typeStr) ? typeStr : undefined;
+        let skillFile;
+        // Scope-direct: no plugin qualifier, or explicit `_:` sentinel
+        if (pluginName === undefined || pluginName === SCOPE_SKILL_PLUGIN) {
+            const scope = resolveWriteScope(scopeStr);
+            const scopeRootPath = requireScopeRoot(scope);
+            ensureScopeInitialized(scope, scopeRootPath);
+            const skillsRoot = scopeSkillsDir(scope);
+            if (!skillsRoot) {
+                throw general(`no skills dir for scope ${scope}`);
             }
-            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) {
-                let scope;
-                if (scopeArg !== undefined && scopeArg !== 'all') {
-                    scope = scopeArg;
-                }
-                else {
-                    scope = projectScopeRoot() !== null ? 'project' : 'user';
-                }
-                const scopeRootPath = requireScopeRoot(scope);
-                ensureScopeInitialized(scope, scopeRootPath);
-                const skillsRoot = scopeSkillsDir(scope);
-                if (!skillsRoot) {
-                    throw general(`no skills dir for scope ${scope}`);
-                }
-                const skillDir = join(skillsRoot, ...skillName.split('/'));
-                const skillFile = join(skillDir, SKILL_ENTRY_FILE);
-                if (pathExists(skillFile)) {
-                    throw general(`skill already exists: ${skillFile}`);
-                }
-                ensureDir(skillDir);
-                const fm = serializeFrontmatter({
-                    name: skillName,
-                    description: opts.description,
-                    type: skillType,
-                });
-                writeFileSync(skillFile, fm, 'utf8');
-                out(skillFile);
-                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;
-            if (scopeArg !== undefined && scopeArg !== 'all') {
-                plugin = findPluginByName(pluginName, scopeArg);
-            }
-            else {
-                plugin = findPluginByName(pluginName);
+            const skillDir = join(skillsRoot, ...skillName.split('/'));
+            skillFile = join(skillDir, SKILL_ENTRY_FILE);
+            if (pathExists(skillFile)) {
+                throw general(`skill already exists: ${skillFile}`);
             }
+            ensureDir(skillDir);
+            const fm = serializeFrontmatter({
+                name: skillName,
+                description,
+                type: skillType,
+            });
+            writeFileSync(skillFile, fm, 'utf8');
+        }
+        else {
+            // Plugin-scoped scaffold
+            const scopeForLookup = scopeStr !== undefined
+                ? (() => {
+                    const r = resolveScopeArg(scopeStr);
+                    return r !== 'all' ? r : undefined;
+                })()
+                : undefined;
+            const plugin = scopeForLookup !== undefined
+                ? findPluginByName(pluginName, scopeForLookup)
+                : findPluginByName(pluginName);
             if (!plugin) {
                 throw notFound(`plugin not found: ${pluginName}`);
             }
             const skillDir = join(plugin.root, SKILLS_DIR, ...skillName.split('/'));
-            const skillFile = join(skillDir, SKILL_ENTRY_FILE);
+            skillFile = join(skillDir, SKILL_ENTRY_FILE);
             if (pathExists(skillFile)) {
                 throw general(`skill already exists: ${skillFile}`);
             }
             ensureDir(skillDir);
             const fm = serializeFrontmatter({
                 name: skillName,
-                description: opts.description,
+                description,
                 type: skillType,
             });
             writeFileSync(skillFile, fm, 'utf8');
-            out(skillFile);
-            const templateHint = skillType !== undefined ? skillType : '<type>';
-            hint(`crtr: scaffolded ${skillFile} — edit directly; ` +
-                `\`crtr skill template ${templateHint}\` for body skeleton`);
-        }
-        catch (e) {
-            handleError(e);
-        }
-    });
-    // create — pick a template type
-    skill
-        .command('create [topic...]')
-        .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));
-    });
-    // template — full workflow + skeleton for one template type
-    skill
-        .command('template <type> [topic...]')
-        .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));
-    });
-    // where
-    skill
-        .command('where <name>')
-        .description('show resolution info as JSON')
-        .option('--scope <scope>', 'user|project')
-        .option('--plugin <name>', 'filter by plugin name')
-        .action(async (name, opts) => {
-        try {
-            const scopeArg = resolveScopeArg(opts.scope);
-            const resolveOpts = scopeArg !== 'all' ? { scope: scopeArg } : {};
-            if (opts.plugin !== undefined) {
-                Object.assign(resolveOpts, { pluginFilter: opts.plugin });
-            }
-            const skillObj = resolveSkill(name, resolveOpts);
-            jsonOut({
-                name: skillObj.name,
-                plugin: skillObj.plugin,
-                scope: skillObj.scope,
-                path: skillObj.path,
-            });
-        }
-        catch (e) {
-            handleError(e);
-        }
-    });
-    // enable
-    skill
-        .command('enable <name>')
-        .description('enable a skill (clears any disable in the chosen scope)')
-        .option('--scope <scope>', 'user|project (default: project if available, else user)')
-        .action(async (name, opts) => {
-        try {
-            await toggleSkill(name, true, opts.scope);
-        }
-        catch (e) {
-            handleError(e);
-        }
-    });
-    // disable
-    skill
-        .command('disable <name>')
-        .description('disable a skill (hides from list and agent discovery)')
-        .option('--scope <scope>', 'user|project (default: project if available, else user)')
-        .action(async (name, opts) => {
-        try {
-            await toggleSkill(name, false, opts.scope);
-        }
-        catch (e) {
-            handleError(e);
         }
-    });
-    // search
-    skill
-        .command('search <query>')
-        .description('search skills by name, description, and keywords')
-        .option('--scope <scope>', 'user|project|all (default: all)')
-        .option('--plugin <name>', 'filter by plugin name')
-        .option('-a, --all', 'include disabled skills')
-        .option('--body', 'also search SKILL.md body')
-        .option('--json', 'emit JSON')
-        .addHelpText('after', '\nOutput columns (tab-separated): <scope>:<plugin>/<name>  <matched-fields>  <description>\n' +
-        'The identifier is pasteable into `crtr skill show`.')
-        .action(async (query, opts) => {
-        try {
-            const needle = query.toLowerCase();
-            const scopes = listScopes(opts.scope);
-            const candidates = scopes
-                .flatMap((s) => listAllSkills(s))
-                .filter((sk) => {
-                if (opts.plugin !== undefined && sk.plugin !== opts.plugin)
-                    return false;
-                if (!opts.all && !sk.enabled)
-                    return false;
-                return true;
-            });
-            const hits = [];
-            for (const sk of candidates) {
-                const matched = [];
-                let score = 0;
-                if (sk.name.toLowerCase().includes(needle)) {
-                    score += 10;
-                    matched.push('name');
-                }
-                const desc = sk.frontmatter.description;
-                if (desc !== undefined && desc.toLowerCase().includes(needle)) {
-                    score += 4;
-                    matched.push('description');
-                }
-                const kws = sk.frontmatter.keywords;
-                if (kws && kws.some((k) => k.toLowerCase().includes(needle))) {
-                    score += 6;
-                    matched.push('keywords');
-                }
-                if (opts.body) {
-                    const text = readText(sk.path).toLowerCase();
-                    if (text.includes(needle)) {
-                        score += 1;
-                        matched.push('body');
-                    }
-                }
-                if (score > 0)
-                    hits.push({ skill: sk, score, matched });
-            }
-            hits.sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
-            if (opts.json) {
-                jsonOut({
-                    query,
-                    hits: hits.map((h) => ({
-                        name: h.skill.name,
-                        plugin: h.skill.plugin,
-                        scope: h.skill.scope,
-                        path: h.skill.path,
-                        description: h.skill.frontmatter.description,
-                        keywords: h.skill.frontmatter.keywords,
-                        enabled: h.skill.enabled,
-                        score: h.score,
-                        matched: h.matched,
-                    })),
-                });
-                return;
-            }
-            for (const h of hits) {
-                const desc = h.skill.frontmatter.description !== undefined
-                    ? h.skill.frontmatter.description
-                    : '';
-                const marker = h.skill.enabled ? '' : ' [disabled]';
-                const qualified = h.skill.plugin === SCOPE_SKILL_PLUGIN
-                    ? `${h.skill.scope}:${h.skill.name}`
-                    : `${h.skill.scope}:${h.skill.plugin}/${h.skill.name}`;
-                out(`${qualified}${marker}\t${h.matched.join(',')}\t${desc}`);
-            }
-        }
-        catch (e) {
-            handleError(e, { json: opts.json });
-        }
-    });
-}
-async function toggleSkill(name, enabled, scopeArgRaw) {
-    let scope;
-    if (scopeArgRaw !== undefined) {
-        const resolved = resolveScopeArg(scopeArgRaw);
-        if (resolved === 'all')
-            throw usage('--scope must be user or project for enable/disable');
-        scope = resolved;
-    }
-    else {
-        scope = projectScopeRoot() !== null ? 'project' : 'user';
-    }
-    const skillObj = resolveSkill(name);
+        const typeHint = skillType !== undefined ? `--type ${skillType} ` : '';
+        const follow_up = `crtr skill author guide ${typeHint}--topic "${skillName}"`;
+        return { path: skillFile, follow_up };
+    },
+});
+const authorBranch = defineBranch({
+    name: 'author',
+    help: {
+        name: 'skill author',
+        summary: 'create and scaffold new skills',
+        children: [
+            { name: 'guide', desc: 'load authoring workflow + skeleton for a type', useWhen: 'writing a new skill and need the template and instructions' },
+            { name: 'scaffold', desc: 'create an empty SKILL.md stub', useWhen: 'initializing the file before writing content' },
+        ],
+    },
+    children: [authorGuide, authorScaffold],
+});
+// ---------------------------------------------------------------------------
+// state sub-branch
+// ---------------------------------------------------------------------------
+async function toggleSkill(input, enabled) {
+    const nameRaw = input['name'];
+    const scopeStr = input['scope'];
+    const scope = resolveWriteScope(scopeStr);
+    const skillObj = resolveSkill(nameRaw);
     const key = skillConfigKey(skillObj.plugin, skillObj.name);
     const scopeRootPath = requireScopeRoot(scope);
     ensureScopeInitialized(scope, scopeRootPath);
     updateConfig(scope, (cfg) => {
         cfg.skills[key] = { enabled };
     });
-    info(`${enabled ? 'enabled' : 'disabled'} ${skillObj.plugin}:${skillObj.name} in ${scope} scope`);
+    return { name: skillObj.name, scope, enabled };
+}
+const stateEnable = defineLeaf({
+    name: 'enable',
+    help: {
+        name: 'skill state enable',
+        summary: 'enable a skill in the given scope',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read show.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope where the enable was applied.' },
+            { name: 'enabled', type: 'boolean', required: true, constraint: 'Always true.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes the skill enable flag to config.json in the target scope.'],
+    },
+    run: async (input) => toggleSkill(input, true),
+});
+const stateDisable = defineLeaf({
+    name: 'disable',
+    help: {
+        name: 'skill state disable',
+        summary: 'disable a skill in the given scope, hiding it from list and agent discovery',
+        params: [
+            { kind: 'positional', name: 'name', required: true, constraint: 'Skill identifier. Same forms as skill read show.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
+        ],
+        output: [
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved skill name.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope where the disable was applied.' },
+            { name: 'enabled', type: 'boolean', required: true, constraint: 'Always false.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes the skill disable flag to config.json in the target scope.'],
+    },
+    run: async (input) => toggleSkill(input, false),
+});
+const stateBranch = defineBranch({
+    name: 'state',
+    help: {
+        name: 'skill state',
+        summary: 'enable or disable skills',
+        children: [
+            { name: 'enable', desc: 'enable a skill', useWhen: 'making a previously disabled skill available again' },
+            { name: 'disable', desc: 'disable a skill', useWhen: 'hiding a skill from list and agent discovery without removing it' },
+        ],
+    },
+    children: [stateEnable, stateDisable],
+});
+// ---------------------------------------------------------------------------
+// Loaded-skills catalog (dynamicState for `skill -h`)
+// ---------------------------------------------------------------------------
+// A skill is a forest root within its source (scope+plugin) when no other
+// skill in that same source is its ancestor (`name` prefix + '/'). Nested
+// children stay discoverable via `skill find list` and the Neighbors section.
+function buildSkillCatalog() {
+    let skills;
+    try {
+        skills = listAllSkills().filter((s) => s.enabled);
+    }
+    catch {
+        return null;
+    }
+    if (skills.length === 0)
+        return null;
+    const bySource = new Map();
+    for (const s of skills) {
+        const key = `${s.scope}${s.plugin}`;
+        const arr = bySource.get(key);
+        if (arr)
+            arr.push(s);
+        else
+            bySource.set(key, [s]);
+    }
+    const byPrefix = new Map();
+    for (const group of bySource.values()) {
+        const names = group.map((g) => g.name);
+        for (const s of group) {
+            const isChild = names.some((n) => n !== s.name && s.name.startsWith(n + '/'));
+            if (isChild)
+                continue;
+            const prefix = s.plugin === SCOPE_SKILL_PLUGIN ? `${s.scope}:` : `${s.plugin}/`;
+            let set = byPrefix.get(prefix);
+            if (!set) {
+                set = new Set();
+                byPrefix.set(prefix, set);
+            }
+            set.add(s.name);
+        }
+    }
+    const prefixes = [...byPrefix.keys()].sort();
+    const prefixW = prefixes.reduce((m, p) => (p.length > m ? p.length : m), 0);
+    const lines = [`Loaded skills (${skills.length})`];
+    for (const prefix of prefixes) {
+        const names = [...byPrefix.get(prefix)].sort();
+        lines.push(`  ${prefix.padEnd(prefixW)}  ${names.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Root export
+// ---------------------------------------------------------------------------
+export function registerSkill() {
+    return defineBranch({
+        name: 'skill',
+        help: {
+            name: 'skill',
+            summary: 'discover, read, author, and manage skill state',
+            model: '`find` when you do not yet know which skill applies — it locates candidates by topic, keyword, or body text. `read` when you have a name and need the SKILL.md content or its on-disk location. `author` when you are writing a new skill — it carries the template workflow and the scaffolder. `state` when a skill should be hidden from discovery without being removed. Append `-h` at any branch or leaf for its full schema.',
+            dynamicState: buildSkillCatalog,
+            children: [
+                { name: 'find', desc: 'list, search, or grep skills', useWhen: 'discovering what skills are available' },
+                { name: 'read', desc: 'read skill content or resolve location', useWhen: 'loading a skill to act on it' },
+                { name: 'author', desc: 'create and scaffold skills', useWhen: 'writing a new skill' },
+                { name: 'state', desc: 'enable or disable skills', useWhen: 'toggling skill visibility' },
+            ],
+        },
+        children: [findBranch, readBranch, authorBranch, stateBranch],
+    });
 }