@compilr-dev/sdk 0.9.30 → 0.10.0

package/dist/index.d.ts

@@ -67,6 +67,8 @@ export type { GuideEntry, ContentTopic, ContentSection, GuideToolConfig } from '
 export { createPlatformTools, createProjectTools, createWorkItemTools, createDocumentTools, createPlanTools, createBacklogTools, createAnchorTools, createArtifactTools, createEpisodeTools, createImageTools, ProjectAnchorStore, } from './platform/index.js';
 export type { ProjectAnchorStoreConfig, ImageToolsConfig, ImageResizer } from './platform/index.js';
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
+export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, SkillEligibilityContext, } from './skills/index.js';
+export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, } 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

@@ -152,9 +152,7 @@ export { createPlatformTools, createProjectTools, createWorkItemTools, createDoc
 // Platform Workflow (pure step-criteria logic)
 // =============================================================================
 export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, getStepNumber, } from './platform/index.js';
-// =============================================================================
-// Platform Skills (platform-specific prompt expansions)
-// =============================================================================
+export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, } 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

@@ -1,4 +1,9 @@
 /**
  * Platform Skills — barrel export
  */
+export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker } from './types.js';
+export { RESERVED_SKILL_NAMES, isReservedSkillName } from './types.js';
+export { parseSkillMarkdown, loadSkillsFromDir } from './loader.js';
+export type { SkillEligibilityContext } from './resolver.js';
+export { resolveLayeredSkills, resolveSkillsForAgent } from './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

@@ -1,4 +1,4 @@
-/**
- * Platform Skills — barrel export
- */
+export { RESERVED_SKILL_NAMES, isReservedSkillName } from './types.js';
+export { parseSkillMarkdown, loadSkillsFromDir } from './loader.js';
+export { resolveLayeredSkills, resolveSkillsForAgent } from './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/loader.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Skill loader — reads <dir>/<name>/SKILL.md from disk into CustomSkill objects.
+ *
+ * File format follows Anthropic Agent Skills spec (agentskills.io):
+ *   <name>/SKILL.md       — required, frontmatter + body
+ *   <name>/references/    — optional progressive-disclosure detail
+ *   <name>/scripts/       — optional executable scripts
+ *   <name>/templates/     — optional starter files
+ *   <name>/assets/        — optional binary assets
+ *   <name>/LICENSE.txt    — optional, author's choice
+ *
+ * Spec: /workspace/project-docs/00-requirements/compilr-dev-sdk/custom-skills-spec.md
+ */
+import type { CustomSkill } from './types.js';
+/**
+ * Parse a SKILL.md string into a CustomSkill.
+ *
+ * Minimal YAML frontmatter parser — handles the subset we use without
+ * pulling in a yaml dependency. Returns null on malformed input so the
+ * caller can warn-and-skip rather than crash.
+ */
+export declare function parseSkillMarkdown(content: string, sourcePath?: string, source?: CustomSkill['source']): CustomSkill | null;
+/**
+ * Load all skills from a directory. Each subdirectory containing a
+ * SKILL.md becomes one CustomSkill. Malformed files are skipped with
+ * a warning callback.
+ *
+ * Returns [] if the directory doesn't exist.
+ */
+export declare function loadSkillsFromDir(dir: string, source?: CustomSkill['source'], onWarn?: (msg: string) => void): Promise<CustomSkill[]>;

package/dist/skills/loader.js

