@compilr-dev/sdk 0.27.0 → 0.29.0

package/dist/guide/shared-content.js

@@ -115,20 +115,53 @@ The delegated agent runs independently and returns results to the coordinator.`,
     },
     // ── Skills ──────────────────────────────────────────────────────────────
     {
-        id: 'skills-overview',
-        title: 'Skills Overview',
-        keywords: ['skills', 'slash', 'command', '/'],
-        content: `Skills are pre-built prompts that guide the agent through specific workflows.
+        id: 'macros-overview',
+        title: 'Macros Overview',
+        keywords: ['macros', 'macro', 'skills', 'slash', 'command', '/'],
+        content: `Macros are pre-built prompts that guide the agent through specific workflows. You
+invoke one; it expands into a message.
 
-Use them by typing / followed by the skill name (e.g., /design, /build).
+Use them by typing / followed by the macro name (e.g., /design, /build).
 
-Skills vary by project type. Software projects have: /design, /sketch, /prd, /architecture, /scaffold, /build, /refine, /session-notes.
+Macros vary by project type. Software projects have: /design, /sketch, /prd, /architecture, /scaffold, /build, /refine, /session-notes.
 
 Research projects have: /research-scaffold, /outline, /literature-review, /draft-section, /peer-review.
 
 Business projects have: /business-vision, /market-analysis, /competitor-analysis, /financial-model, /pitch-outline, /business-review.
 
-Skills can be combined with your own instructions: type /design then add context.`,
+Macros can be combined with your own instructions: type /design then add context.
+
+**Macros are not Skills.** A macro is text YOU trigger. A Skill is a capability the MODEL
+chooses from a catalogue and loads when it decides it is relevant — see "Skills". They were
+called the same thing until recently, which is why older notes use "skill" for both.`,
+    },
+    {
+        id: 'skills',
+        title: 'Skills — Capabilities the Model Chooses',
+        keywords: ['skill', 'skills', 'SKILL.md', 'anthropic', 'agent skills', 'catalogue', 'grant'],
+        content: `A Skill is a capability the MODEL picks up when it decides the work calls for it —
+not something you type.
+
+Each agent is shown a CATALOGUE: one line per skill, name and description only. When the agent
+judges a skill relevant it loads the body then, and not before, so an unused skill costs a line
+of context rather than a document.
+
+**Where they live**
+- User scope: ~/.compilr-dev/skills/<name>/SKILL.md — personal, every project
+- Project scope: <project>/.compilr/skills/<name>/SKILL.md — shared via version control
+
+The format is Anthropic's Agent Skills format: YAML frontmatter (name, description) and a
+markdown body. We read the frontmatter and the body; bundled references/, scripts/, templates/
+and assets/ are not read yet.
+
+**Granting them per agent**
+In the agent editor's Skills section, tick the skills an agent may choose from. An agent you have
+never restricted may choose any installed skill; once you save a selection it is limited to
+exactly what is ticked, and an empty selection grants none.
+
+**Skills are not macros.** A macro (/design, /build) is text YOU trigger. A skill is something
+the model reaches for on its own. A skill you install is also typeable as a slash command, so one
+folder can serve both purposes — see "Custom Skills".`,
     },
     {
         id: 'custom-skills',
@@ -157,8 +190,8 @@ A folder with a SKILL.md file containing YAML frontmatter (name, description) an
 
 **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.
+**Forking shipped macros:**
+You cannot override a shipped macro directly — its name is reserved, so creating one is refused. Fork it instead: that copies it, and you edit the copy. Then bind a slash command to your fork (e.g., /design → design-acme).
 
 **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.

package/dist/index.d.ts

@@ -73,6 +73,12 @@ export type { SkillScope, SkillPromptResolution, AvailableSkillEntry, SkillSourc
 export { resolveSkillPrompt, getAllAvailableSkills } from './skills/index.js';
 export { buildMacroList } from './skills/index.js';
 export { buildMacroInvocation } from './skills/index.js';
+export { skillReachability, isUnreachable } from './skills/index.js';
+export { patchSkillFrontmatter } from './skills/index.js';
+export { readSkillFolder, unreadSkillFiles } from './skills/index.js';
+export type { SkillFolderEntry } from './skills/index.js';
+export type { FrontmatterPatch } from './skills/index.js';
+export type { SkillReachability } from './skills/index.js';
 export type { MacroInvocation, MacroInvocationContext, MacroProjectContext, } from './skills/index.js';
 export type { MacroListEntry, BuildMacroListOptions } from './skills/index.js';
 export { generateSkillCatalog, toCatalogEntry, createLoadSkillTool } from './skills/index.js';

package/dist/index.js

@@ -156,6 +156,9 @@ export { RESERVED_MACRO_NAMES, isReservedMacroName, parseSkillMarkdown, loadSkil
 export { resolveSkillPrompt, getAllAvailableSkills } from './skills/index.js';
 export { buildMacroList } from './skills/index.js';
 export { buildMacroInvocation } from './skills/index.js';
+export { skillReachability, isUnreachable } from './skills/index.js';
+export { patchSkillFrontmatter } from './skills/index.js';
+export { readSkillFolder, unreadSkillFiles } from './skills/index.js';
 export { generateSkillCatalog, toCatalogEntry, createLoadSkillTool } from './skills/index.js';
 export { platformMacros, designMacro, sketchMacro, prdMacro, refineMacro, refineItemMacro, architectureMacro, sessionNotesMacro, buildMacro, scaffoldMacro, outlineMacro, literatureReviewMacro, draftSectionMacro, peerReviewMacro, researchScaffoldMacro, businessVisionMacro, marketAnalysisMacro, competitorAnalysisMacro, financialModelMacro, pitchOutlineMacro, businessReviewMacro, brandSetupMacro, contentStrategyMacro, contentCalendarMacro, createContentMacro, contentReviewMacro, curriculumDesignMacro, lessonPlanMacro, assessmentDesignMacro, courseReviewMacro, bookOutlineMacro, characterDesignMacro, plotThreadsMacro, sceneBreakdownMacro, bookReviewMacro, } from './skills/index.js';
 // =============================================================================

package/dist/skills/canvas-macros.js

@@ -31,7 +31,7 @@ export const canvasMacro = defineSkill({
 - **carousel** — multiple slide "sheets"; author each slide as a top-level \`<section data-sheet>…</section>\`.
 - **board** — an infinite 2D coordinate space of absolutely-positioned node cards + inline-SVG connectors (mind-map / diagram / UI sketch). Wrap in \`<div data-board style="position:relative;width:Wpx;height:Hpx">\`.
 
-**Once you've picked the type, consult its craft guide for the design rules that make it good** — the \`infographic\` skill (hierarchy, grid, stat tiles, restrained color, correct charts), the \`carousel\` skill (one idea per slide, narrative arc, consistent master layout, 16:9 discipline), or the \`board\` skill (declared coordinate space, absolutely-positioned node cards, inline-SVG connectors, clustering). This general skill covers the mechanics (tools, structure, theme, Tweaks); the per-type skill covers the craft.
+**Once you've picked the type, consult its craft guide for the design rules that make it good** — the \`infographic\` macro (hierarchy, grid, stat tiles, restrained color, correct charts), the \`carousel\` macro (one idea per slide, narrative arc, consistent master layout, 16:9 discipline), or the \`board\` macro (declared coordinate space, absolutely-positioned node cards, inline-SVG connectors, clustering). This general macro covers the mechanics (tools, structure, theme, Tweaks); the per-type macro covers the craft.
 
 ## STEPS
 
@@ -89,7 +89,7 @@ stored and what the markup actually uses.
    - Do NOT include \`<html>\`, \`<head>\`, \`<meta>\`, \`<!doctype>\`, or your own CSP — the host injects the sandbox and CSP. Just the body content + a \`<style>\` and optional \`<script>\`.
    - The sandbox is \`allow-scripts\` with NO same-origin and CSP \`default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:\`. So: inline \`<style>\`/\`<script>\` only, no external fonts/CSS/JS/network, no remote images (use inline SVG or data: URIs).
    - **Match the app theme by default.** The host injects its live theme palette as CSS variables you MUST use instead of hardcoded colors: \`var(--canvas-bg)\` (page background), \`var(--canvas-fg)\` (text), \`var(--canvas-accent)\` and \`var(--canvas-secondary)\` (highlights), \`var(--canvas-muted)\` (secondary text), \`var(--canvas-border)\` (lines), \`var(--canvas-card)\` (raised surfaces). Only hardcode specific colors when the user explicitly asks for a particular palette or brand.
-   - **Background — infographic & carousel: always set it EXPLICITLY to \`var(--canvas-bg)\`** on your outermost wrapper (and each \`<section data-sheet>\` for a carousel). Do NOT use \`background: transparent\` and do NOT hardcode a fixed color like \`#0a0a0a\`: transparent looks fine in-app but **exports to PDF/HTML on WHITE**, and a fixed color ignores the theme. **EXCEPTION — infinite board: do the OPPOSITE.** Keep the \`data-board\` root **transparent** (do not fill it) — the host paints a dot-grid backdrop that must show through, and filling it turns the infinite surface into a finite rectangle. On a board you style only the node cards; the space between them stays transparent. (See the \`board\` skill.)
+   - **Background — infographic & carousel: always set it EXPLICITLY to \`var(--canvas-bg)\`** on your outermost wrapper (and each \`<section data-sheet>\` for a carousel). Do NOT use \`background: transparent\` and do NOT hardcode a fixed color like \`#0a0a0a\`: transparent looks fine in-app but **exports to PDF/HTML on WHITE**, and a fixed color ignores the theme. **EXCEPTION — infinite board: do the OPPOSITE.** Keep the \`data-board\` root **transparent** (do not fill it) — the host paints a dot-grid backdrop that must show through, and filling it turns the infinite surface into a finite rectangle. On a board you style only the node cards; the space between them stays transparent. (See the \`board\` macro.)
    - Make it look intentional: a clear grid, strong type scale, generous spacing. Use \`var(--canvas-accent)\` sparingly for emphasis. Prefer inline SVG for shapes/charts/icons (fill/stroke with the theme vars).
    - For a **carousel**, wrap each slide in \`<section data-sheet>…</section>\` — a natural unit to add one per \`canvas_edit\` append.
 
@@ -201,7 +201,7 @@ export const infographicMacro = defineSkill({
 - Inline **SVG**, filled/stroked with the theme vars, a consistent stroke width. No emoji as primary iconography.
 
 ## Before you finish
-- Set the background explicitly to \`var(--canvas-bg)\` (see the canvas skill's export note).
+- Set the background explicitly to \`var(--canvas-bg)\` (see the canvas macro's export note).
 - Add 2–4 **bound** Tweaks (accent color, headline size, a section toggle) — declared AND referenced in the HTML.
 
 ## Anti-patterns (fix on sight)
@@ -242,7 +242,7 @@ Structure the sequence like a story, not a list:
 - The same card/grid system reused slide to slide.
 
 ## Before you finish
-- Set \`background: var(--canvas-bg)\` on EACH \`<section data-sheet>\` (see the canvas skill's export note — transparent slides export white).
+- Set \`background: var(--canvas-bg)\` on EACH \`<section data-sheet>\` (see the canvas macro's export note — transparent slides export white).
 - Add 2–4 **bound** Tweaks (accent color, title size, a toggle for footer/page numbers).
 
 ## Anti-patterns (fix on sight)
@@ -335,7 +335,7 @@ export const canvasStylesMacro = defineSkill({
     prompt: `The STYLE CATALOGUE for canvases — pick a coherent visual aesthetic instead of defaulting to the flat theme look. Design guidance; author with the canvas tools (see the \`canvas\` skill for mechanics). Applies to **infographic** and **carousel** (a board is a diagram surface — keep it theme-flat unless asked).
 
 ## How to use it
-- **Offer during the brief, don't over-ask.** In the canvas skill's Step 1, if the user hasn't named a style, include a SHORT aesthetic menu (2–4 fitting options from below) in the SAME \`propose_alternatives\`/\`ask_user\` round — never a separate interview. If they said "surprise me / your call", just pick the one that best fits the content and build.
+- **Offer during the brief, don't over-ask.** In the canvas macro's Step 1, if the user hasn't named a style, include a SHORT aesthetic menu (2–4 fitting options from below) in the SAME \`propose_alternatives\`/\`ask_user\` round — never a separate interview. If they said "surprise me / your call", just pick the one that best fits the content and build.
 - **A style is a SYSTEM, not a trick.** Surfaces, borders, shadows, type, spacing, and accent all move together. Apply the whole recipe — half a recipe reads as a mistake.
 
 ## Hard constraints (every style — the sandbox is strict)

package/dist/skills/folder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * What else is in a skill's folder — and what we do not read.
+ *
+ * ⚠️ A SKILL IS A FOLDER, NOT A FILE, AND WE ONLY READ ONE FILE OF IT. Of 50 Anthropic-authored
+ * skills, 16 ship `references/` and 11 ship `scripts/`. That is progressive disclosure: the body
+ * stays short precisely because it points at those files, loaded only when the model needs them.
+ *
+ * We read frontmatter and body. Nothing else. So an installed third-party skill half-works and
+ * says nothing about it — the author's instructions reference material that never arrives.
+ *
+ * Listing them is the interim fix; reading them is the real one. Surfacing the gap is the point of
+ * this module: a host can say "points at 3 files we do not load" instead of leaving the user to
+ * discover it from a confused agent.
+ */
+export interface SkillFolderEntry {
+    /** Path relative to the skill folder, e.g. `references/api.md`. */
+    path: string;
+    /** Which convention it belongs to. */
+    kind: 'reference' | 'script' | 'asset' | 'template' | 'other';
+    bytes: number;
+}
+/**
+ * Everything in the skill folder besides SKILL.md.
+ *
+ * Returns [] when the folder is unreadable or holds only SKILL.md — an absent folder is the normal
+ * case for a skill someone just created, not an error.
+ */
+export declare function readSkillFolder(skillDir: string): SkillFolderEntry[];
+/**
+ * The entries a host should warn about: material the skill's own body points at and we never load.
+ *
+ * `LICENSE.txt` and the like are not this — they are not instructions the agent was meant to read.
+ */
+export declare function unreadSkillFiles(entries: SkillFolderEntry[]): SkillFolderEntry[];

package/dist/skills/folder.js

@@ -0,0 +1,70 @@
+/**
+ * What else is in a skill's folder — and what we do not read.
+ *
+ * ⚠️ A SKILL IS A FOLDER, NOT A FILE, AND WE ONLY READ ONE FILE OF IT. Of 50 Anthropic-authored
+ * skills, 16 ship `references/` and 11 ship `scripts/`. That is progressive disclosure: the body
+ * stays short precisely because it points at those files, loaded only when the model needs them.
+ *
+ * We read frontmatter and body. Nothing else. So an installed third-party skill half-works and
+ * says nothing about it — the author's instructions reference material that never arrives.
+ *
+ * Listing them is the interim fix; reading them is the real one. Surfacing the gap is the point of
+ * this module: a host can say "points at 3 files we do not load" instead of leaving the user to
+ * discover it from a confused agent.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const KIND_BY_DIR = {
+    references: 'reference',
+    scripts: 'script',
+    assets: 'asset',
+    templates: 'template',
+};
+/**
+ * Everything in the skill folder besides SKILL.md.
+ *
+ * Returns [] when the folder is unreadable or holds only SKILL.md — an absent folder is the normal
+ * case for a skill someone just created, not an error.
+ */
+export function readSkillFolder(skillDir) {
+    const out = [];
+    const walk = (dir, prefix, kind) => {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const full = join(dir, name);
+            const rel = prefix ? `${prefix}/${name}` : name;
+            try {
+                const st = statSync(full);
+                if (st.isDirectory()) {
+                    walk(full, rel, KIND_BY_DIR[name] ?? kind);
+                }
+                else if (rel !== 'SKILL.md') {
+                    out.push({
+                        path: rel,
+                        kind: prefix ? kind : (KIND_BY_DIR[name] ?? 'other'),
+                        bytes: st.size,
+                    });
+                }
+            }
+            catch {
+                // a file that vanished between readdir and stat is not worth failing a listing for
+            }
+        }
+    };
+    walk(skillDir, '', 'other');
+    return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+/**
+ * The entries a host should warn about: material the skill's own body points at and we never load.
+ *
+ * `LICENSE.txt` and the like are not this — they are not instructions the agent was meant to read.
+ */
+export function unreadSkillFiles(entries) {
+    return entries.filter((e) => e.kind === 'reference' || e.kind === 'script' || e.kind === 'template');
+}

package/dist/skills/index.d.ts

@@ -21,3 +21,9 @@ export { buildMacroList } from './macro-list.js';
 export type { MacroListEntry, BuildMacroListOptions } from './macro-list.js';
 export { buildMacroInvocation } from './macro-invocation.js';
 export type { MacroInvocation, MacroInvocationContext, MacroProjectContext, } from './macro-invocation.js';
+export { skillReachability, isUnreachable } from './reachability.js';
+export type { SkillReachability } from './reachability.js';
+export { patchSkillFrontmatter } from './patch.js';
+export type { FrontmatterPatch } from './patch.js';
+export { readSkillFolder, unreadSkillFiles } from './folder.js';
+export type { SkillFolderEntry } from './folder.js';

package/dist/skills/index.js

@@ -9,3 +9,6 @@ export { resolveSkillPrompt, getAllAvailableSkills } from './prompt-resolver.js'
 export { platformMacros, designMacro, sketchMacro, prdMacro, refineMacro, refineItemMacro, architectureMacro, sessionNotesMacro, buildMacro, scaffoldMacro, outlineMacro, literatureReviewMacro, draftSectionMacro, peerReviewMacro, researchScaffoldMacro, businessVisionMacro, marketAnalysisMacro, competitorAnalysisMacro, financialModelMacro, pitchOutlineMacro, businessReviewMacro, brandSetupMacro, contentStrategyMacro, contentCalendarMacro, createContentMacro, contentReviewMacro, curriculumDesignMacro, lessonPlanMacro, assessmentDesignMacro, courseReviewMacro, bookOutlineMacro, characterDesignMacro, plotThreadsMacro, sceneBreakdownMacro, bookReviewMacro, } from './platform-macros.js';
 export { buildMacroList } from './macro-list.js';
 export { buildMacroInvocation } from './macro-invocation.js';
+export { skillReachability, isUnreachable } from './reachability.js';
+export { patchSkillFrontmatter } from './patch.js';
+export { readSkillFolder, unreadSkillFiles } from './folder.js';

package/dist/skills/loader.js

@@ -31,9 +31,19 @@ export function parseSkillMarkdown(content, sourcePath, source) {
     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)
+    if (!name)
         return null;
+    /*
+      ⚠️ AN EMPTY DESCRIPTION PARSES. It used to return null, which meant a skill with no description
+      was not "incomplete" — it was INVISIBLE, absent from every list with nothing to explain why.
+      Since the template now ships `description: ''` deliberately (never pre-fill a field that would
+      be valid if saved), refusing to parse it would hide every newly created skill.
+  
+      So it loads, and shows as `not set`. What it must NOT do is reach the model: a catalogue entry
+      with nothing to match on is worse than no entry at all — see generateSkillCatalog and
+      resolveSkillsForAgent, which both drop it.
+    */
+    const description = typeof meta['description'] === 'string' ? meta['description'] : '';
     const skill = {
         name,
         description,
@@ -49,6 +59,34 @@ export function parseSkillMarkdown(content, sourcePath, source) {
         skill.tags = meta['tags'].filter((t) => typeof t === 'string');
     if (typeof meta['enabled'] === 'boolean')
         skill.enabled = meta['enabled'];
+    /*
+      The Anthropic invocation fields. Hyphenated on disk, camelCase in the type — the file format is
+      theirs and we do not get to rename it, so the mapping lives here and nowhere else.
+    */
+    if (typeof meta['disable-model-invocation'] === 'boolean') {
+        skill.disableModelInvocation = meta['disable-model-invocation'];
+    }
+    if (typeof meta['user-invocable'] === 'boolean')
+        skill.userInvocable = meta['user-invocable'];
+    if (typeof meta['argument-hint'] === 'string')
+        skill.argumentHint = meta['argument-hint'];
+    if (Array.isArray(meta['allowed-tools'])) {
+        skill.allowedTools = meta['allowed-tools'].filter((t) => typeof t === 'string');
+    }
+    else if (typeof meta['allowed-tools'] === 'string') {
+        // Seen both ways in the wild: `allowed-tools: [Read, Grep]` and a bare comma string.
+        skill.allowedTools = meta['allowed-tools']
+            .split(',')
+            .map((t) => t.trim())
+            .filter(Boolean);
+    }
+    /*
+      ⚠️ EVERY KEY, INCLUDING THE ONES WE DO NOT MODEL. A host shows `compatibility` and friends from
+      this. It is NOT a write path: regenerating frontmatter from parsed YAML destroys comments —
+      measured on our own template, 17 lines became 7 and all 9 comment lines vanished. Writes patch
+      the original text instead. Decision D-2.
+    */
+    skill.rawFrontmatter = meta;
     if (meta['compilr'] && typeof meta['compilr'] === 'object') {
         skill.compilr = meta['compilr'];
     }

package/dist/skills/macro-invocation.d.ts

@@ -1,44 +1,78 @@
 /**
  * What a host actually SENDS when a user invokes a macro.
  *
- * ⚠️ THE TWO HOSTS SENT DIFFERENT THINGS FOR THE SAME COMMAND. `/design` in the CLI wrapped the
- * macro's prompt in ~20 lines of project context — do not scan the filesystem, the cwd is not the
- * project, save work items with `workitem_add` and documents with `project_document_add` rather
- * than writing files — while Desktop sent the prompt alone. Same name, same macro, materially
- * different instructions, so the same request produced an agent that interviewed you and filled
- * the backlog in one host and an agent that went looking for source files in the other.
+ * ⚠️ THE TWO HOSTS SENT DIFFERENT THINGS FOR THE SAME COMMAND. The CLI wrapped each of these
+ * macros in project context — do not scan the filesystem, the cwd is not the project, save work
+ * items with `workitem_add` and documents with `project_document_add` rather than writing files —
+ * while Desktop sent the prompt alone. Same names, same macros, materially different
+ * instructions, so the same request produced an agent that interviewed you and filled the backlog
+ * in one host and an agent that went looking for source files in the other.
  *
- * The prompt is shared data; what surrounds it was not. It is now.
+ * The prompts were always shared data; what surrounded them was not. It is now.
  *
- * This composes the MESSAGE only. The tool-gap preamble (`macroToolGap`) stays a separate,
- * host-applied prepend because it depends on which AGENT is being addressed, which is a thing
- * only the host knows.
+ * ⚠️ THE TEXT IS TRANSCRIBED, NOT REWRITTEN. Every block below was generated from the CLI's own
+ * template and asserted byte-identical to what it sent before the move, because a single reworded
+ * line here is a silent behaviour change in both hosts at once.
  *
- * Spec: project-docs/00-requirements/compilr-dev-sdk/macros-rename.md
+ * This composes the MESSAGE only. The tool-gap preamble (`macroToolGap`) stays a separate,
+ * host-applied prepend: it depends on which AGENT is addressed, which only the host knows.
  */
-/** What the host knows about the project a macro is being invoked against. */
+/** What the host knows about the project a macro is invoked against. */
 export interface MacroProjectContext {
     id: string | number;
     name: string;
+    /** Absolute path on disk. `build` and `scaffold` write files and need it. */
+    path?: string;
+}
+/** A backlog item, for `build`. */
+export interface MacroWorkItem {
+    itemId: string;
+    type: string;
+    priority: string;
+    title: string;
+    description?: string;
 }
 export interface MacroInvocationContext {
-    /** Absent when no project is selected; the context block is then omitted. */
+    /** Absent when no project is selected; the context block is then omitted entirely. */
     project?: MacroProjectContext;
+    /** `prd` — the section the user named, if any. */
+    section?: string;
+    /** `session-notes` — the title the user gave, if any. */
+    noteTitle?: string;
+    /** `architecture` — the document type chosen, and how to name it back to the user. */
+    architecture?: {
+        docType: string;
+        displayType?: string;
+    };
+    /** `refine` — the item id, when refining one item rather than the whole backlog. */
+    refineItemId?: string;
+    /** `build` — the item to implement. Without it there is nothing to build. */
+    workItem?: MacroWorkItem;
+    /**
+     * `scaffold` — `factoryContext` is a pre-rendered block the host supplies because only it
+     * knows the Application Model's state; `isFactory` picks the closing instruction.
+     */
+    scaffold?: {
+        factoryContext?: string;
+        isFactory?: boolean;
+    };
 }
 export interface MacroInvocation {
     /** The text to send to the agent. */
     message: string;
-    /** The text to show the user in the transcript, in place of the full message. */
+    /** The short line to show the user in place of the full message. */
     displayMessage: string;
 }
 /**
  * Compose the message for a macro invocation.
  *
- * A macro with no wrapper sends its prompt unchanged — that is the common case and stays the
- * default, so adding a macro does not require touching this file.
+ * A macro with no wrapper sends its prompt unchanged — the common case, and the default, so
+ * adding a macro needs no edit here. A macro WITH a wrapper falls back to the bare prompt when
+ * the host cannot supply what the wrapper names: better a plain prompt than one asserting a
+ * project, an item or a path that is not there.
  *
  * @param macroName the macro being invoked, e.g. `design`
  * @param prompt    the macro's resolved prompt text
- * @param ctx       what the host knows; an absent project omits the context block
+ * @param ctx       what the host knows
  */
 export declare function buildMacroInvocation(macroName: string, prompt: string, ctx?: MacroInvocationContext): MacroInvocation;

package/dist/skills/macro-invocation.js

@@ -1,26 +1,21 @@
 /**
  * What a host actually SENDS when a user invokes a macro.
  *
- * ⚠️ THE TWO HOSTS SENT DIFFERENT THINGS FOR THE SAME COMMAND. `/design` in the CLI wrapped the
- * macro's prompt in ~20 lines of project context — do not scan the filesystem, the cwd is not the
- * project, save work items with `workitem_add` and documents with `project_document_add` rather
- * than writing files — while Desktop sent the prompt alone. Same name, same macro, materially
- * different instructions, so the same request produced an agent that interviewed you and filled
- * the backlog in one host and an agent that went looking for source files in the other.
+ * ⚠️ THE TWO HOSTS SENT DIFFERENT THINGS FOR THE SAME COMMAND. The CLI wrapped each of these
+ * macros in project context — do not scan the filesystem, the cwd is not the project, save work
+ * items with `workitem_add` and documents with `project_document_add` rather than writing files —
+ * while Desktop sent the prompt alone. Same names, same macros, materially different
+ * instructions, so the same request produced an agent that interviewed you and filled the backlog
+ * in one host and an agent that went looking for source files in the other.
  *
- * The prompt is shared data; what surrounds it was not. It is now.
+ * The prompts were always shared data; what surrounded them was not. It is now.
  *
- * This composes the MESSAGE only. The tool-gap preamble (`macroToolGap`) stays a separate,
- * host-applied prepend because it depends on which AGENT is being addressed, which is a thing
- * only the host knows.
+ * ⚠️ THE TEXT IS TRANSCRIBED, NOT REWRITTEN. Every block below was generated from the CLI's own
+ * template and asserted byte-identical to what it sent before the move, because a single reworded
+ * line here is a silent behaviour change in both hosts at once.
  *
- * Spec: project-docs/00-requirements/compilr-dev-sdk/macros-rename.md
- */
-/**
- * ⚠️ "A NEW PROJECT" IS ASSERTED, NOT DETECTED, AND THAT IS DELIBERATE. `/design` is the
- * from-scratch macro — `/refine` is the one for a backlog that already exists — so invoking it
- * states the intent. Deriving it instead (counting work items, say) would make the prompt depend
- * on database state at send time, and be wrong the moment someone re-runs /design to redesign.
+ * This composes the MESSAGE only. The tool-gap preamble (`macroToolGap`) stays a separate,
+ * host-applied prepend: it depends on which AGENT is addressed, which only the host knows.
  */
 function designContext(project) {
     return `I want to design my project and create the backlog.
@@ -42,22 +37,250 @@ Save all documents and backlog items using the database - do NOT write files dir
 }
 const DESIGN_CLOSER = 'Please start by using todo_write to track the design phases, then begin with Phase 1: Vision. ' +
     'Use the ask_user tool to gather information efficiently.';
