@compilr-dev/sdk 0.28.0 → 0.29.0

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/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/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/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.28.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",