@compilr-dev/sdk 0.10.3 → 0.10.5

package/dist/agent.js

@@ -454,6 +454,12 @@ class CompilrAgentImpl {
     getUsage() {
         return { ...this.totalUsage };
     }
+    getModel() {
+        return this.agent.getModel();
+    }
+    setModel(modelId) {
+        this.agent.setModel(modelId);
+    }
     unwrap() {
         return this.agent;
     }

package/dist/config.d.ts

@@ -316,6 +316,10 @@ export interface CompilrAgent {
     clearHistory(): this;
     /** Get token usage info */
     getUsage(): UsageInfo;
+    /** Get the current model ID */
+    getModel(): string;
+    /** Change the model for subsequent LLM calls (same provider only) */
+    setModel(modelId: string): void;
     /** Get the underlying Agent instance */
     unwrap(): unknown;
     /** Abort the current run */

package/dist/guide/shared-content.js

@@ -129,6 +129,47 @@ Research projects have: /outline, /literature-review, /methodology, /abstract.
 Business projects have: /business-vision, /market-analysis, /financial-model, /pitch.
 
 Skills can be combined with your own instructions: type /design then add context.`,
+    },
+    {
+        id: 'custom-skills',
+        title: 'Custom Skills — Create Your Own Slash Commands',
+        keywords: [
+            'custom skill',
+            'user skill',
+            'project skill',
+            '/skill',
+            'SKILL.md',
+            'fork',
+            'bind',
+            'slash command',
+            'create skill',
+        ],
+        content: `You can create custom skills that become slash commands (e.g., /my-template).
+
+**What is a custom skill?**
+A folder with a SKILL.md file containing YAML frontmatter (name, description) and a markdown body (the prompt the agent receives). Follows the Anthropic Agent Skills format.
+
+**Two scopes:**
+- **User scope** (~/.compilr-dev/skills/) — personal, works across all projects
+- **Project scope** (<project>/.compilr/skills/) — shared via version control
+
+**CLI:** Use the /skill overlay to create, edit, fork, bind, enable/disable, delete, and rename skills. Press n to create, e to edit (fullscreen editor), f to fork an SDK skill, b to manage bindings.
+
+**Desktop:** The Agents panel has a Skills section showing custom skills. Click the maximize button to open the SkillsView tab with full management (create, fork, bind/unbind, enable/disable, delete). Click a skill name to view/edit in the code editor.
+
+**Forking SDK skills:**
+You cannot override built-in skills directly. Instead, fork them: this creates a copy with your changes. Then bind a slash command to your fork (e.g., /design → design-acme). The capability bundle still loads based on the command name.
+
+**Bindings:**
+Bindings remap slash commands to custom skills. Example: bind /design to your forked design-acme skill. When you type /design, it uses your custom prompt instead of the SDK version. Use the Bindings tab/section to manage them.
+
+**Validation:**
+Skills with issues (short description, empty body, name mismatch) show a ⚠ warning. Fix them in the editor — validation runs automatically on save.
+
+**Custom skills appear in:**
+- Slash command autocomplete (/ in chat)
+- Help menu (/help in CLI)
+- Slash command picker (/ button in Desktop)`,
     },
     // ── Models & Providers ──────────────────────────────────────────────────
     {

package/dist/index.d.ts

@@ -69,7 +69,8 @@ export type { ProjectAnchorStoreConfig, ImageToolsConfig, ImageResizer } from '.
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, SkillEligibilityContext, SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './skills/index.js';
 export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readSkillScopeConfig, readSkillScopeConfigSync, writeSkillScopeConfig, getSkillBindings, resolveSkillBinding, } from './skills/index.js';
-export type { SkillScope } from './skills/index.js';
+export type { SkillScope, SkillPromptResolution, AvailableSkillEntry, SkillSources, } from './skills/index.js';
+export { resolveSkillPrompt, getAllAvailableSkills } from './skills/index.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './skills/index.js';
 export { ACTION_REGISTRY, getActionsForContext, getActionById, resolveActionPrompt, buildContextSummary, getSuggestedRole, } from './actions/index.js';
 export type { ActionContext, ActionDefinition } from './actions/index.js';

package/dist/index.js

@@ -153,6 +153,7 @@ export { createPlatformTools, createProjectTools, createWorkItemTools, createDoc
 // =============================================================================
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
 export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readSkillScopeConfig, readSkillScopeConfigSync, writeSkillScopeConfig, getSkillBindings, resolveSkillBinding, } from './skills/index.js';
+export { resolveSkillPrompt, getAllAvailableSkills } from './skills/index.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './skills/index.js';
 // =============================================================================
 // Contextual Actions (skill invocations with context)

package/dist/skills/index.d.ts

@@ -10,4 +10,6 @@ export type { SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig,
 export { detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill, } from './operations.js';
 export type { SkillScope } from './paths.js';
 export { getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readScopeConfig as readSkillScopeConfig, readScopeConfigSync as readSkillScopeConfigSync, writeScopeConfig as writeSkillScopeConfig, getAllBindings as getSkillBindings, resolveBinding as resolveSkillBinding, } from './paths.js';
+export type { SkillPromptResolution, AvailableSkillEntry, SkillSources, } from './prompt-resolver.js';
+export { resolveSkillPrompt, getAllAvailableSkills } from './prompt-resolver.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './platform-skills.js';

package/dist/skills/index.js

@@ -3,4 +3,5 @@ export { parseSkillMarkdown, loadSkillsFromDir } from './loader.js';
 export { resolveLayeredSkills, resolveSkillsForAgent } from './resolver.js';
 export { detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill, } from './operations.js';
 export { getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readScopeConfig as readSkillScopeConfig, readScopeConfigSync as readSkillScopeConfigSync, writeScopeConfig as writeSkillScopeConfig, getAllBindings as getSkillBindings, resolveBinding as resolveSkillBinding, } from './paths.js';
+export { resolveSkillPrompt, getAllAvailableSkills } from './prompt-resolver.js';
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, outlineSkill, literatureReviewSkill, draftSectionSkill, peerReviewSkill, researchScaffoldSkill, businessVisionSkill, marketAnalysisSkill, competitorAnalysisSkill, financialModelSkill, pitchOutlineSkill, businessReviewSkill, brandSetupSkill, contentStrategySkill, contentCalendarSkill, createContentSkill, contentReviewSkill, curriculumDesignSkill, lessonPlanSkill, assessmentDesignSkill, courseReviewSkill, bookOutlineSkill, characterDesignSkill, plotThreadsSkill, sceneBreakdownSkill, bookReviewSkill, } from './platform-skills.js';

package/dist/skills/prompt-resolver.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Unified skill prompt resolver — used by both CLI and Desktop.
+ *
+ * Resolves a slash command name to a skill prompt using:
+ * 1. Binding resolution (config.json slashCommands)
+ * 2. 5-layer priority: project → user → SDK platform → agents builtin → agents-coding
+ *
+ * Also provides getAllAvailableSkills() for autocomplete/picker display.
+ */
+import type { ForkedFromMarker } from './types.js';
+/** Result of resolving a skill prompt */
+export interface SkillPromptResolution {
+    /** The resolved skill prompt text */
+    prompt: string;
+    /** The skill name that provided the prompt (may differ from input if bound) */
+    skillName: string;
+    /** Whether this was resolved via a config.json binding */
+    isBound: boolean;
+    /** Fork info if the resolved skill is forked from an SDK skill */
+    forkedFrom?: ForkedFromMarker;
+    /** Source layer where the skill was found */
+    source?: 'project' | 'user' | 'sdk' | 'agents' | 'agents-coding' | 'factory';
+}
+/** Entry in the available skills list (for autocomplete/picker) */
+export interface AvailableSkillEntry {
+    /** Skill name (used as slash command) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Where this skill comes from */
+    source: 'project' | 'user' | 'sdk' | 'agents' | 'binding';
+    /** Scope for custom skills */
+    scope?: 'user' | 'project';
+    /** Whether the skill is enabled (custom skills only) */
+    enabled?: boolean;
+    /** Whether the skill has validation warnings */
+    hasWarnings?: boolean;
+    /** For binding entries: the command name */
+    boundCommand?: string;
+    /** Whether this is a forked skill */
+    isForked?: boolean;
+}
+/** Additional skill sources that consumers can provide */
+export interface SkillSources {
+    /** Factory skills (from @compilr-dev/factory) */
+    factorySkills?: readonly {
+        name: string;
+        description: string;
+        prompt: string;
+    }[];
+    /** Coding skills (from @compilr-dev/agents-coding) */
+    codingSkills?: readonly {
+        name: string;
+        description: string;
+        prompt: string;
+    }[];
+}
+/**
+ * Resolve a slash command name to a skill prompt.
+ *
+ * Resolution order:
+ * 1. Check bindings (config.json slashCommands — project overrides user)
+ * 2. Project-scoped custom skills (<projectDir>/.compilr/skills/)
+ * 3. User-scoped custom skills (~/.compilr-dev/skills/)
+ * 4. SDK platform skills
+ * 5. Additional sources (factory, agents builtin, agents-coding)
+ *
+ * @param name - The slash command name (without leading /)
+ * @param projectDir - Project directory for project-scoped skills and bindings
+ * @param sources - Additional skill sources (factory, coding)
+ * @returns Resolution result with prompt and metadata, or null if not found
+ */
+export declare function resolveSkillPrompt(name: string, projectDir?: string, sources?: SkillSources): SkillPromptResolution | null;
+/**
+ * Get all available skills for display (autocomplete, picker, help menu).
+ *
+ * Returns a deduplicated list from all sources with metadata.
+ * Project skills override user skills override SDK skills (by name).
+ *
+ * @param projectDir - Project directory for project-scoped skills and bindings
+ * @param sources - Additional skill sources (factory, coding)
+ * @returns List of all available skills with source and metadata
+ */
+export declare function getAllAvailableSkills(projectDir?: string, sources?: SkillSources): AvailableSkillEntry[];

package/dist/skills/prompt-resolver.js

@@ -0,0 +1,235 @@
+/**
+ * Unified skill prompt resolver — used by both CLI and Desktop.
+ *
+ * Resolves a slash command name to a skill prompt using:
+ * 1. Binding resolution (config.json slashCommands)
+ * 2. 5-layer priority: project → user → SDK platform → agents builtin → agents-coding
+ *
+ * Also provides getAllAvailableSkills() for autocomplete/picker display.
+ */
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseSkillMarkdown } from './loader.js';
+import { resolveBinding, getSkillsDir, readScopeConfigSync } from './paths.js';
+import { platformSkills } from './platform-skills.js';
+// Re-export builtinSkills from agents (available via SDK re-export)
+// The SDK re-exports builtinSkills from @compilr-dev/agents
+import { builtinSkills } from '@compilr-dev/agents';
+// =============================================================================
+// Prompt Resolution
+// =============================================================================
+/**
+ * Read a skill prompt from a scoped directory (project or user).
+ * Returns null if the skill doesn't exist, is disabled, or has malformed frontmatter.
+ */
+function readScopedSkillPrompt(scope, name, projectDir) {
+    try {
+        const file = join(getSkillsDir(scope, projectDir), name, 'SKILL.md');
+        if (!existsSync(file))
+            return null;
+        const content = readFileSync(file, 'utf-8');
+        const parsed = parseSkillMarkdown(content);
+        if (!parsed || parsed.enabled === false)
+            return null;
+        return parsed.prompt;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Read the forkedFrom marker from a scoped skill.
+ */
+function readScopedSkillForkedFrom(scope, name, projectDir) {
+    try {
+        const file = join(getSkillsDir(scope, projectDir), name, 'SKILL.md');
+        const content = readFileSync(file, 'utf-8');
+        const parsed = parseSkillMarkdown(content);
+        return parsed?.forkedFrom ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a slash command name to a skill prompt.
+ *
+ * Resolution order:
+ * 1. Check bindings (config.json slashCommands — project overrides user)
+ * 2. Project-scoped custom skills (<projectDir>/.compilr/skills/)
+ * 3. User-scoped custom skills (~/.compilr-dev/skills/)
+ * 4. SDK platform skills
+ * 5. Additional sources (factory, agents builtin, agents-coding)
+ *
+ * @param name - The slash command name (without leading /)
+ * @param projectDir - Project directory for project-scoped skills and bindings
+ * @param sources - Additional skill sources (factory, coding)
+ * @returns Resolution result with prompt and metadata, or null if not found
+ */
+export function resolveSkillPrompt(name, projectDir, sources) {
+    // 1. Check bindings
+    const boundName = resolveBinding(name, projectDir);
+    if (boundName && boundName !== name) {
+        for (const scope of ['project', 'user']) {
+            const prompt = readScopedSkillPrompt(scope, boundName, projectDir);
+            if (prompt) {
+                const forkedFrom = readScopedSkillForkedFrom(scope, boundName, projectDir);
+                return {
+                    prompt,
+                    skillName: boundName,
+                    isBound: true,
+                    forkedFrom: forkedFrom ?? undefined,
+                    source: scope,
+                };
+            }
+        }
+        // Bound skill not found — fall through to normal resolution
+    }
+    // 2. Project-scoped custom skills
+    if (projectDir) {
+        const prompt = readScopedSkillPrompt('project', name, projectDir);
+        if (prompt) {
+            return { prompt, skillName: name, isBound: false, source: 'project' };
+        }
+    }
+    // 3. User-scoped custom skills
+    {
+        const prompt = readScopedSkillPrompt('user', name);
+        if (prompt) {
+            return { prompt, skillName: name, isBound: false, source: 'user' };
+        }
+    }
+    // 4. SDK platform skills
+    const sdkSkill = platformSkills.find((s) => s.name === name);
+    if (sdkSkill) {
+        return { prompt: sdkSkill.prompt, skillName: name, isBound: false, source: 'sdk' };
+    }
+    // 5. Additional sources
+    if (sources?.factorySkills) {
+        const factorySkill = sources.factorySkills.find((s) => s.name === name);
+        if (factorySkill) {
+            return { prompt: factorySkill.prompt, skillName: name, isBound: false, source: 'factory' };
+        }
+    }
+    const agentsSkill = builtinSkills.find((s) => s.name === name);
+    if (agentsSkill) {
+        return { prompt: agentsSkill.prompt, skillName: name, isBound: false, source: 'agents' };
+    }
+    if (sources?.codingSkills) {
+        const codingSkill = sources.codingSkills.find((s) => s.name === name);
+        if (codingSkill) {
+            return {
+                prompt: codingSkill.prompt,
+                skillName: name,
+                isBound: false,
+                source: 'agents-coding',
+            };
+        }
+    }
+    return null;
+}
+// =============================================================================
+// Available Skills List
+// =============================================================================
+/**
+ * Get all available skills for display (autocomplete, picker, help menu).
+ *
+ * Returns a deduplicated list from all sources with metadata.
+ * Project skills override user skills override SDK skills (by name).
+ *
+ * @param projectDir - Project directory for project-scoped skills and bindings
+ * @param sources - Additional skill sources (factory, coding)
+ * @returns List of all available skills with source and metadata
+ */
+export function getAllAvailableSkills(projectDir, sources) {
+    const entries = [];
+    const seen = new Set();
+    // 1. Custom skills (project + user)
+    for (const scope of ['project', 'user']) {
+        try {
+            const dir = getSkillsDir(scope, scope === 'project' ? projectDir : undefined);
+            const dirEntries = readdirSync(dir, { withFileTypes: true });
+            for (const entry of dirEntries) {
+                if (!entry.isDirectory() || seen.has(entry.name))
+                    continue;
+                seen.add(entry.name);
+                try {
+                    const content = readFileSync(join(dir, entry.name, 'SKILL.md'), 'utf-8');
+                    const parsed = parseSkillMarkdown(content);
+                    if (parsed) {
+                        entries.push({
+                            name: parsed.name,
+                            description: parsed.description,
+                            source: scope,
+                            scope,
+                            enabled: parsed.enabled !== false,
+                            hasWarnings: parsed.description.length < 60 || !parsed.prompt.trim(),
+                            isForked: !!parsed.forkedFrom,
+                        });
+                    }
+                }
+                catch {
+                    /* skip malformed */
+                }
+            }
+        }
+        catch {
+            /* dir doesn't exist */
+        }
+    }
+    // 2. SDK platform skills
+    for (const skill of platformSkills) {
+        if (!seen.has(skill.name)) {
+            seen.add(skill.name);
+            entries.push({ name: skill.name, description: skill.description, source: 'sdk' });
+        }
+    }
+    // 3. Agents builtin skills
+    for (const skill of builtinSkills) {
+        if (!seen.has(skill.name)) {
+            seen.add(skill.name);
+            entries.push({ name: skill.name, description: skill.description, source: 'agents' });
+        }
+    }
+    // 4. Additional sources
+    if (sources?.factorySkills) {
+        for (const skill of sources.factorySkills) {
+            if (!seen.has(skill.name)) {
+                seen.add(skill.name);
+                entries.push({ name: skill.name, description: skill.description, source: 'sdk' });
+            }
+        }
+    }
+    if (sources?.codingSkills) {
+        for (const skill of sources.codingSkills) {
+            if (!seen.has(skill.name)) {
+                seen.add(skill.name);
+                entries.push({ name: skill.name, description: skill.description, source: 'agents' });
+            }
+        }
+    }
+    // 5. Bound commands (as separate entries)
+    for (const scope of ['project', 'user']) {
+        try {
+            const config = readScopeConfigSync(scope, scope === 'project' ? projectDir : undefined);
+            if (config.slashCommands) {
+                for (const [cmd, skillName] of Object.entries(config.slashCommands)) {
+                    if (!seen.has(cmd)) {
+                        seen.add(cmd);
+                        entries.push({
+                            name: cmd,
+                            description: `→ ${skillName} [${scope} binding]`,
+                            source: 'binding',
+                            scope,
+                            boundCommand: cmd,
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return entries;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@compilr-dev/agents": "^0.5.7",
+    "@compilr-dev/agents": "^0.5.8",
     "@compilr-dev/logger": "^0.1.0",
     "@compilr-dev/sdk": "^0.10.2",
     "ajv": "^6.14.0",