@compilr-dev/sdk 0.10.0 → 0.10.2

package/dist/index.d.ts

@@ -67,8 +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 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, } 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,7 +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';
-export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, } from './skills/index.js';
+export { RESERVED_SKILL_NAMES, isReservedSkillName, parseSkillMarkdown, loadSkillsFromDir, resolveLayeredSkills, resolveSkillsForAgent, detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill as validateSkillQuality, } 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/book-skills.js

@@ -6,7 +6,7 @@
 import { defineSkill } from '@compilr-dev/agents';
 export const bookOutlineSkill = defineSkill({
     name: 'book-outline',
-    description: 'Define book structure — beats, chapters, and story template',
+    description: 'Define the book structure — story template selection, beat sheet, chapter breakdown, and narrative arc. Use when starting a new book or restructuring an existing one. Produces a BookModel outline stored in the project database.',
     prompt: `You are in BOOK OUTLINE MODE. Help the user structure their book.
 
 ## Step 1: Book Overview
@@ -47,7 +47,7 @@ Create one "Chapter" work item per chapter.
 });
 export const characterDesignSkill = defineSkill({
     name: 'character-design',
-    description: 'Build character profiles, arcs, and relationship maps',
+    description: 'Build detailed character profiles including backstory, traits, motivations, arcs, and relationship maps. Use after the outline exists. Creates or updates character entries in the BookModel with connections between characters.',
     prompt: `You are in CHARACTER DESIGN MODE. Help the user build their cast.
 
 ## Step 1: Read Context
@@ -84,7 +84,7 @@ This feeds the Character Map visualization.
 });
 export const plotThreadsSkill = defineSkill({
     name: 'plot-threads',
-    description: 'Define and track plot threads across chapters',
+    description: 'Define and track plot threads across chapters — main plot, subplots, and thematic threads. Use when the outline and characters exist but narrative threads need explicit tracking. Maps each thread to the chapters where it appears.',
     prompt: `You are in PLOT THREADS MODE. Map the story's narrative threads.
 
 ## Step 1: Read Context
@@ -120,7 +120,7 @@ Report issues and suggest fixes.
 });
 export const sceneBreakdownSkill = defineSkill({
     name: 'scene-breakdown',
-    description: 'Break a chapter into detailed scenes',
+    description: 'Break a chapter into detailed scenes with setting, characters present, POV, conflict, and beats. Use when a chapter outline exists but needs scene-level granularity before drafting. Produces scene entries linked to the chapter in the BookModel.',
     prompt: `You are in SCENE BREAKDOWN MODE. Detail a chapter's scenes.
 
 ## Step 1: Read Context
@@ -153,7 +153,7 @@ Save: \`book_model_update\` op: "scene_add"
 });
 export const bookReviewSkill = defineSkill({
     name: 'book-review',
-    description: 'Structural review — beats, arcs, threads, pacing',
+    description: 'Structural review of the entire book — validates beat sheet completeness, character arc consistency, thread coverage across chapters, and pacing balance. Use after substantial content exists to find structural gaps before drafting or revision.',
     prompt: `You are in BOOK REVIEW MODE. Evaluate the book's structure.
 
 ## Step 1: Load

package/dist/skills/business-skills.js

@@ -6,7 +6,7 @@
 import { defineSkill } from '@compilr-dev/agents';
 export const businessVisionSkill = defineSkill({
     name: 'business-vision',
-    description: 'Define the business identity, problem, solution, and value proposition',
+    description: 'Define the core business identity — problem statement, solution, unique value proposition, target customer, and business stage. Use when starting a new business plan or when the foundational vision needs to be articulated. Produces the identity section of the BusinessModel.',
     prompt: `You are in BUSINESS VISION MODE. Help the user define and articulate their business idea.
 
 ## Step 1: Assess Current State
@@ -46,7 +46,7 @@ After saving, suggest:
 });
 export const marketAnalysisSkill = defineSkill({
     name: 'market-analysis',
-    description: 'Analyze market size, trends, and customer segments',
+    description: 'Analyze the target market — total addressable market (TAM), serviceable market (SAM), growth trends, and customer segmentation. Use after the business vision is defined. Produces market analysis data in the BusinessModel including size estimates and segment profiles.',
     prompt: `You are in MARKET ANALYSIS MODE. Help the user understand their market.
 
 ## Step 1: Assess Current State
@@ -91,7 +91,7 @@ Create Milestone work items for:
 });
 export const competitorAnalysisSkill = defineSkill({
     name: 'competitor-analysis',
-    description: 'Map the competitive landscape — identify competitors, strengths, weaknesses, positioning',
+    description: 'Map the competitive landscape — identify direct and indirect competitors, analyze their strengths and weaknesses, and define market positioning. Use after the market analysis to understand where the business fits. Produces competitor profiles and a positioning matrix in the BusinessModel.',
     prompt: `You are in COMPETITOR ANALYSIS MODE. Help the user understand their competition.
 
 ## Step 1: Assess Current State
@@ -151,7 +151,7 @@ Create work items for:
 });
 export const financialModelSkill = defineSkill({
     name: 'financial-model',
-    description: 'Build revenue forecasts, cost structure, and break-even analysis',
+    description: 'Build the financial model — revenue streams, pricing strategy, cost structure, break-even analysis, and projections. Use when the business vision and market analysis are complete. Produces financial forecasts and unit economics in the BusinessModel.',
     prompt: `You are in FINANCIAL MODEL MODE. Help the user build financial projections.
 
 ## Step 1: Assess Current State
@@ -214,7 +214,7 @@ Save: \`business_model_update\` op: "set_financials_fields", financials_field: {
 });
 export const pitchOutlineSkill = defineSkill({
     name: 'pitch-outline',
-    description: 'Structure an investor pitch or executive summary from the Business Model',
+    description: 'Structure an investor pitch deck or executive summary from the BusinessModel. Use when the plan is mature enough to present — extracts key metrics, value proposition, market opportunity, and financials into a presentation-ready narrative outline.',
     prompt: `You are in PITCH OUTLINE MODE. Help the user create a compelling pitch from their Business Model.
 
 ## Step 1: Assess Readiness
@@ -264,7 +264,7 @@ Create Milestone work items:
 });
 export const businessReviewSkill = defineSkill({
     name: 'business-review',
-    description: 'Validate the business plan — find gaps, weak assumptions, and missing elements',
+    description: 'Critical review of the entire business plan — identifies gaps, weak assumptions, missing market data, unrealistic projections, and inconsistencies across sections. Use before presenting to stakeholders or investors to stress-test the plan.',
     prompt: `You are in BUSINESS REVIEW MODE. Critically evaluate the business plan like an investor would.
 
 ## Step 1: Load and Assess

package/dist/skills/content-skills.js

@@ -6,7 +6,7 @@
 import { defineSkill } from '@compilr-dev/agents';
 export const brandSetupSkill = defineSkill({
     name: 'brand-setup',
-    description: 'Define brand identity, visual guidelines, voice, audience, and content strategy',
+    description: 'Define the complete brand identity — name, tagline, visual guidelines, voice and tone, target audience personas, and content pillars. Use when starting a new brand or formalizing an existing one. Produces a BrandModel stored in the project database.',
     prompt: `You are in BRAND SETUP MODE. Guide the user through building their Brand Model step by step.
 
 ## Step 1: Brand Identity
@@ -62,7 +62,7 @@ Run \`brand_model_validate\` to check completeness. Report gaps and ask if user
 });
 export const contentStrategySkill = defineSkill({
     name: 'content-strategy',
-    description: 'Define or refine content pillars and per-platform cadence',
+    description: 'Define or refine the content strategy — content pillars, platform-specific cadence, audience targeting per channel, and content mix ratios. Use after brand setup to plan what content to produce and where to publish it.',
     prompt: `You are in CONTENT STRATEGY MODE. Help the user plan their content approach.
 
 ## Step 1: Assess
@@ -86,7 +86,7 @@ Create initial content piece work items based on pillars and cadence.`,
 });
 export const contentCalendarSkill = defineSkill({
     name: 'content-calendar',
-    description: 'Generate content piece work items for a specific period',
+    description: 'Generate a content calendar — create backlog work items for content pieces across a specific time period. Use after the content strategy is defined. Assigns topics to dates, platforms, and content pillars based on the planned cadence.',
     prompt: `You are in CONTENT CALENDAR MODE. Plan content for a specific period.
 
 ## Step 1: Assess
@@ -111,7 +111,7 @@ Present the calendar as a table before creating work items.`,
 });
 export const createContentSkill = defineSkill({
     name: 'create-content',
-    description: 'Write copy and generate visual brief for a content piece',
+    description: 'Write the actual copy for a content piece and generate a visual brief for accompanying graphics. Use when a content calendar item is ready to produce. Follows brand voice guidelines and platform-specific formatting conventions.',
     prompt: `You are in CONTENT CREATION MODE. Create a complete content piece.
 
 ## Step 1: Read Context
@@ -148,7 +148,7 @@ Write everything as structured markdown in the work item description.
 });
 export const contentReviewSkill = defineSkill({
     name: 'content-review',
-    description: 'Review content for voice consistency, brand alignment, and platform conventions',
+    description: 'Review a content piece for voice consistency, brand alignment, platform conventions, and audience fit. Use before publishing to catch tone mismatches, off-brand messaging, or format issues. Produces actionable feedback with specific suggestions.',
     prompt: `You are in CONTENT REVIEW MODE. Review a content piece as the brand's quality gate.
 
 ## Step 1: Read References

package/dist/skills/course-skills.js

@@ -6,7 +6,7 @@
 import { defineSkill } from '@compilr-dev/agents';
 export const curriculumDesignSkill = defineSkill({
     name: 'curriculum-design',
-    description: 'Define course structure — modules, learning objectives, progression',
+    description: 'Define the course structure — target audience, difficulty level, modules, learning objectives, prerequisites, and progression path. Use when starting a new course or restructuring an existing one. Produces a CurriculumModel stored in the project database.',
     prompt: `You are in CURRICULUM DESIGN MODE. Help the user structure their course.
 
 ## Step 1: Course Overview
@@ -50,7 +50,7 @@ Run \`curriculum_model_validate\` to check completeness.
 });
 export const lessonPlanSkill = defineSkill({
     name: 'lesson-plan',
-    description: 'Break a module into detailed lessons with types and time estimates',
+    description: 'Break a module into detailed lessons — lesson types (theory, demo, hands-on, discussion), time estimates, learning objectives per lesson, and key concepts. Use after the curriculum structure exists to add lesson-level detail.',
     prompt: `You are in LESSON PLAN MODE. Break a module into detailed lessons.
 
 ## Step 1: Read Context
@@ -88,7 +88,7 @@ Save: \`curriculum_model_update\` op: "assessment_add"
 });
 export const assessmentDesignSkill = defineSkill({
     name: 'assessment-design',
-    description: 'Create quizzes, exercises, and projects for a module',
+    description: 'Create assessments for a module — quizzes, coding exercises, projects, and rubrics. Use after lessons are defined to add evaluation checkpoints. Aligns assessment types with learning objectives and difficulty level.',
     prompt: `You are in ASSESSMENT DESIGN MODE. Create assessments linked to learning objectives.
 
 ## Step 1: Read Context
@@ -120,7 +120,7 @@ Flag untested objectives.
 });
 export const courseReviewSkill = defineSkill({
     name: 'course-review',
-    description: 'Review course for pedagogical quality — balance, coverage, progression',
+    description: 'Review the entire course for pedagogical quality — lesson type balance (theory vs hands-on), learning objective coverage, difficulty progression, time estimates, and assessment alignment. Use before publishing to identify structural gaps.',
     prompt: `You are in COURSE REVIEW MODE. Evaluate the curriculum as a pedagogical expert.
 
 ## Step 1: Load

package/dist/skills/index.d.ts

@@ -6,4 +6,6 @@ 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 type { SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './operations.js';
+export { detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill, } from './operations.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,5 @@
 export { RESERVED_SKILL_NAMES, isReservedSkillName } from './types.js';
 export { parseSkillMarkdown, loadSkillsFromDir } from './loader.js';
 export { resolveLayeredSkills, resolveSkillsForAgent } from './resolver.js';
+export { detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill, } from './operations.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/operations.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Skill operations — reusable logic for CLI and Desktop.
+ *
+ * - Collision detection (user skills vs SDK reserved names)
+ * - Diff (fork vs upstream SDK version)
+ * - Fork scaffold (build SKILL.md with forkedFrom marker)
+ * - Validation (quality checks beyond parseSkillMarkdown)
+ * - Binding resolution (config.json slash command remapping)
+ */
+import type { CustomSkill, ForkedFromMarker } from './types.js';
+export interface SkillCollision {
+    /** The colliding skill name */
+    name: string;
+    /** Path to the user's skill folder */
+    userPath: string;
+    /** Scope where the user skill lives */
+    scope: 'user' | 'project';
+    /** SDK package that owns the reserved name */
+    sdkSource: string;
+}
+/**
+ * Detect user/project skills that shadow SDK reserved names.
+ * Called at startup to warn users about collisions introduced by SDK updates.
+ *
+ * Note: Phase 1 blocks creation of reserved names via `/skill new`, but
+ * collisions can still happen if the SDK adds new skills after the user
+ * already has a skill with that name.
+ */
+export declare function detectCollisions(userSkills: {
+    name: string;
+    scope: 'user' | 'project';
+    path: string;
+}[]): SkillCollision[];
+/**
+ * Format collision warnings for display.
+ */
+export declare function formatCollisionWarnings(collisions: SkillCollision[]): string;
+export interface SkillDiffLine {
+    type: 'same' | 'added' | 'removed';
+    content: string;
+}
+/**
+ * Compute a simple line-by-line diff between a forked skill and the
+ * upstream SDK skill it was forked from.
+ *
+ * Returns null if the upstream skill is not found.
+ */
+export declare function diffForkVsUpstream(forkPrompt: string, upstreamSkillName: string): SkillDiffLine[] | null;
+/**
+ * Build the SKILL.md content for a forked SDK skill.
+ */
+export declare function buildForkContent(sdkSkill: {
+    name: string;
+    description: string;
+    prompt: string;
+}, newName: string, sdkVersion: string): string;
+/**
+ * Build the SKILL.md template for a new custom skill.
+ */
+export declare function buildNewSkillContent(name: string, scope: string): string;
+export interface SkillValidationIssue {
+    level: 'error' | 'warning';
+    message: string;
+}
+/**
+ * Validate a parsed custom skill beyond basic frontmatter parsing.
+ */
+export declare function validateSkill(skill: CustomSkill, folderName: string): SkillValidationIssue[];
+export interface ScopeConfig {
+    slashCommands?: Record<string, string>;
+}
+export interface SkillResolution {
+    /** The resolved skill prompt */
+    prompt: string;
+    /** Original command name the user typed */
+    commandName: string;
+    /** Actual skill name that provided the prompt (may differ if bound) */
+    skillName: string;
+    /** Whether this was resolved via a binding */
+    isBound: boolean;
+    /** Fork info if the skill is forked */
+    forkedFrom?: ForkedFromMarker;
+    /** Source layer */
+    source?: CustomSkill['source'];
+}

package/dist/skills/operations.js

@@ -0,0 +1,210 @@
+/**
+ * Skill operations — reusable logic for CLI and Desktop.
+ *
+ * - Collision detection (user skills vs SDK reserved names)
+ * - Diff (fork vs upstream SDK version)
+ * - Fork scaffold (build SKILL.md with forkedFrom marker)
+ * - Validation (quality checks beyond parseSkillMarkdown)
+ * - Binding resolution (config.json slash command remapping)
+ */
+import { RESERVED_SKILL_NAMES } from './types.js';
+import { platformSkills } from './platform-skills.js';
+/**
+ * Detect user/project skills that shadow SDK reserved names.
+ * Called at startup to warn users about collisions introduced by SDK updates.
+ *
+ * Note: Phase 1 blocks creation of reserved names via `/skill new`, but
+ * collisions can still happen if the SDK adds new skills after the user
+ * already has a skill with that name.
+ */
+export function detectCollisions(userSkills) {
+    const reserved = new Set(RESERVED_SKILL_NAMES);
+    const collisions = [];
+    for (const skill of userSkills) {
+        if (reserved.has(skill.name)) {
+            collisions.push({
+                name: skill.name,
+                userPath: skill.path,
+                scope: skill.scope,
+                sdkSource: '@compilr-dev/sdk',
+            });
+        }
+    }
+    return collisions;
+}
+/**
+ * Format collision warnings for display.
+ */
+export function formatCollisionWarnings(collisions) {
+    if (collisions.length === 0)
+        return '';
+    const lines = [`⚠️  SDK update introduced new skills that collide with yours:`];
+    for (const c of collisions) {
+        lines.push(`    '${c.name}'  — your version: ${c.userPath}  (${c.scope} scope)`, `              SDK version: ${c.sdkSource}`);
+    }
+    lines.push('', '   Run /skill to view details.', '   Options: rename your skill, delete it, or fork the SDK version.');
+    return lines.join('\n');
+}
+/**
+ * Compute a simple line-by-line diff between a forked skill and the
+ * upstream SDK skill it was forked from.
+ *
+ * Returns null if the upstream skill is not found.
+ */
+export function diffForkVsUpstream(forkPrompt, upstreamSkillName) {
+    // Find the upstream SDK skill
+    // Check all platform skills + builtins
+    const allSdk = [...platformSkills];
+    const upstream = allSdk.find((s) => s.name === upstreamSkillName);
+    if (!upstream)
+        return null;
+    const upstreamLines = upstream.prompt.split('\n');
+    const forkLines = forkPrompt.split('\n');
+    return computeLineDiff(upstreamLines, forkLines);
+}
+/**
+ * Simple line diff (not a full Myers diff — sufficient for skill comparison).
+ * Uses longest common subsequence for reasonable output.
+ */
+function computeLineDiff(oldLines, newLines) {
+    const result = [];
+    let oi = 0;
+    let ni = 0;
+    while (oi < oldLines.length && ni < newLines.length) {
+        if (oldLines[oi] === newLines[ni]) {
+            result.push({ type: 'same', content: oldLines[oi] });
+            oi++;
+            ni++;
+        }
+        else {
+            // Look ahead for the next matching line
+            const matchInNew = newLines.indexOf(oldLines[oi], ni);
+            const matchInOld = oldLines.indexOf(newLines[ni], oi);
+            if (matchInNew >= 0 && (matchInOld < 0 || matchInNew - ni <= matchInOld - oi)) {
+                // Lines added in new
+                while (ni < matchInNew) {
+                    result.push({ type: 'added', content: newLines[ni] });
+                    ni++;
+                }
+            }
+            else if (matchInOld >= 0) {
+                // Lines removed from old
+                while (oi < matchInOld) {
+                    result.push({ type: 'removed', content: oldLines[oi] });
+                    oi++;
+                }
+            }
+            else {
+                // No match found — treat as replace
+                result.push({ type: 'removed', content: oldLines[oi] });
+                result.push({ type: 'added', content: newLines[ni] });
+                oi++;
+                ni++;
+            }
+        }
+    }
+    // Remaining old lines
+    while (oi < oldLines.length) {
+        result.push({ type: 'removed', content: oldLines[oi] });
+        oi++;
+    }
+    // Remaining new lines
+    while (ni < newLines.length) {
+        result.push({ type: 'added', content: newLines[ni] });
+        ni++;
+    }
+    return result;
+}
+// =============================================================================
+// Fork Scaffold
+// =============================================================================
+/**
+ * Build the SKILL.md content for a forked SDK skill.
+ */
+export function buildForkContent(sdkSkill, newName, sdkVersion) {
+    const forkedFrom = {
+        source: '@compilr-dev/sdk',
+        skill: sdkSkill.name,
+        version: sdkVersion,
+        forkedAt: new Date().toISOString(),
+    };
+    const descLines = sdkSkill.description
+        .split('\n')
+        .map((l) => `  ${l}`)
+        .join('\n');
+    const fmLines = [
+        `name: ${newName}`,
+        'description: |',
+        descLines,
+        'version: 0.1.0',
+        'forkedFrom:',
+        `  source: "${forkedFrom.source}"`,
+        `  skill: "${forkedFrom.skill}"`,
+        `  version: "${forkedFrom.version}"`,
+        `  forkedAt: "${forkedFrom.forkedAt}"`,
+    ];
+    return ['---', ...fmLines, '---', '', sdkSkill.prompt].join('\n');
+}
+// =============================================================================
+// New Skill Scaffold
+// =============================================================================
+/**
+ * Build the SKILL.md template for a new custom skill.
+ */
+export function buildNewSkillContent(name, scope) {
+    return `---
+name: ${name}
+description: |
+  Use this skill when … (replace with a paragraph-long description that names
+  the trigger conditions, the kinds of phrases the user will say, and the
+  expected output. Anthropic-style descriptions are keyword-dense and
+  intent-rich because the model reads them to decide when to load the skill.)
+version: 0.1.0
+
+# Optional — compilr extensions (ignored by Anthropic-compatible runtimes).
+# Uncomment and edit to limit which agents and project types this skill applies to.
+# compilr:
+#   targets:
+#     roles: [arch, qa]
+#   requires:
+#     tools: []
+#     projectTypes: []
+#   scope: ${scope}
+---
+
+# ${name}
+
+(Body markdown — the prompt the agent will receive when this skill activates.)
+
+## Step 1
+Describe the first step.
+
+## Step 2
+…
+`;
+}
+/**
+ * Validate a parsed custom skill beyond basic frontmatter parsing.
+ */
+export function validateSkill(skill, folderName) {
+    const issues = [];
+    if (skill.name !== folderName) {
+        issues.push({
+            level: 'error',
+            message: `Frontmatter name '${skill.name}' doesn't match folder '${folderName}'.`,
+        });
+    }
+    if (skill.description.length < 60) {
+        issues.push({
+            level: 'warning',
+            message: `Description is ${String(skill.description.length)} chars (recommend 60+).`,
+        });
+    }
+    if (!skill.prompt || skill.prompt.trim().length === 0) {
+        issues.push({
+            level: 'warning',
+            message: 'Body is empty.',
+        });
+    }
+    return issues;
+}

