@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/commands/skill.js

@@ -1,690 +1,21 @@
 // `crtr skill` subtree handlers — P3 implementation.
 // Sub-branches: find {list, search, grep}, author {guide, scaffold}, state {enable, disable}.
 // Leaf children of skill: read.
-import { join } from 'node:path';
-import { writeFileSync } from 'node:fs';
-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 { 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 { 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}`;
-}
-function formatNeighborKeywords(s) {
-    const kw = s.frontmatter.keywords;
-    if (!kw || kw.length === 0)
-        return '';
-    return ` — [${kw.join(', ')}]`;
-}
-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. Run `crtr skill read <name>` for full description + body.*',
-        '',
-    ];
-    if (siblings.length > 0) {
-        lines.push('**Siblings:**');
-        for (const s of siblings) {
-            lines.push(`- \`${formatNeighborQualifier(s)}\`${formatNeighborKeywords(s)}`);
-        }
-        if (children.length > 0)
-            lines.push('');
-    }
-    if (children.length > 0) {
-        lines.push('**Nested:**');
-        for (const s of children) {
-            lines.push(`- \`${formatNeighborQualifier(s)}\`${formatNeighborKeywords(s)}`);
-        }
-    }
-    return lines.join('\n');
-}
-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`;
-}
-// ---------------------------------------------------------------------------
-// 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');
-        }
-        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 <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) });
-        }
-        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 <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 {
-            regex = new RegExp(pattern);
-        }
-        catch {
-            throw usage(`invalid regex pattern: ${pattern}`);
-        }
-        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);
-            }
-            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 });
-                    }
-                });
-            }
-        }
-        // 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 leaf
-// ---------------------------------------------------------------------------
-const readLeaf = defineLeaf({
-    name: 'read',
-    help: {
-        name: 'skill read',
-        summary: 'load SKILL.md body and resolution metadata 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 content.' },
-            { kind: 'flag', name: 'no-body', type: 'bool', required: false, constraint: 'When present, omits the body — returns resolution metadata only. Use to confirm a skill exists or locate it without loading SKILL.md.' },
-        ],
-        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: false, constraint: 'SKILL.md body (with or without frontmatter per --frontmatter). Omitted when --no-body is set.' },
-            { name: 'follow_up', type: 'string', required: false, constraint: 'Hints at variant flags. Present on default reads; omitted when --no-body is set.' },
-        ],
-        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 noBody = input['noBody'];
-        const resolveOpts = {};
-        if (scopeStr !== undefined) {
-            const resolved = resolveScopeArg(scopeStr);
-            if (resolved !== 'all')
-                resolveOpts.scope = resolved;
-        }
-        if (pluginFilter !== undefined)
-            resolveOpts.pluginFilter = pluginFilter;
-        const skillObj = resolveSkill(nameRaw, resolveOpts);
-        const out = {
-            name: skillObj.name,
-            plugin: skillObj.plugin,
-            scope: skillObj.scope,
-            path: skillObj.path,
-        };
-        if (noBody)
-            return out;
-        const rawContent = readText(skillObj.path);
-        const rawBody = includeFrontmatter ? rawContent : parseFrontmatter(rawContent).body;
-        out['content'] = appendNeighbors(skillObj, rawBody);
-        out['follow_up'] = 'Add --no-body to skip the body and return path/scope/plugin only. Add --frontmatter to include YAML frontmatter in content.';
-        return out;
-    },
-});
-// ---------------------------------------------------------------------------
-// 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 };
-        }
-        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 parsed = parseSkillQualifier(qualifier);
-        if (parsed.segments.length === 0) {
-            throw usage('skill name required in qualifier');
-        }
-        // For scaffold, the qualifier is always <plugin>/<skill>. If it's a single segment,
-        // treat it as a scope-direct skill name. Otherwise first segment is the plugin.
-        const pluginName = parsed.segments.length > 1 ? parsed.segments[0] : undefined;
-        const skillName = parsed.segments.length > 1
-            ? parsed.segments.slice(1).join('/')
-            : parsed.segments[0];
-        if (typeStr !== undefined && !isSkillType(typeStr)) {
-            throw usage(`unknown skill type: ${typeStr} / valid: ${SKILL_TYPES.join(' | ')}`);
-        }
-        const skillType = typeStr !== undefined && isSkillType(typeStr) ? typeStr : undefined;
-        let skillFile;
-        // Scope-direct: no plugin qualifier, or explicit `_/` sentinel (internal only)
-        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}`);
-            }
-            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('/'));
-            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');
-        }
-        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 };
-    });
-    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.' },
-            { 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.' },
-            { 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],
-});
-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}\t${s.plugin}`;
-        const arr = bySource.get(key);
-        if (arr)
-            arr.push(s);
-        else
-            bySource.set(key, [s]);
-    }
-    const projectSources = [];
-    const userSources = [];
-    for (const [key, group] of bySource) {
-        const [scope, plugin] = key.split('\t');
-        const names = group.map((g) => g.name);
-        const roots = names
-            .filter((n) => !names.some((m) => m !== n && n.startsWith(m + '/')))
-            .sort();
-        if (roots.length === 0)
-            continue;
-        (scope === 'project' ? projectSources : userSources).push({ plugin, roots });
-    }
-    const lines = [`Loaded skills (${skills.length})`];
-    renderCatalogSection('Project', projectSources, lines);
-    renderCatalogSection('User', userSources, lines);
-    return lines.join('\n');
-}
-function renderCatalogSection(label, sources, out) {
-    if (sources.length === 0)
-        return;
-    const count = sources.reduce((n, s) => n + s.roots.length, 0);
-    out.push('');
-    out.push(`${label} (${count})`);
-    const sentinel = sources.filter((s) => s.plugin === SCOPE_SKILL_PLUGIN);
-    const named = sources
-        .filter((s) => s.plugin !== SCOPE_SKILL_PLUGIN)
-        .sort((a, b) => a.plugin.localeCompare(b.plugin));
-    for (const s of sentinel) {
-        for (const n of s.roots)
-            out.push(`  ${n}`);
-    }
-    if (named.length === 0)
-        return;
-    const classified = named.map((s) => {
-        const subcats = new Map();
-        const bare = [];
-        for (const n of s.roots) {
-            const slash = n.indexOf('/');
-            if (slash === -1) {
-                bare.push(n);
-            }
-            else {
-                const sub = n.slice(0, slash);
-                const rest = n.slice(slash + 1);
-                const arr = subcats.get(sub);
-                if (arr)
-                    arr.push(rest);
-                else
-                    subcats.set(sub, [rest]);
-            }
-        }
-        return { plugin: s.plugin, roots: s.roots, subcats, bare };
-    });
-    // Smart-nest: a plugin nests iff it has 2+ distinct subcategories.
-    const nests = (p) => p.subcats.size >= 2;
-    const inlineLabels = classified.filter((p) => !nests(p)).map((p) => `${p.plugin}/`);
-    const inlineW = inlineLabels.reduce((m, p) => (p.length > m ? p.length : m), 0);
-    for (const p of classified) {
-        if (nests(p)) {
-            out.push(`  ${p.plugin}/`);
-            if (p.bare.length > 0) {
-                out.push(`    ${[...p.bare].sort().join(', ')}`);
-            }
-            const subKeys = [...p.subcats.keys()].sort();
-            const subLabels = subKeys.map((k) => `${k}/`);
-            const subW = subLabels.reduce((m, k) => (k.length > m ? k.length : m), 0);
-            for (let i = 0; i < subKeys.length; i++) {
-                const children = p.subcats.get(subKeys[i]).sort();
-                out.push(`    ${subLabels[i].padEnd(subW)}  ${children.join(', ')}`);
-            }
-        }
-        else {
-            const pluginLabel = `${p.plugin}/`;
-            out.push(`  ${pluginLabel.padEnd(inlineW)}  ${[...p.roots].sort().join(', ')}`);
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// Root export
-// ---------------------------------------------------------------------------
+import { defineBranch } from '../core/command.js';
+import { buildSkillCatalog } from './skill/shared.js';
+import { findBranch } from './skill/find.js';
+import { readLeaf } from './skill/read.js';
+import { authorBranch } from './skill/author.js';
+import { stateBranch } from './skill/state.js';
 export function registerSkill() {
     return defineBranch({
         name: 'skill',
+        rootEntry: {
+            concept: 'a SKILL.md you read to adopt its workflow',
+            desc: 'find, read, author, and manage skills',
+            useWhen: 'a task matches a loaded skill — read it before improvising. `crtr skill read <name>` loads one by name from the catalog below; `crtr skill find` only when the name is not already listed. Names are crtr identifiers, not file paths — never cat or find SKILL.md off disk.',
+            dynamicState: buildSkillCatalog,
+        },
         help: {
             name: 'skill',
             summary: 'discover, read, author, and manage skill state',