+function sketchMessage(p, prompt) {
+    return `I want to quickly outline my project.
+
+## PROJECT CONTEXT (IMPORTANT)
+- Project Name: ${p.name} (ID: ${String(p.id)})
+- This is a NEW project being designed from scratch
+- Do NOT scan the filesystem - the current directory is NOT the project
+- Do NOT use detect_project, glob, read_file, or ls tools
+- Focus ONLY on gathering requirements via ask_user questions
+
+## DOCUMENT STORAGE (CRITICAL)
+Save all documents and backlog items using the database - do NOT write files directly.
+- For backlog items: \`workitem_add({ type: "feature", title: "...", description: "..." })\`
+- For documents: \`project_document_add({ doc_type: "prd", title: "...", content: "..." })\`
+- Do NOT use write_file or edit tools for documentation
+
+${prompt}
+
+Please start by asking me about the type of application I'm building using the ask_user_simple tool.`;
+}
+function refineMessage(p, prompt, userIntent, agentInstructions) {
+    return `${userIntent}
+
+## PROJECT CONTEXT (IMPORTANT)
+- Project Name: ${p.name} (ID: ${String(p.id)})
+- Do NOT scan the filesystem - the current directory is NOT the project
+- Do NOT use detect_project, glob, read_file, or ls tools
+- Use ONLY database tools to access project data
+
+## DOCUMENT STORAGE (CRITICAL)
+Use database tools for all updates - do NOT write files directly.
+- Use \`workitem_query\` to read items
+- Use \`workitem_update\` to modify items
+- Do NOT use write_file or edit tools
+
+${prompt}
+
+${agentInstructions}`;
+}
+function buildMessage(p, prompt, item) {
+    return `I want to implement backlog item ${item.itemId}: "${item.title}".
+
+## PROJECT CONTEXT (CRITICAL)
+- Project Name: ${p.name} (ID: ${String(p.id)})
+- **Project Directory: ${p.path ?? ''}**
+- ALL files MUST be created/modified in this directory
+
+## WORK ITEM DETAILS
+- Item ID: ${item.itemId}
+- Type: ${item.type}
+- Priority: ${item.priority}
+- Description: ${item.description ?? 'No description provided'}
+
+## TOOL RESTRICTIONS (CRITICAL)
+- Do NOT use detect_project or find_project_root
+- Do NOT scan filesystem to detect project type
+- The project path above is the ONLY source of truth for where to create/modify files
+- Use \`project_document_get\` to read PRD and architecture docs from the database
+- Use \`workitem_query\` to read related backlog items from the database
+- Use \`workitem_update\` to update the item status when done
+
+## FILE OPERATIONS (CRITICAL)
+When creating or modifying files:
+- Use absolute paths starting with: ${p.path ?? ''}/
+- Example: write_file({ path: "${p.path ?? ''}/src/index.ts", ... })
+- NEVER use relative paths
+- IGNORE the current working directory (cwd) - it may be different from the project!
+- The user may have started the CLI from a different folder
+
+${prompt}
+
+Please start by:
+1. Using todo_write to plan the implementation steps
+2. Reading project documents from the database (project_document_list, project_document_get)
+3. Updating the work item status to 'in_progress' using workitem_update
+4. Implementing the feature
+5. Updating the work item status to 'completed' when done`;
+}
+function sessionNotesMessage(p, prompt, titleInstruction) {
+    return `I want to create a session note capturing what we've done.
+
+## PROJECT CONTEXT
+- Project Name: ${p.name} (ID: ${String(p.id)})
+
+## DOCUMENT STORAGE (CRITICAL)
+Save session notes using the database - do NOT write files directly.
+- Tool: \`project_document_add({ doc_type: "session-note", title: "...", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${prompt}
+
+${titleInstruction}
+
+Review the conversation context to understand what was accomplished, then create the session note.`;
+}
+function prdMessage(p, prompt, sectionInstruction) {
+    return `I want to update the Product Requirements Document.
+
+## DOCUMENT STORAGE (CRITICAL)
+Save PRD updates using the database - do NOT write files directly.
+- Project: ${p.name} (ID: ${String(p.id)})
+- Tool: \`project_document_add({ doc_type: "prd", title: "Product Requirements Document", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${prompt}
+
+${sectionInstruction}
+
+Start by reading the existing PRD from the database using project_document_get({ doc_type: "prd" }). If no document exists yet, create a new one.`;
+}
+function architectureMessage(p, prompt, arch) {
+    return `I want to create architecture documentation.
+
+## DOCUMENT STORAGE (CRITICAL)
+Save architecture documentation using the database - do NOT write files directly.
+- Project: ${p.name} (ID: ${String(p.id)})
+- Tool: \`project_document_add({ doc_type: "architecture", title: "...", content: "..." })\`
+- The database is the source of truth for all project documents
+- Do NOT use write_file or edit tools for documentation
+
+${prompt}
+
+Please start by using project_document_list to find any existing PRD, and workitem_query to understand the project backlog. Then use ask_user to gather the information needed for this ${arch.docType} document.`;
+}
+function scaffoldMessage(p, prompt, factoryContext, closingInstruction) {
+    return `I want to create the project scaffold/foundation.
+
+## PROJECT CONTEXT (CRITICAL)
+- Project Name: ${p.name} (ID: ${String(p.id)})
+- **Project Directory: ${p.path ?? ''}**
+- ALL files MUST be created in this directory
+${factoryContext}
+## TOOL RESTRICTIONS (CRITICAL)
+- Do NOT use detect_project or find_project_root
+- Do NOT scan filesystem to detect project type
+- The project path above is the ONLY source of truth for where to create files
+- Use \`project_document_get\` to read PRD and architecture docs from the database
+- Use \`workitem_query\` to read backlog items from the database
+
+## FILE CREATION (CRITICAL)
+When creating files:
+- Use absolute paths starting with: ${p.path ?? ''}/
+- Example: write_file({ path: "${p.path ?? ''}/package.json", ... })
+- NEVER use relative paths
+- IGNORE the current working directory (cwd) - it may be different from the project!
+- The user may have started the CLI from a different folder
+
+${prompt}
+
+${closingInstruction}`;
+}
 /**
  * Compose the message for a macro invocation.
  *
- * A macro with no wrapper sends its prompt unchanged — that is the common case and stays the
- * default, so adding a macro does not require touching this file.
+ * A macro with no wrapper sends its prompt unchanged — the common case, and the default, so
+ * adding a macro needs no edit here. A macro WITH a wrapper falls back to the bare prompt when
+ * the host cannot supply what the wrapper names: better a plain prompt than one asserting a
+ * project, an item or a path that is not there.
  *
  * @param macroName the macro being invoked, e.g. `design`
  * @param prompt    the macro's resolved prompt text
- * @param ctx       what the host knows; an absent project omits the context block
+ * @param ctx       what the host knows
  */
 export function buildMacroInvocation(macroName, prompt, ctx = {}) {
-    if (macroName === 'design' && ctx.project) {
-        return {
-            message: `${designContext(ctx.project)}\n${prompt}\n\n${DESIGN_CLOSER}`,
-            displayMessage: 'Start the design process for my project.',
-        };
+    const p = ctx.project;
+    if (!p)
+        return { message: prompt, displayMessage: `/${macroName}` };
+    switch (macroName) {
+        case 'design':
+            return {
+                message: `${designContext(p)}\n${prompt}\n\n${DESIGN_CLOSER}`,
+                displayMessage: 'Start the design process for my project.',
+            };
+        case 'sketch':
+            return { message: sketchMessage(p, prompt), displayMessage: 'Quick project outline.' };
+        case 'refine':
+        case 'refine-item': {
+            // Bound to a local so the narrowing survives into the template literals.
+            const itemId = ctx.refineItemId;
+            const userIntent = itemId !== undefined
+                ? `I want to refine backlog item ${itemId}.`
+                : 'I want to refine my project requirements.';
+            const agentInstructions = itemId !== undefined
+                ? `Please use workitem_query to find item "${itemId}", then guide me through refining it using workitem_update.`
+                : "Please start by using workitem_query with limit:10 to get an overview, then ask me what I'd like to focus on using ask_user_simple.";
+            return {
+                message: refineMessage(p, prompt, userIntent, agentInstructions),
+                displayMessage: userIntent,
+            };
+        }
+        case 'build': {
+            // Nothing to build without an item, and the whole wrapper is about one.
+            if (!ctx.workItem)
+                return { message: prompt, displayMessage: `/${macroName}` };
+            return {
+                message: buildMessage(p, prompt, ctx.workItem),
+                displayMessage: `Build ${ctx.workItem.itemId}: ${ctx.workItem.title}`,
+            };
+        }
+        case 'session-notes': {
+            const titleInstruction = ctx.noteTitle
+                ? `The session title is: "${ctx.noteTitle}"`
+                : 'Please ask me for a title using ask_user_simple, or generate one from the session summary.';
+            return {
+                message: sessionNotesMessage(p, prompt, titleInstruction),
+                displayMessage: ctx.noteTitle
+                    ? `Create session note: "${ctx.noteTitle}"`
+                    : 'Create a session note for this session.',
+            };
+        }
+        case 'prd': {
+            const valid = ['vision', 'scope', 'technical', 'success'];
+            const section = ctx.section ?? '';
+            const sectionInstruction = valid.includes(section)
+                ? `The user wants to update the "${section}" section specifically.`
+                : 'Ask the user which section they want to update using ask_user_simple.';
+            return {
+                message: prdMessage(p, prompt, sectionInstruction),
+                displayMessage: section
+                    ? `Update PRD: ${section} section`
+                    : 'Update the Product Requirements Document',
+            };
+        }
+        case 'architecture': {
+            if (!ctx.architecture)
+                return { message: prompt, displayMessage: `/${macroName}` };
+            return {
+                message: architectureMessage(p, prompt, ctx.architecture),
+                displayMessage: `Create ${ctx.architecture.displayType ?? ctx.architecture.docType} documentation.`,
+            };
+        }
+        case 'scaffold':
+        case 'factory-scaffold': {
+            const closingInstruction = macroName === 'factory-scaffold' || ctx.scaffold?.isFactory
+                ? 'Start by checking the Application Model with app_model_get. If no model exists, read the PRD with project_document_get and build the model incrementally using app_model_update. Then generate with factory_scaffold.'
+                : 'Start by reading the project documents from the database using project_document_list and project_document_get. Then create a plan with todo_write before generating files.';
+            return {
+                message: scaffoldMessage(p, prompt, ctx.scaffold?.factoryContext ?? '', closingInstruction),
+                displayMessage: 'Create project scaffold.',
+            };
+        }
+        default:
+            return { message: prompt, displayMessage: `/${macroName}` };
     }
-    return { message: prompt, displayMessage: `/${macroName}` };
 }

package/dist/skills/operations.d.ts

@@ -65,6 +65,11 @@ export interface SkillValidationIssue {
 /**
  * Validate a parsed custom skill beyond basic frontmatter parsing.
  */
+/**
+ * The description our own template ships. Matched on its opening, so an author who edited the tail
+ * but left the head is still caught.
+ */
+export declare function isPlaceholderDescription(description: string): boolean;
 export declare function validateSkill(skill: CustomSkill, folderName: string): SkillValidationIssue[];
 export interface ScopeConfig {
     slashCommands?: Record<string, string>;

package/dist/skills/operations.js

@@ -7,8 +7,9 @@
  * - Validation (quality checks beyond parseSkillMarkdown)
  * - Binding resolution (config.json slash command remapping)
  */
-import { RESERVED_MACRO_NAMES } from './types.js';
 import { platformMacros } from './platform-macros.js';
+import { builtinSkills } from '@compilr-dev/agents';
+import { RESERVED_MACRO_NAMES } from './types.js';
 /**
  * Detect user/project skills that shadow SDK reserved names.
  * Called at startup to warn users about collisions introduced by SDK updates.
@@ -152,13 +153,18 @@ export function buildForkContent(sdkSkill, newName, sdkVersion) {
  * Build the SKILL.md template for a new custom skill.
  */
 export function buildNewSkillContent(name, scope) {
+    /*
+      ⚠️ NO DESCRIPTION. It used to ship a paragraph of advice IN the description field, and people
+      shipped it unchanged — 291 characters, which passed every length check we had, so the catalogue
+      filled with entries no agent would ever choose. The advice moved to a comment, where it cannot
+      be mistaken for content. Never pre-fill a field with text that would be valid if saved.
+    */
     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.)
+description: ''
+# ↑ REQUIRED, and written for a different reader: the model decides from this whether to load the
+# skill. Name the trigger conditions, the phrases a user would say, and what it produces. Real
+# skills run 100+ characters — it is a net for matching, not a summary.
 version: 0.1.0
 
 # Optional — compilr extensions (ignored by Anthropic-compatible runtimes).
@@ -186,6 +192,13 @@ Describe the first step.
 /**
  * Validate a parsed custom skill beyond basic frontmatter parsing.
  */
+/**
+ * The description our own template ships. Matched on its opening, so an author who edited the tail
+ * but left the head is still caught.
+ */
+export function isPlaceholderDescription(description) {
+    return description.trim().startsWith('Use this skill when …');
+}
 export function validateSkill(skill, folderName) {
     const issues = [];
     if (skill.name !== folderName) {
@@ -194,12 +207,41 @@ export function validateSkill(skill, folderName) {
             message: `Frontmatter name '${skill.name}' doesn't match folder '${folderName}'.`,
         });
     }
-    if (skill.description.length < 60) {
+    /*
+      ⚠️ THE FLOOR IS 100, AND MEASURED. Across 50 Anthropic-authored SKILL.md files the shortest
+      description is 105 characters; median 329, p90 906. The old floor of 60 sat BELOW the shortest
+      real skill, so it could never fire on anything plausible.
+  
+      And it cannot catch the thing that actually breaks: our own template placeholder was 291
+      characters — comfortably normal — so every length check passed it. Only persistent UI state
+      solves that; the explicit placeholder check below is the cheap half.
+    */
+    if (skill.description.trim().length < 100) {
+        issues.push({
+            level: 'warning',
+            message: `Description is ${String(skill.description.trim().length)} chars. Real skills run 100+ — it is a net for matching, not a summary.`,
+        });
+    }
+    if (isPlaceholderDescription(skill.description)) {
         issues.push({
             level: 'warning',
-            message: `Description is ${String(skill.description.length)} chars (recommend 60+).`,
+            message: 'Description is still the template placeholder — no agent will choose this skill. Length checks cannot catch it; it is 291 characters.',
         });
     }
+    /*
+      Forking copies the source's description verbatim, so two catalogue entries read the same and no
+      agent can tell them apart. This becomes the COMMON failure once forking is one click, and
+      neither the old UI nor the original design brief caught it.
+    */
+    if (skill.forkedFrom?.skill) {
+        const source = [...platformMacros, ...builtinSkills].find((m) => m.name === skill.forkedFrom?.skill);
+        if (source && source.description.trim() === skill.description.trim()) {
+            issues.push({
+                level: 'warning',
+                message: `Description is identical to /${skill.forkedFrom.skill}, which it was forked from — an agent cannot choose between them.`,
+            });
+        }
+    }
     if (!skill.prompt || skill.prompt.trim().length === 0) {
         issues.push({
             level: 'warning',

package/dist/skills/patch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Edit a SKILL.md's frontmatter WITHOUT rewriting it.
+ *
+ * ⚠️ PARSE FOR READING, PATCH FOR WRITING. Regenerating frontmatter from parsed YAML destroys
+ * comments — they are not in any YAML data model. Measured on our own template: `parse → stringify`
+ * took it from 17 lines to 7 and all 9 comment lines to 0, deleting the commented-out `compilr:`
+ * block we ship deliberately as documentation.
+ *
+ * So retaining unknown KEYS is not sufficient. This edits the lines it is given and returns every
+ * other byte unchanged: comments, key order, spacing, and fields we have never modelled.
+ *
+ * The guard this buys, and it covers the whole class: open a skill, change nothing, save — the
+ * file must be byte-identical.
+ *
+ * Decision D-2: project-docs/.../compilr-dev-skills/implementation-plan.md
+ */
+/** `undefined` leaves a key alone; `null` removes it; anything else sets it. */
+export type FrontmatterPatch = Record<string, string | number | boolean | null | undefined>;
+/**
+ * Apply `patch` to `content`'s frontmatter, leaving everything else byte-identical.
+ *
+ * Returns the content unchanged when it has no frontmatter — a caller should not be silently
+ * handed a file it cannot edit.
+ */
+export declare function patchSkillFrontmatter(content: string, patch: FrontmatterPatch): string;

package/dist/skills/patch.js

@@ -0,0 +1,91 @@
+/**
+ * Edit a SKILL.md's frontmatter WITHOUT rewriting it.
+ *
+ * ⚠️ PARSE FOR READING, PATCH FOR WRITING. Regenerating frontmatter from parsed YAML destroys
+ * comments — they are not in any YAML data model. Measured on our own template: `parse → stringify`
+ * took it from 17 lines to 7 and all 9 comment lines to 0, deleting the commented-out `compilr:`
+ * block we ship deliberately as documentation.
+ *
+ * So retaining unknown KEYS is not sufficient. This edits the lines it is given and returns every
+ * other byte unchanged: comments, key order, spacing, and fields we have never modelled.
+ *
+ * The guard this buys, and it covers the whole class: open a skill, change nothing, save — the
+ * file must be byte-identical.
+ *
+ * Decision D-2: project-docs/.../compilr-dev-skills/implementation-plan.md
+ */
+function splitFrontmatter(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 {
+                before: '---\n',
+                frontmatter: lines.slice(1, i).join('\n'),
+                after: '\n---' + content.slice(content.indexOf('\n---', content.indexOf('\n')) + 4),
+            };
+        }
+    }
+    return null;
+}
+/** Does this line begin the given top-level key? Indented lines are values, not keys. */
+function startsKey(line, key) {
+    return new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*:`).test(line);
+}
+/** The lines a top-level key owns: its own, plus any indented or blank continuation. */
+function keyBlockEnd(lines, start) {
+    let end = start + 1;
+    while (end < lines.length) {
+        const l = lines[end];
+        if (l.trim() === '' || /^\s/.test(l)) {
+            end++;
+            continue;
+        }
+        break;
+    }
+    // Trailing blank lines belong to whatever follows, not to this key.
+    while (end > start + 1 && lines[end - 1].trim() === '')
+        end--;
+    return end;
+}
+function render(key, value) {
+    if (typeof value === 'string' && (value.includes('\n') || value.length > 80)) {
+        const body = value
+            .split('\n')
+            .map((l) => `  ${l}`)
+            .join('\n');
+        return `${key}: |\n${body}`;
+    }
+    return `${key}: ${String(value)}`;
+}
+/**
+ * Apply `patch` to `content`'s frontmatter, leaving everything else byte-identical.
+ *
+ * Returns the content unchanged when it has no frontmatter — a caller should not be silently
+ * handed a file it cannot edit.
+ */
+export function patchSkillFrontmatter(content, patch) {
+    const split = splitFrontmatter(content);
+    if (!split)
+        return content;
+    const lines = split.frontmatter.split('\n');
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        const idx = lines.findIndex((l) => startsKey(l, key));
+        if (value === null) {
+            if (idx !== -1)
+                lines.splice(idx, keyBlockEnd(lines, idx) - idx);
+            continue;
+        }
+        if (idx === -1) {
+            lines.push(render(key, value));
+            continue;
+        }
+        lines.splice(idx, keyBlockEnd(lines, idx) - idx, ...render(key, value).split('\n'));
+    }
+    return split.before + lines.join('\n') + split.after;
+}

package/dist/skills/prompt-resolver.js

@@ -16,6 +16,7 @@
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { parseSkillMarkdown } from './loader.js';
+import { skillReachability } from './reachability.js';
 import { resolveBinding, getSkillsDir, readScopeConfigSync } from './paths.js';
 import { platformMacros } from './platform-macros.js';
 // Re-export builtinSkills from agents (available via SDK re-export)
@@ -35,7 +36,9 @@ function readScopedSkillPrompt(scope, name, projectDir) {
             return null;
         const content = readFileSync(file, 'utf-8');
         const parsed = parseSkillMarkdown(content);
-        if (!parsed || parsed.enabled === false)
+        // A skill the USER may not type does not resolve as a slash command. `enabled: false` maps
+        // to both switches off, so a shelved skill still refuses here (D-1).
+        if (!parsed || !skillReachability(parsed).byUser)
             return null;
         return parsed.prompt;
     }
@@ -168,7 +171,7 @@ export function getAllAvailableSkills(projectDir, sources) {
                             description: parsed.description,
                             source: scope,
                             scope,
-                            enabled: parsed.enabled !== false,
+                            enabled: skillReachability(parsed).byUser,
                             hasWarnings: parsed.description.length < 60 || !parsed.prompt.trim(),
                             isForked: !!parsed.forkedFrom,
                         });

package/dist/skills/reachability.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Who can reach a skill — and the migration off `enabled`.
+ *
+ * ⚠️ TWO AXES, NOT ONE. Reachability asks "can ANYTHING reach this skill?" and lives in the file,
+ * in Anthropic's own fields. The GRANT asks "which agents may choose among the reachable ones?"
+ * and lives on the agent as `grantedSkills`, the same contract as `mcpServers`. They compose: an
+ * unreachable skill is unreachable whatever the grants say.
+ *
+ * ⚠️ `enabled` IS NOT PART OF THE FORMAT. Zero of 50 Anthropic-authored SKILL.md files carry it;
+ * we invented it, and three precedents point the other way — Claude Code disables plugins in
+ * settings.json rather than by editing the artifact, and our own MCP model has no enabled flag
+ * either. It is mapped here, on READ, so a skill someone disabled long ago and never re-saved
+ * keeps reading as unreachable. It is never written back.
+ *
+ * Decision D-1: project-docs/.../compilr-dev-skills/implementation-plan.md
+ */
+import type { CustomSkill } from './types.js';
+export interface SkillReachability {
+    /** An agent may choose this skill from its catalogue. */
+    byModel: boolean;
+    /** A user may type this skill as a slash command. */
+    byUser: boolean;
+}
+/** Nothing can reach it — the state that replaces `enabled: false`. */
+export declare function isUnreachable(skill: Pick<CustomSkill, 'enabled' | 'disableModelInvocation' | 'userInvocable'>): boolean;
+/**
+ * Resolve the two switches, applying the legacy mapping.
+ *
+ * Defaults, and why they differ from Anthropic's:
+ * - `byModel` defaults TRUE, matching the format: absent `disable-model-invocation` means the
+ *   model may choose it.
+ * - `byUser` defaults TRUE, which Anthropic's format does NOT — there, `user-invocable` opts in.
+ *   Every SKILL.md in compilr has always been typeable and decision D-1 in commands-and-skills.md
+ *   keeps it so; flipping the default would silently un-type every skill anyone has already built.
+ */
+export declare function skillReachability(skill: Pick<CustomSkill, 'enabled' | 'disableModelInvocation' | 'userInvocable'>): SkillReachability;

package/dist/skills/reachability.js

@@ -0,0 +1,41 @@
+/**
+ * Who can reach a skill — and the migration off `enabled`.
+ *
+ * ⚠️ TWO AXES, NOT ONE. Reachability asks "can ANYTHING reach this skill?" and lives in the file,
+ * in Anthropic's own fields. The GRANT asks "which agents may choose among the reachable ones?"
+ * and lives on the agent as `grantedSkills`, the same contract as `mcpServers`. They compose: an
+ * unreachable skill is unreachable whatever the grants say.
+ *
+ * ⚠️ `enabled` IS NOT PART OF THE FORMAT. Zero of 50 Anthropic-authored SKILL.md files carry it;
+ * we invented it, and three precedents point the other way — Claude Code disables plugins in
+ * settings.json rather than by editing the artifact, and our own MCP model has no enabled flag
+ * either. It is mapped here, on READ, so a skill someone disabled long ago and never re-saved
+ * keeps reading as unreachable. It is never written back.
+ *
+ * Decision D-1: project-docs/.../compilr-dev-skills/implementation-plan.md
+ */
+/** Nothing can reach it — the state that replaces `enabled: false`. */
+export function isUnreachable(skill) {
+    const r = skillReachability(skill);
+    return !r.byModel && !r.byUser;
+}
+/**
+ * Resolve the two switches, applying the legacy mapping.
+ *
+ * Defaults, and why they differ from Anthropic's:
+ * - `byModel` defaults TRUE, matching the format: absent `disable-model-invocation` means the
+ *   model may choose it.
+ * - `byUser` defaults TRUE, which Anthropic's format does NOT — there, `user-invocable` opts in.
+ *   Every SKILL.md in compilr has always been typeable and decision D-1 in commands-and-skills.md
+ *   keeps it so; flipping the default would silently un-type every skill anyone has already built.
+ */
+export function skillReachability(skill) {
+    // The legacy field wins when explicitly false: it is the user's stated intent to shelve it,
+    // recorded before the two switches existed.
+    if (skill.enabled === false)
+        return { byModel: false, byUser: false };
+    return {
+        byModel: skill.disableModelInvocation !== true,
+        byUser: skill.userInvocable !== false,
+    };
+}

package/dist/skills/resolver.js

@@ -15,6 +15,7 @@
  *   - Stage 2 ACTIVATION: model picks from descriptions, runs per turn.
  *     (Stage 2 is the existing skill invocation — this file only does Stage 1.)
  */
+import { skillReachability } from './reachability.js';
 /**
  * Resolve a list of skills from layered sources by priority. First match
  * by name wins. Returns the deduplicated list, with each skill carrying
@@ -55,7 +56,13 @@ export function resolveSkillsForAgent(skills, context) {
     */
     const allowlist = context.grantedSkills ? new Set(context.grantedSkills) : null;
     return skills.filter((skill) => {
-        if (skill.enabled === false)
+        // Stage 0 — a skill with no description cannot be CHOSEN: the description is the only thing
+        // the model sees in the catalogue. Loading it costs tokens and offers nothing to match on.
+        if (skill.description.trim() === '')
+            return false;
+        // Stage 1.0 — reachability. A skill the MODEL may not choose never enters a catalogue,
+        // whatever the grants say. `enabled: false` maps here; see skillReachability (D-1).
+        if (!skillReachability(skill).byModel)
             return false;
         // Stage 1.1 — Targeting. Default = targets every agent.
         const targets = skill.compilr?.targets;

package/dist/skills/software-macros.js

@@ -18,9 +18,9 @@ export const designMacro = defineSkill({
 - Need to create initial backlog
 
 ## When NOT to Use
-- Project already has requirements → use refine skill
-- Quick project outline needed → use sketch skill
-- Just need to update PRD → use prd skill
+- Project already has requirements → tell the user to run /refine
+- Quick project outline needed → tell the user to run /sketch
+- Just need to update PRD → tell the user to run /prd
 
 ## PHASES
 
@@ -104,9 +104,9 @@ export const refineMacro = defineSkill({
 - Adding missing items to backlog
 
 ## When NOT to Use
-- No backlog exists yet → use design skill
-- Quick outline needed → use sketch skill
-- Refining single item → use refine-item skill
+- No backlog exists yet → tell the user to run /design
+- Quick outline needed → tell the user to run /sketch
+- Refining single item → tell the user to run /refine-item
 
 ## STARTUP
 
@@ -182,9 +182,9 @@ export const sketchMacro = defineSkill({
 - Initial brainstorming session
 
 ## When NOT to Use
-- Detailed requirements needed → use design skill
-- Project already has backlog → use refine skill
-- Single item focus → use refine-item skill
+- Detailed requirements needed → tell the user to run /design
+- Project already has backlog → tell the user to run /refine
+- Single item focus → tell the user to run /refine-item
 
 STEPS:
 1. Use todo_write with 6 tasks (one per question)
@@ -221,9 +221,9 @@ export const refineItemMacro = defineSkill({
 - Changing priority of specific item
 
 ## When NOT to Use
-- Multiple items need refinement → use refine skill
-- No items exist yet → use design or sketch skill
-- Ready to implement → use build skill
+- Multiple items need refinement → tell the user to run /refine
+- No items exist yet → tell the user to run /design or /sketch
+- Ready to implement → tell the user to run /build
 
 ## STARTUP
 
@@ -290,9 +290,9 @@ export const architectureMacro = defineSkill({
 - Recording technical decisions
 
 ## When NOT to Use
-- Need product requirements → use design or prd skill
-- Need to implement features → use build skill
-- Just want to understand existing code → use explain skill
+- Need product requirements → tell the user to run /design or /prd
+- Need to implement features → tell the user to run /build
+- Just want to understand existing code → tell the user to run /explain
 
 ## DOCUMENT TYPE: {{doc_type}}
 {{#if custom_topic}}Custom Topic: {{custom_topic}}{{/if}}
@@ -434,9 +434,9 @@ export const prdMacro = defineSkill({
 - Refining vision or scope
 
 ## When NOT to Use
-- No PRD exists yet → use design skill first
-- Need architecture docs → use architecture skill
-- Need session summary → use session-notes skill
+- No PRD exists yet → tell the user to run /design first
+- Need architecture docs → tell the user to run /architecture
+- Need session summary → tell the user to run /session-notes
 
 ## STARTUP
 
@@ -519,8 +519,8 @@ export const sessionNotesMacro = defineSkill({
 - Need to capture decisions for future reference
 
 ## When NOT to Use
-- Need product requirements → use prd skill
-- Need architecture docs → use architecture skill
+- Need product requirements → tell the user to run /prd
+- Need architecture docs → tell the user to run /architecture
 - In the middle of active work
 
 ## STARTUP
@@ -614,10 +614,10 @@ export const buildMacro = defineSkill({
 - Ready to write code for a feature
 
 ## When NOT to Use
-- Item is too vague → use refine-item skill first
-- No backlog exists → use design or sketch skill
-- Just exploring code → use code-navigation skill
-- Need to fix a bug → use debug skill
+- Item is too vague → tell the user to run /refine-item first
+- No backlog exists → tell the user to run /design or /sketch
+- Just exploring code → tell the user to run /code-navigation
+- Need to fix a bug → tell the user to run /debug
 
 ## CRITICAL: PROJECT DIRECTORY
 
@@ -711,9 +711,9 @@ export const scaffoldMacro = defineSkill({
 - Need basic project structure
 
 ## When NOT to Use
-- Project already has structure → use build skill
-- Need requirements first → use design skill
-- Modifying existing project → use appropriate skill
+- Project already has structure → tell the user to run /build
+- Need requirements first → tell the user to run /design
+- Modifying existing project → tell the user to run /appropriate
 
 ## FACTORY CHECK (TRY THIS FIRST)
 

package/dist/skills/types.d.ts

@@ -60,7 +60,39 @@ export interface CustomSkill {
     license?: string;
     version?: string;
     tags?: string[];
+    /**
+     * ⚠️ LEGACY, AND NOT PART OF THE ANTHROPIC FORMAT. Zero of 50 Anthropic-authored SKILL.md files
+     * carry it; we invented it. It is read ONLY so the loader can migrate it — see
+     * `skillReachability`, which maps `enabled: false` onto both invocation switches being off.
+     * Never write it. Decision D-1 in the skills implementation plan.
+     */
     enabled?: boolean;
+    /**
+     * The model may NOT choose this skill (Anthropic: `disable-model-invocation`).
+     * Absent means the model may choose it, which is the format's default.
+     */
+    disableModelInvocation?: boolean;
+    /**
+     * The user may type this skill as a slash command (Anthropic: `user-invocable`).
+     *
+     * ⚠️ WE DEFAULT THIS ON; ANTHROPIC'S FORMAT DEFAULTS IT OFF. Deliberate: every SKILL.md in
+     * compilr has always been typeable, and decision D-1 in commands-and-skills.md keeps it that
+     * way so `/my-thing` does not stop working for anyone who built one. Flipping the default would
+     * silently un-type every existing user skill.
+     */
+    userInvocable?: boolean;
+    /** Argument hint shown for typed invocation (Anthropic: `argument-hint`). */
+    argumentHint?: string;
+    /** Tools this skill declares it needs (Anthropic: `allowed-tools`). */
+    allowedTools?: string[];
+    /**
+     * Every frontmatter key exactly as parsed, including ones we do not model.
+     *
+     * Populated on read so a host can SHOW `compatibility`, `license` and anything else without us
+     * having modelled it. Writing is done by patching the original text — see
+     * `patchSkillFrontmatter` — so this is for display, never for regeneration.
+     */
+    rawFrontmatter?: Record<string, unknown>;
     compilr?: CompilrSkillExtension;
     /** Set when this skill was created via /skill fork. */
     forkedFrom?: ForkedFromMarker;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,8 @@
     "./models": {
       "types": "./dist/models/index.d.ts",
       "import": "./dist/models/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",