@crouton-kit/crouter 0.1.8 → 0.2.2

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,7 +23,7 @@ const KNOWN_VERBS = new Set([
     'disable',
     'search',
 ]);
-const AUTHORING_GUIDE_SKILL = 'authoring-skills';
+const AUTHORING_GUIDE_SKILL = 'crouter-development/skills';
 function buildShowFooter(skillPath) {
     return (`crtr: edit this skill directly at ${skillPath} — ` +
         `for SKILL.md authoring guidance run \`crtr skill ${AUTHORING_GUIDE_SKILL}\``);
@@ -31,11 +31,58 @@ function buildShowFooter(skillPath) {
 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' +
+    '  <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('after', '\n' + SKILL_IDENTIFIER_HELP)
         .action(async (nameOrVerb, _rest, opts) => {
         if (nameOrVerb === undefined) {
             out(skillPrompt());
@@ -45,7 +92,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));
             }
@@ -62,6 +110,8 @@ export function registerSkillCommands(program) {
         .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) => {
         try {
             const scopes = listScopes(opts.scope);
@@ -108,7 +158,14 @@ 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' +
+        '  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);
@@ -118,7 +175,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,
@@ -220,12 +279,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) {
@@ -251,6 +318,7 @@ export function registerSkillCommands(program) {
                 const fm = serializeFrontmatter({
                     name: skillName,
                     description: opts.description,
+                    type: skillType,
                 });
                 writeFileSync(skillFile, fm, 'utf8');
                 out(skillFile);
@@ -277,6 +345,7 @@ export function registerSkillCommands(program) {
             const fm = serializeFrontmatter({
                 name: skillName,
                 description: opts.description,
+                type: skillType,
             });
             writeFileSync(skillFile, fm, 'utf8');
             out(skillFile);
@@ -290,7 +359,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));
@@ -298,7 +367,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));
@@ -363,6 +432,8 @@ export function registerSkillCommands(program) {
         .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();

package/dist/core/artifact.js

@@ -6,7 +6,8 @@ import { CRTR_DIR_NAME } from '../types.js';
 import { ensureDir, pathExists, readText, walkFiles } from './fs-utils.js';
 import { usage, notFound, general } from './errors.js';
 import { out, hint, jsonOut, handleError, info } from './output.js';
-import { spawnSidePaneReview, DEFAULT_PANE_OPTS, } from './spawn.js';
+import { spawnSidePaneReview, countPanesInCurrentWindow, DEFAULT_PANE_OPTS, } from './spawn.js';
+import { readConfig } from './config.js';
 export function mangleCwd(cwd = process.cwd()) {
     return cwd.replace(/\//g, '-');
 }
@@ -32,7 +33,17 @@ export function inTmux() {
     return Boolean(process.env.TMUX);
 }
 export function openInTmuxPane(path) {
-    const result = spawnSync('termrender', ['--tmux', path], {
+    // Always pass --watch so the pane live-updates when the agent edits the
+    // file. The watcher re-detects width on resize and survives parse errors.
+    const args = ['--tmux', '--watch'];
+    // If the current tmux window is already at the configured pane budget,
+    // open in a new window instead of cramping the existing split further.
+    const maxPanes = readConfig('user').max_panes_per_window;
+    if (countPanesInCurrentWindow() >= maxPanes) {
+        args.push('--tmux-new-window');
+    }
+    args.push(path);
+    const result = spawnSync('termrender', args, {
         stdio: ['ignore', 'pipe', 'pipe'],
     });
     if (result.error) {
@@ -52,7 +63,7 @@ export function openInTmuxPane(path) {
     }
     const paneId = result.stdout.toString().trim();
     if (paneId)
-        hint(`opened in tmux pane ${paneId}`);
+        hint(`opened in tmux pane ${paneId} (live — edits to the file refresh the view)`);
 }
 async function readStdin() {
     const chunks = [];

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,15 +13,19 @@ 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;
 }
 export declare function resolveSkill(rawName: string, opts?: SkillResolutionOpts): Skill;
-export declare function parseSkillQualifier(raw: string): {
+export interface ParsedSkillQualifier {
+    scope?: Scope;
     plugin?: string;
     name: string;
-};
+}
+export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
 export declare function listInstalledMarketplaces(scope: Scope): InstalledMarketplace[];
 export declare function listAllMarketplaces(): InstalledMarketplace[];
 export declare function findMarketplaceByName(name: string, scope?: Scope): InstalledMarketplace | null;

package/dist/core/resolver.js

@@ -4,9 +4,30 @@ import { readConfig } from './config.js';
 import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
-import { ambiguous, notFound } from './errors.js';
-import { marketplacesDir, pluginsDir, projectScopeRoot, scopeSkillsDir, userScopeRoot, } from './scope.js';
+import { ambiguous, notFound, usage } from './errors.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,17 +162,83 @@ 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 { plugin: pluginQualifier, name } = parseSkillQualifier(rawName);
-    const plugins = opts.scope ? listInstalledPlugins(opts.scope) : listAllPlugins();
+    const parsed = parseSkillQualifier(rawName);
+    if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
+        throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
+    }
+    if (parsed.plugin && opts.pluginFilter && parsed.plugin !== opts.pluginFilter) {
+        throw usage(`plugin conflict: identifier "${rawName}" uses plugin "${parsed.plugin}" but --plugin is "${opts.pluginFilter}"`);
+    }
+    const effectiveScope = opts.scope ?? parsed.scope;
+    const effectivePluginFilter = opts.pluginFilter ?? parsed.plugin;
+    const direct = findSkillMatches(parsed.name, parsed.plugin, effectiveScope, effectivePluginFilter);
+    if (direct.length > 0)
+        return pickMatch(direct, parsed.name, parsed.plugin);
+    // Fallback: bare `plugin/name` (no colon) — try splitting on first `/`.
+    // Disambiguates "claude-authoring/rules" (which the search/list display also emits as
+    // "user:claude-authoring/rules") from a nested scope-root skill of the same shape.
+    if (!parsed.plugin && parsed.name.includes('/')) {
+        const slashIdx = parsed.name.indexOf('/');
+        const maybePlugin = parsed.name.slice(0, slashIdx);
+        const rest = parsed.name.slice(slashIdx + 1);
+        if (effectivePluginFilter === undefined || effectivePluginFilter === maybePlugin) {
+            const fallback = findSkillMatches(rest, maybePlugin, effectiveScope, maybePlugin);
+            if (fallback.length > 0)
+                return pickMatch(fallback, rest, maybePlugin);
+        }
+    }
+    throw notFound(formatNotFoundMessage(rawName, parsed), {
+        skill: parsed.name,
+        plugin: parsed.plugin,
+        scope: parsed.scope,
+    });
+}
+function findSkillMatches(name, pluginQualifier, scope, pluginFilter) {
+    const plugins = scope ? listInstalledPlugins(scope) : listAllPlugins();
     const enabledPlugins = plugins.filter((p) => p.enabled);
     const cfgs = loadScopeConfigs();
     const matches = [];
     // Scope-root skills first — they're the user's own captured knowledge.
-    if (!opts.pluginFilter &&
+    if (!pluginFilter &&
         (pluginQualifier === undefined || pluginQualifier === SCOPE_SKILL_PLUGIN)) {
-        const scopes = opts.scope
-            ? [opts.scope]
+        const scopes = scope
+            ? [scope]
             : [projectScopeRoot() ? 'project' : null, 'user'].filter(Boolean);
         for (const s of scopes) {
             const skillsRoot = scopeSkillsDir(s);
@@ -176,7 +266,7 @@ export function resolveSkill(rawName, opts = {}) {
     for (const plugin of ordered) {
         if (pluginQualifier && plugin.name !== pluginQualifier)
             continue;
-        if (opts.pluginFilter && plugin.name !== opts.pluginFilter)
+        if (pluginFilter && plugin.name !== pluginFilter)
             continue;
         const skillPath = join(plugin.root, SKILLS_DIR, ...name.split('/'), SKILL_ENTRY_FILE);
         if (!pathExists(skillPath))
@@ -195,20 +285,16 @@ export function resolveSkill(rawName, opts = {}) {
             disabledIn,
         });
     }
-    if (matches.length === 0) {
-        throw notFound(pluginQualifier
-            ? `skill not found: ${pluginQualifier}:${name}`
-            : `skill not found: ${name}`, { skill: name, plugin: pluginQualifier });
-    }
+    return matches;
+}
+function pickMatch(matches, name, pluginQualifier) {
     if (matches.length === 1)
         return matches[0];
     const sameScopeAndPlugin = matches.every((m) => m.plugin === matches[0].plugin && m.scope === matches[0].scope);
     if (sameScopeAndPlugin)
         return matches[0];
-    // Resolution order picks the first; flag ambiguity only if user didn't qualify.
-    if (!pluginQualifier) {
+    if (!pluginQualifier)
         return matches[0];
-    }
     throw ambiguous(`ambiguous skill: ${name}`, {
         skill: name,
         candidates: matches.map((m) => ({
@@ -218,14 +304,116 @@ export function resolveSkill(rawName, opts = {}) {
         })),
     });
 }
+function formatNotFoundMessage(rawName, parsed) {
+    const suggestions = suggestSkills(parsed.name, parsed.plugin);
+    const lines = [`skill not found: ${rawName}`];
+    lines.push('       expected forms: <name>, <plugin>:<name>, <scope>:<plugin>/<name>');
+    if (suggestions.length > 0) {
+        const formatted = suggestions
+            .map((s) => s.plugin === SCOPE_SKILL_PLUGIN ? s.name : `${s.plugin}:${s.name}`)
+            .slice(0, 3);
+        lines.push(`       did you mean: ${formatted.join(', ')}`);
+    }
+    else {
+        lines.push('       run `crtr skill list` or `crtr skill search <query>` to discover skills');
+    }
+    return lines.join('\n');
+}
+function suggestSkills(name, plugin) {
+    let all;
+    try {
+        all = listAllSkills();
+    }
+    catch {
+        return [];
+    }
+    const target = name.toLowerCase();
+    const targetBase = target.split('/').pop() ?? target;
+    const targetPluginGuess = target.includes('/') ? target.split('/')[0] : undefined;
+    const exactName = all.filter((s) => s.name.toLowerCase() === target);
+    if (exactName.length > 0)
+        return exactName;
+    const exactBase = all.filter((s) => {
+        const sBase = s.name.toLowerCase().split('/').pop() ?? s.name.toLowerCase();
+        return sBase === targetBase;
+    });
+    if (exactBase.length > 0)
+        return exactBase;
+    const scored = all
+        .map((s) => {
+        const sName = s.name.toLowerCase();
+        const sBase = sName.split('/').pop() ?? sName;
+        const sPlugin = s.plugin.toLowerCase();
+        let score = 0;
+        if (plugin !== undefined && sPlugin === plugin.toLowerCase())
+            score += 5;
+        if (targetPluginGuess !== undefined && sPlugin === targetPluginGuess)
+            score += 5;
+        if (sName.includes(target) || target.includes(sName))
+            score += 4;
+        if (sBase.includes(targetBase) || targetBase.includes(sBase))
+            score += 3;
+        if (editDistance(sBase, targetBase) <= 2)
+            score += 4;
+        return { skill: s, score };
+    })
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score);
+    return scored.slice(0, 3).map((x) => x.skill);
+}
+function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const prev = new Array(b.length + 1);
+    const curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j <= b.length; j++)
+            prev[j] = curr[j];
+    }
+    return prev[b.length];
+}
+const SCOPE_QUALIFIERS = new Set(['user', 'project']);
+// Accepted identifier forms:
+//   <name>                         — bare name; scope-root first, then plugins
+//   <plugin>:<name>                — explicit plugin
+//   <scope>:<name>                 — scope-root in a specific scope
+//   <scope>:<plugin>/<name>        — fully qualified (matches `skill list` / `skill search` display)
+// Bare `<plugin>/<name>` (no colon) is handled as a fallback inside resolveSkill.
 export function parseSkillQualifier(raw) {
-    const idx = raw.indexOf(':');
-    if (idx === -1)
+    const colonIdx = raw.indexOf(':');
+    if (colonIdx === -1)
         return { name: raw };
-    return { plugin: raw.slice(0, idx), name: raw.slice(idx + 1) };
+    const before = raw.slice(0, colonIdx);
+    const after = raw.slice(colonIdx + 1);
+    if (SCOPE_QUALIFIERS.has(before)) {
+        const scope = before;
+        const slashIdx = after.indexOf('/');
+        if (slashIdx !== -1) {
+            return {
+                scope,
+                plugin: after.slice(0, slashIdx),
+                name: after.slice(slashIdx + 1),
+            };
+        }
+        return { scope, name: after };
+    }
+    return { plugin: before, name: after };
 }
 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];