@compilr-dev/sdk 0.24.2 → 0.25.1

package/dist/agent.js

@@ -15,6 +15,8 @@ import { CapabilityManager } from './capabilities/manager.js';
 import { CapabilityContext } from './capabilities/context.js';
 import { createCapabilityHook } from './capabilities/hook.js';
 import { createLoadCapabilityTool } from './capabilities/load-tool.js';
+import { createLoadSkillTool } from './skills/load-tool.js';
+import { generateSkillCatalog, toCatalogEntry } from './skills/catalog.js';
 import { resolveProfileGroups, resolveUpfrontGroups } from './capabilities/profile-resolver.js';
 import { MetaToolsRegistry, createMetaTools } from './meta-tools/registry.js';
 /**
@@ -116,13 +118,40 @@ class CompilrAgentImpl {
         else {
             systemPrompt = preset.systemPrompt;
         }
+        /*
+          Skills the model may choose from. The host has already filtered these for this agent — see
+          `CompilrAgentConfig.skills`. Two things follow: a catalogue of names and DESCRIPTIONS in the
+          prompt, and `load_skill` to fetch a body on demand. Bodies never go in the prompt; `design`
+          alone is 3,724 characters.
+        */
+        const eligibleSkills = config?.skills ?? [];
+        const loadedSkillNames = [];
         // Assemble all tools from preset + config
         let allTools = deduplicateTools(assembleTools(preset, config?.tools));
+        if (eligibleSkills.length > 0) {
+            allTools = [
+                ...allTools,
+                createLoadSkillTool({
+                    // Re-read on every call: an edit rebuilds the agent, so this closure is rebuilt too,
+                    // but reading through the array keeps the tool honest if that ever stops being true.
+                    available: () => eligibleSkills,
+                    onLoaded: (name) => {
+                        if (!loadedSkillNames.includes(name))
+                            loadedSkillNames.push(name);
+                    },
+                }),
+            ];
+        }
         // Replace default suggest tool with callback-wired version when onSuggest is provided
         if (config?.onSuggest) {
             const wiredSuggest = createSuggestTool({ onSuggest: config.onSuggest });
             allTools = allTools.map((t) => t.definition.name === 'suggest' ? wiredSuggest : t);
         }
+        if (eligibleSkills.length > 0) {
+            const catalog = generateSkillCatalog(eligibleSkills.map(toCatalogEntry), loadedSkillNames);
+            if (catalog)
+                systemPrompt = systemPrompt ? `${systemPrompt}\n\n${catalog}` : catalog;
+        }
         // Build context manager if configured
         let contextManager;
         const extendedContext = config?.context?.extendedContext ?? false;

package/dist/config.d.ts