package/dist/skills/research-skills.js

@@ -6,7 +6,7 @@
 import { defineSkill } from '@compilr-dev/agents';
 export const outlineSkill = defineSkill({
     name: 'outline',
-    description: 'Build or refine the research paper structure — sections, claims, source mapping',
+    description: 'Build or refine the research paper structure — define sections, formulate claims with evidence requirements, and map sources to claims. Use when starting a new paper or restructuring an existing one. Produces a ResearchModel outline stored in the project database.',
     prompt: `You are in OUTLINE MODE. Your goal is to help the user build or refine a structured outline for their research paper using the Research Model.
 
 ## When to Use
@@ -150,7 +150,7 @@ Create one work item per section:
 });
 export const literatureReviewSkill = defineSkill({
     name: 'literature-review',
-    description: 'Analyze sources from the Knowledge Base — extract findings, link to claims, identify gaps',
+    description: 'Systematically analyze sources from the Knowledge Base — extract key findings, link evidence to claims in the outline, assess source quality, and identify coverage gaps. Use after the outline exists and sources have been added to the Knowledge Base.',
     prompt: `You are in LITERATURE REVIEW MODE. Your goal is to systematically analyze the sources in the Knowledge Base and connect them to the Research Model's sections and claims.
 
 ## When to Use
@@ -254,7 +254,7 @@ If multiple sources have been analyzed, provide a thematic synthesis:
 });
 export const draftSectionSkill = defineSkill({
     name: 'draft-section',
-    description: 'Draft a paper section using the outline, claims, and linked sources',
+    description: 'Draft a specific paper section using the outline structure, claims, and linked sources. Use when the outline and literature review are complete for the target section. Produces academic prose with inline citations following the selected citation style.',
     prompt: `You are in DRAFT SECTION MODE. Your goal is to write or revise a section of the research paper, guided by the Research Model's outline, claims, and linked sources.
 
 ## When to Use
@@ -366,7 +366,7 @@ Report to the user:
 });
 export const peerReviewSkill = defineSkill({
     name: 'peer-review',
-    description: 'Validate argument structure, find logical gaps, check consistency across sections',
+    description: 'Peer review the research paper — validate argument structure, find logical gaps, check claim-evidence consistency, assess citation coverage, and verify cross-section coherence. Use before submission to identify weaknesses. Produces a structured review report with actionable issues.',
     prompt: `You are in PEER REVIEW MODE. Your goal is to critically evaluate the research paper's argument structure, identify gaps, and check consistency — like an academic peer reviewer.
 
 ## When to Use
@@ -515,7 +515,7 @@ For issues that affect the Research Model:
 });
 export const researchScaffoldSkill = defineSkill({
     name: 'research-scaffold',
-    description: 'Scaffold a research paper project from a template (APA, IEEE, Thesis, Literature Review, Lab Report)',
+    description: 'Scaffold a new research paper project from a template — APA journal article, IEEE conference paper, thesis/dissertation, literature review, or lab report. Use when starting a fresh research project. Creates the ResearchModel with template-appropriate sections, citation style, and document structure.',
     prompt: `You are in RESEARCH SCAFFOLD MODE. Your goal is to help the user set up a new research paper project using a template.
 
 ## Available Templates

package/dist/skills/software-skills.js

@@ -9,7 +9,7 @@ import { defineSkill } from '@compilr-dev/agents';
 // =============================================================================
 export const designSkill = defineSkill({
     name: 'design',
-    description: 'Guide user through project design and requirements gathering',
+    description: 'Interactive requirements gathering session that produces 5-15 actionable backlog items. Use when starting a new project from scratch or when the user has an idea but no clear requirements. Asks structured questions about goals, users, features, and constraints.',
     prompt: `You are in DESIGN MODE. Your goal is to gather enough information to populate the project backlog with 5-15 actionable items.
 
 ## When to Use
@@ -90,7 +90,7 @@ When you have enough information:
 });
 export const refineSkill = defineSkill({
     name: 'refine',
-    description: 'Iteratively refine and expand project requirements',
+    description: 'Iteratively refine and expand existing project requirements. Use when the project already has an initial design or backlog but needs deeper detail, edge cases, or new features explored. Walks through each area asking targeted follow-up questions.',
     prompt: `You are in REFINE MODE. Your goal is to deepen and expand existing requirements based on user feedback.
 
 ## When to Use
@@ -168,7 +168,7 @@ For complex features:
 });
 export const sketchSkill = defineSkill({
     name: 'sketch',
-    description: 'Quick project outline with simple questions',
+    description: 'Quick lightweight project outline using a few simple questions. Use for rapid brainstorming or when the user wants a fast first pass before committing to a full design session. Produces a high-level summary, not detailed backlog items.',
     prompt: `You are in SKETCH MODE. Ask 6 quick questions, then create backlog items.
 
 ## When to Use
@@ -207,7 +207,7 @@ RULES:
 });
 export const refineItemSkill = defineSkill({
     name: 'refine-item',
-    description: 'Focused refinement of a specific backlog item',
+    description: 'Deep-dive refinement of a single backlog work item. Use when an item needs more detail — acceptance criteria, implementation notes, subtask breakdown, or dependency analysis. Reads the item from the database and produces an updated version.',
     prompt: `You are in FOCUSED REFINE MODE. Your goal is to refine a specific backlog item.
 
 ## When to Use
@@ -275,7 +275,7 @@ Based on user's choice:
 });
 export const architectureSkill = defineSkill({
     name: 'architecture',
-    description: 'Create architecture documentation (ADRs, diagrams, data models, API designs)',
+    description: 'Create or update architecture documentation including ADRs, system diagrams, data models, and API designs. Use after requirements are defined. Reads the current backlog and project documents to produce architecture artifacts stored as project documents.',
     prompt: `You are in ARCHITECTURE MODE. Your goal is to create architecture documentation.
 
 ## When to Use
@@ -420,7 +420,7 @@ Generate appropriate documentation.
 });
 export const prdSkill = defineSkill({
     name: 'prd',
-    description: 'Amend or enhance the Product Requirements Document',
+    description: 'Create, amend, or enhance the Product Requirements Document. Use when formalizing requirements into a structured PRD with sections for overview, user personas, functional requirements, non-functional requirements, and success metrics. Stored as a project document.',
     prompt: `You are in PRD MODE. Your goal is to update or enhance the existing Product Requirements Document.
 
 ## When to Use
@@ -502,7 +502,7 @@ Based on section selected:
 });
 export const sessionNotesSkill = defineSkill({
     name: 'session-notes',
-    description: 'Create structured session notes capturing work done and decisions made',
+    description: 'Create structured session notes capturing work done, decisions made, and open questions. Use at the end of a work session to document progress. Reviews conversation history and produces a formatted summary stored as a project document.',
     prompt: `You are in SESSION NOTES MODE. Your goal is to create a structured summary of the current session.
 
 ## When to Use
@@ -597,7 +597,7 @@ Create the directory if it doesn't exist.
 });
 export const buildSkill = defineSkill({
     name: 'build',
-    description: 'Implement a backlog item end-to-end',
+    description: 'Implement a backlog work item end-to-end — read requirements, write code, run tests, and update the item status. Use when an item is ready to build. Follows a structured workflow: understand → plan → implement → verify → mark complete.',
     tags: ['implementation', 'coding'],
     prompt: `You are in BUILD MODE. Implement the specified backlog item.
 
@@ -694,7 +694,7 @@ Before implementing, read these files for context:
 });
 export const scaffoldSkill = defineSkill({
     name: 'scaffold',
-    description: 'Create project foundation based on tech stack',
+    description: 'Generate a complete project scaffold from the Application Model or tech stack selection. Use after the design phase to create the initial codebase — directory structure, configuration, boilerplate, and starter components. Supports multiple toolkits (React+Node, Next+Prisma, FastAPI, Go, static landing).',
     tags: ['setup', 'foundation', 'scaffolding'],
     prompt: `You are creating the PROJECT SCAFFOLD (foundation).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",