@@ -0,0 +1,133 @@
+/**
+ * Skill loader — reads <dir>/<name>/SKILL.md from disk into CustomSkill objects.
+ *
+ * File format follows Anthropic Agent Skills spec (agentskills.io):
+ *   <name>/SKILL.md       — required, frontmatter + body
+ *   <name>/references/    — optional progressive-disclosure detail
+ *   <name>/scripts/       — optional executable scripts
+ *   <name>/templates/     — optional starter files
+ *   <name>/assets/        — optional binary assets
+ *   <name>/LICENSE.txt    — optional, author's choice
+ *
+ * Spec: /workspace/project-docs/00-requirements/compilr-dev-sdk/custom-skills-spec.md
+ */
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYamlReal } from 'yaml';
+/**
+ * Parse a SKILL.md string into a CustomSkill.
+ *
+ * Minimal YAML frontmatter parser — handles the subset we use without
+ * pulling in a yaml dependency. Returns null on malformed input so the
+ * caller can warn-and-skip rather than crash.
+ */
+export function parseSkillMarkdown(content, sourcePath, source) {
+    // Frontmatter is delimited by `---` on its own line at the very top.
+    const fm = matchFrontmatter(content);
+    if (!fm)
+        return null;
+    const meta = parseYaml(fm.frontmatter);
+    if (!meta)
+        return null;
+    const name = typeof meta['name'] === 'string' ? meta['name'] : null;
+    const description = typeof meta['description'] === 'string' ? meta['description'] : null;
+    if (!name || !description)
+        return null;
+    const skill = {
+        name,
+        description,
+        prompt: fm.body.trim(),
+        sourcePath,
+        source,
+    };
+    if (typeof meta['license'] === 'string')
+        skill.license = meta['license'];
+    if (typeof meta['version'] === 'string')
+        skill.version = meta['version'];
+    if (Array.isArray(meta['tags']))
+        skill.tags = meta['tags'].filter((t) => typeof t === 'string');
+    if (typeof meta['enabled'] === 'boolean')
+        skill.enabled = meta['enabled'];
+    if (meta['compilr'] && typeof meta['compilr'] === 'object') {
+        skill.compilr = meta['compilr'];
+    }
+    if (meta['forkedFrom'] && typeof meta['forkedFrom'] === 'object') {
+        skill.forkedFrom = meta['forkedFrom'];
+    }
+    return skill;
+}
+/**
+ * Load all skills from a directory. Each subdirectory containing a
+ * SKILL.md becomes one CustomSkill. Malformed files are skipped with
+ * a warning callback.
+ *
+ * Returns [] if the directory doesn't exist.
+ */
+export async function loadSkillsFromDir(dir, source = 'user', onWarn) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skillDir = join(dir, entry.name);
+        const skillFile = join(skillDir, 'SKILL.md');
+        let content;
+        try {
+            content = await fs.readFile(skillFile, 'utf-8');
+        }
+        catch {
+            continue; // No SKILL.md in this directory — not a skill folder.
+        }
+        const parsed = parseSkillMarkdown(content, skillDir, source);
+        if (!parsed) {
+            onWarn?.(`Skill at ${skillFile} has invalid frontmatter (missing name or description)`);
+            continue;
+        }
+        // Auto-set scope from source if not explicit.
+        if (!parsed.compilr)
+            parsed.compilr = {};
+        if (!parsed.compilr.scope) {
+            parsed.compilr.scope =
+                source === 'project' ? 'project' : source === 'user' ? 'user' : undefined;
+        }
+        skills.push(parsed);
+    }
+    return skills;
+}
+// =============================================================================
+// Internal — frontmatter + minimal YAML
+// =============================================================================
+function matchFrontmatter(content) {
+    if (!content.startsWith('---'))
+        return null;
+    const lines = content.split('\n');
+    if (lines[0] !== '---')
+        return null;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === '---') {
+            return {
+                frontmatter: lines.slice(1, i).join('\n'),
+                body: lines.slice(i + 1).join('\n'),
+            };
+        }
+    }
+    return null;
+}
+function parseYaml(text) {
+    try {
+        const parsed = parseYamlReal(text);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/skills/resolver.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Skill resolver — 5-layer priority + 2-stage selection.
+ *
+ * Spec: /workspace/project-docs/00-requirements/compilr-dev-sdk/custom-skills-spec.md
+ *
+ * 5-layer priority (first match by name wins):
+ *   1. project (<projectDir>/.compilr/skills/)
+ *   2. user    (~/.compilr-dev/skills/)
+ *   3. sdk     (platformSkills)
+ *   4. agents  (builtinSkills)
+ *   5. agents-coding (codingSkills)
+ *
+ * 2-stage selection:
+ *   - Stage 1 ELIGIBILITY: declarative filter, runs at agent boot.
+ *   - Stage 2 ACTIVATION: model picks from descriptions, runs per turn.
+ *     (Stage 2 is the existing skill invocation — this file only does Stage 1.)
+ */
+import type { CustomSkill } from './types.js';
+/**
+ * Agent context used for eligibility filtering. Decoupled from the full
+ * Agent class so non-runtime callers (CLI listers, desktop preview) can
+ * compute eligibility without instantiating an agent.
+ */
+export interface SkillEligibilityContext {
+    /** Agent's role identifier ('arch', 'qa', 'researcher', 'writer', etc.). */
+    role?: string;
+    /** Specific custom-agent id, if any. */
+    agentId?: string;
+    /** Tool names this agent has access to. */
+    toolNames?: ReadonlySet<string> | readonly string[];
+    /** Explicit skill allowlist on the agent (legacy enabledSkills). */
+    enabledSkills?: readonly string[];
+    /** Active project category ('software', 'research', 'business', ...). */
+    projectType?: string;
+}
+/**
+ * Resolve a list of skills from layered sources by priority. First match
+ * by name wins. Returns the deduplicated list, with each skill carrying
+ * its `source` field so callers can render origin in the UI.
+ */
+export declare function resolveLayeredSkills(layers: {
+    project?: CustomSkill[];
+    user?: CustomSkill[];
+    sdk?: CustomSkill[];
+    agents?: CustomSkill[];
+    agentsCoding?: CustomSkill[];
+}): CustomSkill[];
+/**
+ * Stage 1 — Eligibility filter. Given a resolved skill registry and an
+ * agent context, return only the skills this agent should see.
+ *
+ * Stage 2 (model picks based on description) is the existing skill
+ * activation flow and lives at the call site, not here.
+ */
+export declare function resolveSkillsForAgent(skills: CustomSkill[], context: SkillEligibilityContext): CustomSkill[];

package/dist/skills/resolver.js

@@ -0,0 +1,80 @@
+/**
+ * Skill resolver — 5-layer priority + 2-stage selection.
+ *
+ * Spec: /workspace/project-docs/00-requirements/compilr-dev-sdk/custom-skills-spec.md
+ *
+ * 5-layer priority (first match by name wins):
+ *   1. project (<projectDir>/.compilr/skills/)
+ *   2. user    (~/.compilr-dev/skills/)
+ *   3. sdk     (platformSkills)
+ *   4. agents  (builtinSkills)
+ *   5. agents-coding (codingSkills)
+ *
+ * 2-stage selection:
+ *   - Stage 1 ELIGIBILITY: declarative filter, runs at agent boot.
+ *   - Stage 2 ACTIVATION: model picks from descriptions, runs per turn.
+ *     (Stage 2 is the existing skill invocation — this file only does Stage 1.)
+ */
+/**
+ * Resolve a list of skills from layered sources by priority. First match
+ * by name wins. Returns the deduplicated list, with each skill carrying
+ * its `source` field so callers can render origin in the UI.
+ */
+export function resolveLayeredSkills(layers) {
+    const seen = new Map();
+    const tag = (skills, source) => (skills ?? []).map((s) => ({ ...s, source: s.source ?? source }));
+    // Priority order: project > user > sdk > agents > agents-coding.
+    for (const skill of [
+        ...tag(layers.project, 'project'),
+        ...tag(layers.user, 'user'),
+        ...tag(layers.sdk, 'sdk'),
+        ...tag(layers.agents, 'agents'),
+        ...tag(layers.agentsCoding, 'agents-coding'),
+    ]) {
+        if (!seen.has(skill.name)) {
+            seen.set(skill.name, skill);
+        }
+    }
+    return [...seen.values()];
+}
+/**
+ * Stage 1 — Eligibility filter. Given a resolved skill registry and an
+ * agent context, return only the skills this agent should see.
+ *
+ * Stage 2 (model picks based on description) is the existing skill
+ * activation flow and lives at the call site, not here.
+ */
+export function resolveSkillsForAgent(skills, context) {
+    const toolSet = context.toolNames instanceof Set ? context.toolNames : new Set(context.toolNames ?? []);
+    const allowlist = context.enabledSkills ? new Set(context.enabledSkills) : null;
+    return skills.filter((skill) => {
+        if (skill.enabled === false)
+            return false;
+        // Stage 1.1 — Targeting. Default = targets every agent.
+        const targets = skill.compilr?.targets;
+        if (targets) {
+            const matches = targets.all === true ||
+                (targets.roles && context.role && targets.roles.includes(context.role)) ||
+                (targets.agentIds && context.agentId && targets.agentIds.includes(context.agentId));
+            if (!matches)
+                return false;
+        }
+        // Stage 1.2 — Project type filter.
+        const requires = skill.compilr?.requires;
+        if (requires?.projectTypes && context.projectType) {
+            if (!requires.projectTypes.includes(context.projectType))
+                return false;
+        }
+        // Stage 1.3 — Tool guard.
+        if (requires?.tools) {
+            for (const t of requires.tools) {
+                if (!toolSet.has(t))
+                    return false;
+            }
+        }
+        // Stage 1.4 — Agent's explicit enabledSkills allowlist (legacy mechanism).
+        if (allowlist && !allowlist.has(skill.name))
+            return false;
+        return true;
+    });
+}

package/dist/skills/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Custom skill types — Anthropic-format frontmatter + compilr extensions.
+ *
+ * Spec: /workspace/project-docs/00-requirements/compilr-dev-sdk/custom-skills-spec.md
+ *
+ * The base shape matches Anthropic's Agent Skills standard
+ * (https://agentskills.io/specification): folder with SKILL.md, YAML
+ * frontmatter requiring only `name` + `description`. Our multi-agent
+ * extensions live under the optional `compilr:` block, which
+ * Anthropic-compatible runtimes ignore.
+ */
+import type { AgentRole } from '../team/types.js';
+/**
+ * Compilr-specific skill targeting and requirements.
+ *
+ * Lives under the `compilr:` key in SKILL.md frontmatter. Optional —
+ * defaults to `targets: { all: true }` and no requires.
+ */
+export interface CompilrSkillExtension {
+    /** Which agents are eligible to load this skill. */
+    targets?: {
+        /** Match by role (e.g. 'researcher', 'writer', 'arch', 'qa'). */
+        roles?: AgentRole[];
+        /** Match by specific custom-agent id. */
+        agentIds?: string[];
+        /** Set true to target every agent in the project. */
+        all?: boolean;
+    };
+    /** Conditions that must hold for the skill to be eligible. */
+    requires?: {
+        /** Tool names the agent must have to load this skill. */
+        tools?: string[];
+        /** Project categories where this skill applies. */
+        projectTypes?: string[];
+    };
+    /** Where the skill lives. Auto-set by location, but explicit is allowed. */
+    scope?: 'user' | 'project';
+}
+/**
+ * Marker on forked SDK skills.
+ */
+export interface ForkedFromMarker {
+    source: string;
+    skill: string;
+    version: string;
+    forkedAt: string;
+}
+/**
+ * Custom skill — matches Anthropic spec + compilr extensions.
+ *
+ * Loaded from SKILL.md files in user/project skill directories. Built-in
+ * SDK skills (defined via defineSkill()) extend the base agents-lib Skill
+ * shape with these same optional fields for consistency.
+ */
+export interface CustomSkill {
+    name: string;
+    description: string;
+    /** Markdown body — the prompt text. */
+    prompt: string;
+    license?: string;
+    version?: string;
+    tags?: string[];
+    enabled?: boolean;
+    compilr?: CompilrSkillExtension;
+    /** Set when this skill was created via /skill fork. */
+    forkedFrom?: ForkedFromMarker;
+    /** Absolute path to the skill directory (containing SKILL.md). */
+    sourcePath?: string;
+    /** Where this skill came from. */
+    source?: 'project' | 'user' | 'sdk' | 'agents' | 'agents-coding';
+}
+/**
+ * SDK skill names that are reserved — user/project skills cannot use these.
+ *
+ * The CLI's `/skill new` validation rejects creation of any of these
+ * names. Customizing behavior of a reserved name happens via:
+ *   /skill fork <name>   →  clone under a new name
+ *   /skill bind <cmd>    →  remap slash command to a custom skill
+ *
+ * This list is the union of all platform-skill names exported by
+ * platform-skills.ts. Keep it in sync when adding new SDK skills.
+ */
+export declare const RESERVED_SKILL_NAMES: readonly string[];
+export declare function isReservedSkillName(name: string): boolean;

package/dist/skills/types.js

@@ -0,0 +1,67 @@
+/**
+ * Custom skill types — Anthropic-format frontmatter + compilr extensions.
+ *
+ * Spec: /workspace/project-docs/00-requirements/compilr-dev-sdk/custom-skills-spec.md
+ *
+ * The base shape matches Anthropic's Agent Skills standard
+ * (https://agentskills.io/specification): folder with SKILL.md, YAML
+ * frontmatter requiring only `name` + `description`. Our multi-agent
+ * extensions live under the optional `compilr:` block, which
+ * Anthropic-compatible runtimes ignore.
+ */
+/**
+ * SDK skill names that are reserved — user/project skills cannot use these.
+ *
+ * The CLI's `/skill new` validation rejects creation of any of these
+ * names. Customizing behavior of a reserved name happens via:
+ *   /skill fork <name>   →  clone under a new name
+ *   /skill bind <cmd>    →  remap slash command to a custom skill
+ *
+ * This list is the union of all platform-skill names exported by
+ * platform-skills.ts. Keep it in sync when adding new SDK skills.
+ */
+export const RESERVED_SKILL_NAMES = [
+    // Software (9)
+    'design',
+    'sketch',
+    'prd',
+    'refine',
+    'refine-item',
+    'architecture',
+    'session-notes',
+    'build',
+    'scaffold',
+    // Research (5)
+    'outline',
+    'literature-review',
+    'draft-section',
+    'peer-review',
+    'research-scaffold',
+    // Business (6)
+    'business-vision',
+    'market-analysis',
+    'competitor-analysis',
+    'financial-model',
+    'pitch-outline',
+    'business-review',
+    // Content (5)
+    'brand-setup',
+    'content-strategy',
+    'content-calendar',
+    'create-content',
+    'content-review',
+    // Course (4)
+    'curriculum-design',
+    'lesson-plan',
+    'assessment-design',
+    'course-review',
+    // Book (5)
+    'book-outline',
+    'character-design',
+    'plot-threads',
+    'scene-breakdown',
+    'book-review',
+];
+export function isReservedSkillName(name) {
+    return RESERVED_SKILL_NAMES.includes(name);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.9.30",
+  "version": "0.10.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -58,7 +58,8 @@
   "dependencies": {
     "@compilr-dev/agents": "^0.5.7",
     "@compilr-dev/logger": "^0.1.0",
-    "ajv": "^6.14.0"
+    "ajv": "^6.14.0",
+    "yaml": "^2.8.4"
   },
   "peerDependencies": {
     "@compilr-dev/agents-coding": "^1.0.6",