@@ -5,6 +5,7 @@ import type { LLMProvider, Message, Tool, ToolPermission, HooksConfig, AnchorInp
 import type { Preset } from './presets/types.js';
 import type { ToolProfile } from './team/tool-config.js';
 import type { ConditionalModule } from './capabilities/hook.js';
+import type { CustomSkill } from './skills/types.js';
 /**
  * Dynamic capability loading configuration.
  *
@@ -298,6 +299,18 @@ export interface CompilrAgentConfig {
      * Omit or set enabled: false for the legacy all-tools-upfront mode.
      */
     capabilities?: CapabilitiesConfig;
+    /**
+     * Skills this agent may load, ALREADY filtered for eligibility by the host.
+     *
+     * ⚠️ THE HOST FILTERS, THE SDK PRESENTS — the same split as MCP grants. The host owns the
+     * skill directories and knows which agent it is building (the factory receives the TeamAgent),
+     * so it applies `resolveSkillsForAgent`; the SDK turns the result into a catalogue the model
+     * reads and a `load_skill` tool it can call. Passing an unfiltered pool here would hand every
+     * agent every skill, which is the defect this whole line of work started from.
+     *
+     * Omit for no skills — the catalogue is then absent rather than empty.
+     */
+    skills?: CustomSkill[];
 }
 /**
  * High-level agent interface

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/skills/catalog.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Skill catalogue — what the model reads to decide which skill to load.
+ *
+ * ⚠️ THIS IS THE PIECE THAT MAKES A SKILL A SKILL. Until it existed, `SKILL.md` files were
+ * user-invoked prompt macros: the host pasted a body into the chat when someone typed a slash
+ * command, the model never saw a list, and `description` — the field the Anthropic format exists
+ * to make the model read — was decoration. Every per-agent skill setting in the product was
+ * therefore inert, because there was nothing for it to restrict.
+ *
+ * Modelled deliberately on `capabilities/catalog.ts`: the same shape already works for tools
+ * (`## Available Capabilities` + `load_capability`). Skills are that pattern with prompts.
+ *
+ * ⚠️ DESCRIPTIONS ONLY, NEVER BODIES. A body is what `load_skill` returns. Putting bodies here
+ * would be the mistake the capability system was built to avoid — measured on the same codebase,
+ * making language packs lazy saved ~8.4K tokens per turn. `design` alone is 3,724 characters.
+ */
+import type { CustomSkill } from './types.js';
+/** A skill as the model sees it before loading: what it is for, not what it says. */
+export interface SkillCatalogEntry {
+    name: string;
+    description: string;
+}
+/**
+ * Build the system-prompt section listing the skills this agent may load.
+ *
+ * @param skills - the skills this agent is eligible for, already filtered by
+ *                 `resolveSkillsForAgent` (grants, targeting, project type, tool guards)
+ * @param loadedNames - skills already loaded this session, so the model does not reload them
+ * @returns the section, or '' when there is nothing to offer — an empty heading reads as a
+ *          capability the agent has and cannot use
+ */
+export declare function generateSkillCatalog(skills: readonly SkillCatalogEntry[], loadedNames?: readonly string[]): string;
+/** Narrow a resolved skill to what the catalogue publishes. */
+export declare function toCatalogEntry(skill: CustomSkill): SkillCatalogEntry;

package/dist/skills/catalog.js

@@ -0,0 +1,57 @@
+/**
+ * Skill catalogue — what the model reads to decide which skill to load.
+ *
+ * ⚠️ THIS IS THE PIECE THAT MAKES A SKILL A SKILL. Until it existed, `SKILL.md` files were
+ * user-invoked prompt macros: the host pasted a body into the chat when someone typed a slash
+ * command, the model never saw a list, and `description` — the field the Anthropic format exists
+ * to make the model read — was decoration. Every per-agent skill setting in the product was
+ * therefore inert, because there was nothing for it to restrict.
+ *
+ * Modelled deliberately on `capabilities/catalog.ts`: the same shape already works for tools
+ * (`## Available Capabilities` + `load_capability`). Skills are that pattern with prompts.
+ *
+ * ⚠️ DESCRIPTIONS ONLY, NEVER BODIES. A body is what `load_skill` returns. Putting bodies here
+ * would be the mistake the capability system was built to avoid — measured on the same codebase,
+ * making language packs lazy saved ~8.4K tokens per turn. `design` alone is 3,724 characters.
+ */
+/**
+ * Build the system-prompt section listing the skills this agent may load.
+ *
+ * @param skills - the skills this agent is eligible for, already filtered by
+ *                 `resolveSkillsForAgent` (grants, targeting, project type, tool guards)
+ * @param loadedNames - skills already loaded this session, so the model does not reload them
+ * @returns the section, or '' when there is nothing to offer — an empty heading reads as a
+ *          capability the agent has and cannot use
+ */
+export function generateSkillCatalog(skills, loadedNames = []) {
+    if (skills.length === 0)
+        return '';
+    const lines = [
+        '## Available Skills',
+        '',
+        'Procedures you can load when a task calls for one. Read the descriptions and call ' +
+            '`load_skill` with the name when it fits what the user is asking for — do not load one ' +
+            'speculatively, and do not describe a skill to the user instead of using it.',
+        '',
+    ];
+    for (const skill of skills) {
+        lines.push(`- **${skill.name}** — ${collapse(skill.description)}`);
+    }
+    if (loadedNames.length > 0) {
+        lines.push('');
+        lines.push(`Already loaded: ${loadedNames.join(', ')}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Anthropic-format descriptions are deliberately long and often multi-line — the format asks for
+ * trigger conditions and example phrasings. A newline inside a list item breaks the list, so the
+ * catalogue reads as prose and the model loses the one-skill-per-line structure it is scanning.
+ */
+function collapse(description) {
+    return description.replace(/\s*\n+\s*/g, ' ').trim();
+}
+/** Narrow a resolved skill to what the catalogue publishes. */
+export function toCatalogEntry(skill) {
+    return { name: skill.name, description: skill.description };
+}

package/dist/skills/index.d.ts

@@ -3,9 +3,13 @@
  */
 export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker } from './types.js';
 export { RESERVED_SKILL_NAMES, isReservedSkillName } from './types.js';
-export { parseSkillMarkdown, loadSkillsFromDir } from './loader.js';
+export { parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills } from './loader.js';
 export type { SkillEligibilityContext } from './resolver.js';
-export { resolveLayeredSkills, resolveSkillsForAgent } from './resolver.js';
+export { resolveLayeredSkills, resolveSkillsForAgent, resolveSkillsForTeamAgent, } from './resolver.js';
+export { generateSkillCatalog, toCatalogEntry } from './catalog.js';
+export type { SkillCatalogEntry } from './catalog.js';
+export { createLoadSkillTool } from './load-tool.js';
+export type { SkillSource } from './load-tool.js';
 export type { SkillCollision, SkillDiffLine, SkillValidationIssue, ScopeConfig, SkillResolution, } from './operations.js';
 export { detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill, } from './operations.js';
 export type { SkillScope } from './paths.js';

package/dist/skills/index.js

@@ -1,6 +1,8 @@
 export { RESERVED_SKILL_NAMES, isReservedSkillName } from './types.js';
-export { parseSkillMarkdown, loadSkillsFromDir } from './loader.js';
-export { resolveLayeredSkills, resolveSkillsForAgent } from './resolver.js';
+export { parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills } from './loader.js';
+export { resolveLayeredSkills, resolveSkillsForAgent, resolveSkillsForTeamAgent, } from './resolver.js';
+export { generateSkillCatalog, toCatalogEntry } from './catalog.js';
+export { createLoadSkillTool } from './load-tool.js';
 export { detectCollisions, formatCollisionWarnings, diffForkVsUpstream, buildForkContent, buildNewSkillContent, validateSkill, } from './operations.js';
 export { getSkillsDir, getSkillFolder, getSkillFile, ensureSkillsDir, isValidSkillName, getScopeConfigPath, readScopeConfig as readSkillScopeConfig, readScopeConfigSync as readSkillScopeConfigSync, writeScopeConfig as writeSkillScopeConfig, getAllBindings as getSkillBindings, resolveBinding as resolveSkillBinding, } from './paths.js';
 export { resolveSkillPrompt, getAllAvailableSkills } from './prompt-resolver.js';

package/dist/skills/load-tool.d.ts

@@ -0,0 +1,30 @@
+/**
+ * load_skill — how an agent reaches a skill body.
+ *
+ * ⚠️ BEFORE THIS TOOL THERE WAS NO PATH FROM AN AGENT TO A SKILL. Skills were delivered only by
+ * the HOST, when a user typed a slash command; the body arrived as a user message and the model
+ * had no way to ask for one. `canvas_guide` exists precisely as a hand-built escape hatch around
+ * that gap, exposing 8 of ~48 bodies, and its own comment says so. Meanwhile ~30 platform prompts
+ * instruct the model to "use the refine skill" — advice it could only relay to the user.
+ *
+ * Deliberately unlike `load_capability`, which loads a pack and lets the NEXT turn see new tools:
+ * a skill body is content, not capability, so it is returned directly and is usable in the same
+ * turn. Nothing needs to be rebuilt.
+ */
+import type { Tool } from '@compilr-dev/agents';
+interface LoadSkillInput {
+    skill: string;
+}
+/** What `load_skill` can reach: the skills this agent is eligible for, resolved per turn. */
+export interface SkillSource {
+    /** Eligible skills — already filtered by grants, targeting, project type and tool guards. */
+    available: () => {
+        name: string;
+        description: string;
+        prompt: string;
+    }[];
+    /** Called when a skill is successfully loaded, so the catalogue can mark it. */
+    onLoaded?: (name: string) => void;
+}
+export declare function createLoadSkillTool(source: SkillSource): Tool<LoadSkillInput>;
+export {};

package/dist/skills/load-tool.js

@@ -0,0 +1,53 @@
+/**
+ * load_skill — how an agent reaches a skill body.
+ *
+ * ⚠️ BEFORE THIS TOOL THERE WAS NO PATH FROM AN AGENT TO A SKILL. Skills were delivered only by
+ * the HOST, when a user typed a slash command; the body arrived as a user message and the model
+ * had no way to ask for one. `canvas_guide` exists precisely as a hand-built escape hatch around
+ * that gap, exposing 8 of ~48 bodies, and its own comment says so. Meanwhile ~30 platform prompts
+ * instruct the model to "use the refine skill" — advice it could only relay to the user.
+ *
+ * Deliberately unlike `load_capability`, which loads a pack and lets the NEXT turn see new tools:
+ * a skill body is content, not capability, so it is returned directly and is usable in the same
+ * turn. Nothing needs to be rebuilt.
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+export function createLoadSkillTool(source) {
+    return defineTool({
+        name: 'load_skill',
+        description: 'Load a skill: returns the full procedure for a task. ' +
+            'See the "Available Skills" section in your instructions for names and what each is for. ' +
+            'Load one when the user asks for something it covers, then follow it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                skill: {
+                    type: 'string',
+                    description: 'Skill name exactly as listed in "Available Skills".',
+                },
+            },
+            required: ['skill'],
+        },
+        execute: (input) => {
+            const { skill } = input;
+            const available = source.available();
+            const found = available.find((s) => s.name === skill);
+            if (!found) {
+                /*
+                  ⚠️ NAME WHAT IS REACHABLE. A bare "not found" leaves the model guessing between "typo",
+                  "not granted to me" and "does not exist" — and the usual recovery from guessing is to
+                  invent a plausible name and try again. The eligible list is short by construction.
+                */
+                const names = available.map((s) => s.name);
+                return Promise.resolve(createErrorResult(names.length === 0
+                    ? `No skills are available to you. Do not retry — proceed without one.`
+                    : `No skill named "${skill}" is available to you. Available: ${names.join(', ')}.`));
+            }
+            source.onLoaded?.(found.name);
+            return Promise.resolve(createSuccessResult({
+                skill: found.name,
+                instructions: found.prompt,
+            }));
+        },
+    });
+}

package/dist/skills/loader.d.ts

@@ -28,3 +28,19 @@ export declare function parseSkillMarkdown(content: string, sourcePath?: string,
  * Returns [] if the directory doesn't exist.
  */
 export declare function loadSkillsFromDir(dir: string, source?: CustomSkill['source'], onWarn?: (msg: string) => void): Promise<CustomSkill[]>;
+/**
+ * Every installed skill an agent could be granted: the user's and the project's, project first.
+ *
+ * ⚠️ PLATFORM SKILLS ARE NOT IN HERE, DELIBERATELY. The 42 shipped prompts are Commands — modes a
+ * user forces (`You are in DESIGN MODE`), not capabilities a model selects. Putting them in the
+ * catalogue would invite the model to load a mode nobody asked for, and would cost catalogue
+ * tokens for 42 entries that are already reachable by typing. See the Commands/Skills split.
+ *
+ * ⚠️ SYNC, BECAUSE AGENT CONSTRUCTION IS. Both hosts build agents inside a factory callback that
+ * is not a good place to await disk I/O on every rebuild. The directories are small and the
+ * result is intended to be cached by the host and refreshed when skills change.
+ *
+ * Project scope wins on a name clash, matching `resolveSkillPrompt`'s precedence — a project can
+ * override a personal skill, and the two hosts must agree about that.
+ */
+export declare function loadInstalledSkills(projectDir?: string): CustomSkill[];

package/dist/skills/loader.js

@@ -11,8 +11,9 @@
  *
  * Spec: /workspace/project-docs/00-requirements/compilr-dev-sdk/custom-skills-spec.md
  */
-import { promises as fs } from 'node:fs';
+import { promises as fs, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getSkillsDir } from './paths.js';
 import { parse as parseYamlReal } from 'yaml';
 /**
  * Parse a SKILL.md string into a CustomSkill.
@@ -131,3 +132,60 @@ function parseYaml(text) {
         return null;
     }
 }
+/**
+ * Every installed skill an agent could be granted: the user's and the project's, project first.
+ *
+ * ⚠️ PLATFORM SKILLS ARE NOT IN HERE, DELIBERATELY. The 42 shipped prompts are Commands — modes a
+ * user forces (`You are in DESIGN MODE`), not capabilities a model selects. Putting them in the
+ * catalogue would invite the model to load a mode nobody asked for, and would cost catalogue
+ * tokens for 42 entries that are already reachable by typing. See the Commands/Skills split.
+ *
+ * ⚠️ SYNC, BECAUSE AGENT CONSTRUCTION IS. Both hosts build agents inside a factory callback that
+ * is not a good place to await disk I/O on every rebuild. The directories are small and the
+ * result is intended to be cached by the host and refreshed when skills change.
+ *
+ * Project scope wins on a name clash, matching `resolveSkillPrompt`'s precedence — a project can
+ * override a personal skill, and the two hosts must agree about that.
+ */
+export function loadInstalledSkills(projectDir) {
+    const seen = new Map();
+    const scopes = projectDir
+        ? [
+            { scope: 'project', dir: projectDir },
+            { scope: 'user', dir: undefined },
+        ]
+        : [{ scope: 'user', dir: undefined }];
+    for (const { scope, dir } of scopes) {
+        for (const skill of loadSkillsFromDirSync(getSkillsDir(scope, dir), scope)) {
+            if (!seen.has(skill.name))
+                seen.set(skill.name, skill);
+        }
+    }
+    return [...seen.values()];
+}
+/** Synchronous sibling of `loadSkillsFromDir`, for the construction path. */
+function loadSkillsFromDirSync(dir, scope) {
+    const source = scope;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return []; // no skills directory is the normal case, not an error
+    }
+    const skills = [];
+    for (const name of entries) {
+        try {
+            const parsed = parseSkillMarkdown(readFileSync(join(dir, name, 'SKILL.md'), 'utf-8'));
+            if (!parsed)
+                continue; // malformed frontmatter — skipped, as the async loader does
+            skills.push({ ...parsed, source, compilr: { ...parsed.compilr, scope } });
+        }
+        catch {
+            continue; // no SKILL.md in this folder
+        }
+    }
+    return skills;
+}

package/dist/skills/resolver.d.ts

@@ -53,3 +53,30 @@ export declare function resolveLayeredSkills(layers: {
  * activation flow and lives at the call site, not here.
  */
 export declare function resolveSkillsForAgent(skills: CustomSkill[], context: SkillEligibilityContext): CustomSkill[];
+/**
+ * Eligibility for a TeamAgent — the one call both hosts make.
+ *
+ * ⚠️ SHARED SO THE HOSTS CANNOT DISAGREE. Desktop and the CLI each own their skill directories
+ * and each build agents through a factory, so each could assemble this context itself — and then
+ * drift, which is how the same skill came to be offered in one host and refused in the other more
+ * than once. Every judgement lives here: which fields of the agent matter, and what an absent
+ * allowlist means.
+ *
+ * ⚠️ `enabledSkills` DOES NOT FOLLOW THE MCP GRANT CONTRACT, and must not be made to. There,
+ * `[]` means "granted nothing" because the field was new. Here both `undefined` and `[]` mean
+ * "unrestricted": the field predates choosable skills, `createCustomAgentDefinition` normalises
+ * `undefined` to `[]`, and every UI that collects it says empty means all. Only a NON-EMPTY list
+ * filters.
+ *
+ * @param pool  every skill installed for this machine/project, unfiltered
+ * @param agent the agent being built — role, id and its allowlist come from here
+ * @param opts  context the agent does not carry: the project type, and the tools it ended up with
+ */
+export declare function resolveSkillsForTeamAgent(pool: CustomSkill[], agent: {
+    id: string;
+    role?: string;
+    enabledSkills?: readonly string[];
+}, opts?: {
+    projectType?: string;
+    toolNames?: readonly string[];
+}): CustomSkill[];

package/dist/skills/resolver.js

@@ -46,7 +46,21 @@ export function resolveLayeredSkills(layers) {
  */
 export function resolveSkillsForAgent(skills, context) {
     const toolSet = context.toolNames instanceof Set ? context.toolNames : new Set(context.toolNames ?? []);
-    const allowlist = context.enabledSkills ? new Set(context.enabledSkills) : null;
+    /*
+      ⚠️ AN EMPTY ALLOWLIST MEANS "UNRESTRICTED", NOT "NOTHING" — the opposite of the MCP grant
+      contract, and deliberately so. `enabledSkills` predates model-choosable skills and already had
+      a meaning, stated in three places: `CustomAgentDefinition.enabledSkills` is documented "Empty =
+      all skills, non-empty = filtered", `createCustomAgentDefinition` normalises `undefined` to `[]`
+      with the same comment, and Desktop's spawn dialog tells the user "Empty = all skills enabled".
+  
+      0.25.0 copied the MCP reading (`[]` = granted nothing) onto this field and inverted it. Because
+      the definition normalises to `[]`, EVERY custom agent ever created carries one — so every one
+      of them silently got no skills at all, having been told empty meant everything.
+  
+      MCP grants could afford the stricter reading because they were new and nothing had a prior
+      meaning. This field is not new. Honour what the UI has been promising.
+    */
+    const allowlist = context.enabledSkills?.length ? new Set(context.enabledSkills) : null;
     return skills.filter((skill) => {
         if (skill.enabled === false)
             return false;
@@ -78,3 +92,31 @@ export function resolveSkillsForAgent(skills, context) {
         return true;
     });
 }
+/**
+ * Eligibility for a TeamAgent — the one call both hosts make.
+ *
+ * ⚠️ SHARED SO THE HOSTS CANNOT DISAGREE. Desktop and the CLI each own their skill directories
+ * and each build agents through a factory, so each could assemble this context itself — and then
+ * drift, which is how the same skill came to be offered in one host and refused in the other more
+ * than once. Every judgement lives here: which fields of the agent matter, and what an absent
+ * allowlist means.
+ *
+ * ⚠️ `enabledSkills` DOES NOT FOLLOW THE MCP GRANT CONTRACT, and must not be made to. There,
+ * `[]` means "granted nothing" because the field was new. Here both `undefined` and `[]` mean
+ * "unrestricted": the field predates choosable skills, `createCustomAgentDefinition` normalises
+ * `undefined` to `[]`, and every UI that collects it says empty means all. Only a NON-EMPTY list
+ * filters.
+ *
+ * @param pool  every skill installed for this machine/project, unfiltered
+ * @param agent the agent being built — role, id and its allowlist come from here
+ * @param opts  context the agent does not carry: the project type, and the tools it ended up with
+ */
+export function resolveSkillsForTeamAgent(pool, agent, opts = {}) {
+    return resolveSkillsForAgent(pool, {
+        role: agent.role,
+        agentId: agent.id,
+        enabledSkills: agent.enabledSkills,
+        projectType: opts.projectType,
+        toolNames: opts.toolNames,
+    });
+}

package/package.json

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