@cuylabs/agent-core 4.8.1 → 4.10.0

package/dist/sandbox/types.d.ts

@@ -0,0 +1,79 @@
+import type { ToolHost } from "../tool/host/types.js";
+/**
+ * Preview endpoint exposed by a managed sandbox environment.
+ */
+export interface SandboxPreview {
+    /** The internal port inside the environment. */
+    port: number;
+    /** Publicly reachable URL for the preview. */
+    url: string;
+    /** Optional user-facing label. */
+    label?: string;
+}
+/**
+ * Snapshot handle returned by a sandbox implementation.
+ */
+export interface SandboxSnapshotResult {
+    /** Provider-specific snapshot identifier. */
+    id: string;
+    /** Optional display label or description. */
+    label?: string;
+    /** Provider-specific metadata for later restore flows. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Metadata describing a managed sandbox session.
+ */
+export interface SandboxSessionMetadata {
+    /** Implementation kind such as "docker", "local", or "cloud". */
+    kind?: string;
+    /** Human-readable label for logs or dashboards. */
+    label?: string;
+    /** Working directory exposed through the embedded ToolHost. */
+    workingDirectory?: string;
+    /** Extra environment details suitable for prompts or UI surfaces. */
+    environmentDetails?: string;
+    /** Preview endpoints exposed by the environment. */
+    previews?: readonly SandboxPreview[];
+    /** Session expiration timestamp when managed by a lease/timeout system. */
+    expiresAt?: number;
+    /** Initial timeout/lease duration in milliseconds. */
+    timeoutMs?: number;
+    /** Provider-specific metadata. */
+    [key: string]: unknown;
+}
+/**
+ * Managed execution environment used by host-backed tools.
+ *
+ * A SandboxSession owns environment lifecycle concerns such as start/stop,
+ * snapshots, timeout extension, and preview URLs, while exposing a `ToolHost`
+ * for the actual file/shell operations tools perform.
+ */
+export interface SandboxSession {
+    /** Stable identifier for the environment session. */
+    readonly id: string;
+    /** Tool execution surface exposed by the environment. */
+    readonly host: ToolHost;
+    /** Optional metadata about the environment. */
+    readonly metadata?: SandboxSessionMetadata;
+    /** Stop and clean up the environment. */
+    stop(): Promise<void>;
+    /** Create a restorable snapshot when supported by the provider. */
+    snapshot?(): Promise<SandboxSnapshotResult>;
+    /** Extend the environment lease/timeout when supported. */
+    extendTimeout?(additionalMs: number): Promise<{
+        expiresAt: number;
+    } | void>;
+    /** Return a preview URL for an exposed port when supported. */
+    getPreviewUrl?(port: number): string | undefined;
+}
+/**
+ * Factory/connector surface for sandbox implementations.
+ *
+ * Providers may support only `connect`, only `create`, or both.
+ */
+export interface SandboxProvider<TConnectOptions = unknown, TCreateOptions = TConnectOptions> {
+    connect?(options: TConnectOptions): Promise<SandboxSession>;
+    create?(options: TCreateOptions): Promise<SandboxSession>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sandbox/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sandbox/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAC3C,yCAAyC;IACzC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5C,2DAA2D;IAC3D,aAAa,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAC5E,+DAA+D;IAC/D,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAClD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAC9B,eAAe,GAAG,OAAO,EACzB,cAAc,GAAG,eAAe;IAEhC,OAAO,CAAC,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,MAAM,CAAC,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC3D"}

package/dist/skill/discovery/constants.d.ts

@@ -0,0 +1,6 @@
+import type { SkillScope } from "../types.js";
+export declare const DEFAULT_EXTERNAL_DIRS: string[];
+export declare const DEFAULT_MAX_SCAN_DEPTH = 4;
+export declare const MAX_SKILLS_PER_ROOT = 500;
+export declare const SCOPE_PRIORITY: Record<SkillScope, number>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/skill/discovery/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/skill/discovery/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,qBAAqB,UAAyB,CAAC;AAC5D,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAKrD,CAAC"}

package/dist/skill/discovery/dedupe.d.ts

@@ -0,0 +1,3 @@
+import type { SkillMetadata } from "../types.js";
+export declare function deduplicateSkills(skills: SkillMetadata[]): SkillMetadata[];
+//# sourceMappingURL=dedupe.d.ts.map

package/dist/skill/discovery/dedupe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedupe.d.ts","sourceRoot":"","sources":["../../../src/skill/discovery/dedupe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAqB1E"}

package/dist/skill/discovery/discover.d.ts

@@ -0,0 +1,3 @@
+import type { SkillConfig, SkillDiscoveryResult } from "../types.js";
+export declare function discoverSkills(cwd: string, config?: SkillConfig): Promise<SkillDiscoveryResult>;
+//# sourceMappingURL=discover.d.ts.map

package/dist/skill/discovery/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../../src/skill/discovery/discover.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,WAAW,EAEX,oBAAoB,EAErB,MAAM,aAAa,CAAC;AAQrB,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAiE/B"}

package/dist/skill/discovery/fs.d.ts

@@ -0,0 +1,4 @@
+export declare function dirExists(path: string): Promise<boolean>;
+export declare function findGitRoot(startDir: string): Promise<string | undefined>;
+export declare function dirsBetween(from: string, to: string): string[];
+//# sourceMappingURL=fs.d.ts.map

package/dist/skill/discovery/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../../src/skill/discovery/fs.ts"],"names":[],"mappings":"AAGA,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO9D;AAED,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgB7B;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAkB9D"}

package/dist/skill/discovery/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Skill discovery across configured roots and scope-based precedence.
+ */
+export { DEFAULT_EXTERNAL_DIRS, DEFAULT_MAX_SCAN_DEPTH } from "./constants.js";
+export { discoverSkills } from "./discover.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/skill/discovery/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/skill/discovery/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/skill/discovery/scan.d.ts

@@ -0,0 +1,3 @@
+import type { DiscoveryRoot, ScanRootResult } from "./types.js";
+export declare function scanRoot(root: DiscoveryRoot, maxDepth: number, maxFileSize?: number): Promise<ScanRootResult>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/skill/discovery/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../../src/skill/discovery/scan.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEhE,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,GAAE,MAA+B,GAC3C,OAAO,CAAC,cAAc,CAAC,CA4DzB"}

package/dist/skill/discovery/types.d.ts

@@ -0,0 +1,15 @@
+import type { SkillMetadata, SkillScope, SkillSource } from "../types.js";
+export interface DiscoveryRoot {
+    path: string;
+    scope: SkillScope;
+    source: SkillSource;
+}
+export interface ScanRootResult {
+    skills: SkillMetadata[];
+    errors: Array<{
+        path: string;
+        reason: string;
+    }>;
+    dirsScanned: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/skill/discovery/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/skill/discovery/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/skill/index.d.ts

@@ -1,110 +1,88 @@
-import { cL as SkillScope, cM as SkillSource, cH as SkillMetadata, cK as SkillResourceType, cJ as SkillResource, cE as SkillContent, cD as SkillConfig, cG as SkillDiscoveryResult, cI as SkillRegistry, T as Tool } from '../instance-Bg61WSyz.js';
-export { ci as RemoteSkillEntry, cj as RemoteSkillIndex, cF as SkillDiscoveryError, cN as SkillSourceType, dU as createSkillRegistry, dW as emptySkillRegistry } from '../instance-Bg61WSyz.js';
-import '../types-C_LCeYNg.js';
-import 'ai';
-import '../types-RSCv7nQ4.js';
-import 'zod';
-import '../types-CQaXbRsS.js';
-import '../types-DMjoFKKv.js';
-import '@modelcontextprotocol/sdk/client/auth.js';
-import '@modelcontextprotocol/sdk/types.js';
-import '@ai-sdk/provider-utils';
-import '../sandbox/index.js';
-import '../llm-error-D93FNNLY.js';
-
-declare const SKILL_FILENAME = "SKILL.md";
-declare const DEFAULT_SKILL_MAX_SIZE = 102400;
-
-declare function parseFrontmatter(raw: string): {
-    data: Record<string, unknown>;
-    body: string;
-};
-
-declare function loadSkillMetadata(filePath: string, scope: SkillScope, source: SkillSource, maxSize: number): Promise<SkillMetadata | null>;
-
-declare function loadSkillContent(metadata: SkillMetadata): Promise<SkillContent>;
-declare function loadResourceContent(resource: SkillResource): Promise<string>;
-declare function inferResourceType(filePath: string): SkillResourceType;
-
-declare const DEFAULT_EXTERNAL_DIRS: string[];
-declare const DEFAULT_MAX_SCAN_DEPTH = 4;
-
-declare function discoverSkills(cwd: string, config?: SkillConfig): Promise<SkillDiscoveryResult>;
-
 /**
- * Skill Tools — built-in tools for agent-initiated skill loading
+ * Skill System — modular, on-demand knowledge packs for agents
  *
- * Provides two tools that enable the agent to activate skills on demand:
+ * Skills extend an agent's capabilities with specialized instructions,
+ * workflows, scripts, and reference material. They use a three-level
+ * progressive disclosure model for efficient context usage:
  *
- * 1. **`skill`** — Load a skill's full instructions (L2).
- *    The agent calls this when it recognizes a task matching a skill's
- *    description. Returns the complete skill body with resource listings.
+ * - **L1 (Summary)**: Name + description always in system prompt (~100 words each)
+ * - **L2 (Content)**: Full SKILL.md body loaded when agent calls the `skill` tool
+ * - **L3 (Resources)**: Bundled scripts/references loaded via `skill_resource` tool
  *
- * 2. **`skill_resource`** — Read a specific bundled resource (L3).
- *    After loading a skill, the agent can read scripts, references,
- *    examples, or assets bundled with it.
+ * ## Quick Start
  *
- * These tools expose skills as regular tools the agent can call,
- * using progressive disclosure so context is used efficiently.
- *
- * The tool descriptions are dynamic — they list all available skill names
- * and descriptions so the agent knows what's available without needing
- * a separate discovery step.
- *
- * @example
  * ```typescript
- * import { createSkillTools, createSkillRegistry } from "@cuylabs/agent-core";
+ * import {
+ *   createSkillRegistry,
+ *   createSkillTools,
+ *   createAgent,
+ *   PRIORITY_SKILLS,
+ * } from "@cuylabs/agent-core";
+ *
+ * // 1. Discover skills from project, user, and global directories
+ * const registry = await createSkillRegistry(process.cwd(), {
+ *   externalDirs: [".agents", ".claude"],  // scan these convention dirs
+ * });
  *
- * const registry = await createSkillRegistry(cwd, skillConfig);
- * const tools = createSkillTools(registry);
+ * // 2. Create skill tools for the agent
+ * const skillTools = createSkillTools(registry);
+ *
+ * // 3. Inject skill summary into the prompt pipeline
+ * const builder = createPromptBuilder({ includeInstructions: true });
+ * builder.addSection({
+ *   id: "skills",
+ *   label: "Available Skills",
+ *   content: registry.formatSummary(),
+ *   priority: PRIORITY_SKILLS,
+ * });
  *
+ * // 4. Create agent with skill tools
  * const agent = createAgent({
  *   model: anthropic("claude-sonnet-4-20250514"),
- *   tools: [...myTools, ...tools],
+ *   tools: [...codeTools, ...skillTools],
  * });
  * ```
- */
-
-/**
- * Create the built-in `skill` tool that lets the agent load skill instructions.
  *
- * The tool's description is dynamically generated to include all available
- * skill names and summaries, so the agent knows exactly what's available.
+ * ## Skill File Format (SKILL.md)
  *
- * @param registry The skill registry to load from
- * @returns A Tool.Info for the `skill` tool
- */
-declare function createSkillTool(registry: SkillRegistry): Tool.AnyInfo;
-/**
- * Create the built-in `skill_resource` tool for reading bundled files.
+ * ```markdown
+ * ---
+ * name: testing
+ * description: Write comprehensive test suites with vitest...
+ * version: 1.0.0
+ * tags: [testing, vitest]
+ * dependencies: [typescript-patterns]
+ * ---
  *
- * This is the L3 layer — the agent calls this to read specific scripts,
- * references, examples, or assets bundled with a skill.
+ * # Testing Skill
  *
- * @param registry The skill registry to load from
- * @returns A Tool.Info for the `skill_resource` tool
- */
-declare function createSkillResourceTool(registry: SkillRegistry): Tool.AnyInfo;
-/**
- * Create both skill tools (skill + skill_resource) for an agent.
+ * Instructions for the agent go here...
+ * ```
  *
- * Returns an empty array if the registry has no skills, so the tools
- * don't clutter the agent's tool list when skills aren't in use.
+ * ## Directory Structure
  *
- * @param registry The skill registry
- * @returns Array of Tool.AnyInfo (0 or 2 tools)
+ * ```
+ * .agents/skills/          (or .claude/skills/)
+ *   testing/
+ *     SKILL.md             ← Required: frontmatter + instructions
+ *     scripts/             ← Optional: executable helpers
+ *     references/          ← Optional: docs loaded on demand
+ *     assets/              ← Optional: templates, configs
+ *     examples/            ← Optional: working code samples
+ * ```
  *
- * @example
- * ```typescript
- * const registry = await createSkillRegistry(cwd, config);
- * const skillTools = createSkillTools(registry);
+ * ## Discovery Hierarchy
  *
- * const agent = createAgent({
- *   model: myModel,
- *   tools: [...codeTools, ...skillTools],
- * });
- * ```
+ * Skills are discovered from multiple roots with scope-based priority:
+ *   project > user > global > builtin
+ *
+ * When two skills share the same name, the narrower scope wins.
+ *
+ * @packageDocumentation
  */
-declare function createSkillTools(registry: SkillRegistry): Tool.AnyInfo[];
-
-export { DEFAULT_EXTERNAL_DIRS, DEFAULT_MAX_SCAN_DEPTH, DEFAULT_SKILL_MAX_SIZE, SKILL_FILENAME, SkillConfig, SkillContent, SkillDiscoveryResult, SkillMetadata, SkillRegistry, SkillResource, SkillResourceType, SkillScope, SkillSource, createSkillResourceTool, createSkillTool, createSkillTools, discoverSkills, inferResourceType, loadResourceContent, loadSkillContent, loadSkillMetadata, parseFrontmatter };
+export type { SkillScope, SkillSourceType, SkillSource, SkillResourceType, SkillResource, SkillMetadata, SkillContent, SkillConfig, RemoteSkillIndex, RemoteSkillEntry, SkillDiscoveryResult, SkillDiscoveryError, } from "./types.js";
+export { SKILL_FILENAME, DEFAULT_SKILL_MAX_SIZE, parseFrontmatter, loadSkillMetadata, loadSkillContent, loadResourceContent, inferResourceType, } from "./loader/index.js";
+export { DEFAULT_EXTERNAL_DIRS, DEFAULT_MAX_SCAN_DEPTH, discoverSkills, } from "./discovery/index.js";
+export { SkillRegistry, createSkillRegistry, emptySkillRegistry, } from "./registry.js";
+export { createSkillTool, createSkillResourceTool, createSkillTools, } from "./tools.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/skill/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skill/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AAGH,YAAY,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/skill/index.js

@@ -2,7 +2,7 @@ import {
   createSkillResourceTool,
   createSkillTool,
   createSkillTools
-} from "../chunk-CSR75JVC.js";
+} from "../chunk-ASXF5AC6.js";
 import {
   DEFAULT_EXTERNAL_DIRS,
   DEFAULT_MAX_SCAN_DEPTH,
@@ -18,7 +18,7 @@ import {
   loadSkillMetadata,
   parseFrontmatter
 } from "../chunk-I7EJGKUP.js";
-import "../chunk-Q742PSH3.js";
+import "../chunk-MJML3A2F.js";
 export {
   DEFAULT_EXTERNAL_DIRS,
   DEFAULT_MAX_SCAN_DEPTH,

package/dist/skill/loader/constants.d.ts

@@ -0,0 +1,5 @@
+import type { SkillResourceType } from "../types.js";
+export declare const SKILL_FILENAME = "SKILL.md";
+export declare const DEFAULT_SKILL_MAX_SIZE = 102400;
+export declare const RESOURCE_DIRS: Record<string, SkillResourceType>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/skill/loader/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/skill/loader/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD,eAAO,MAAM,cAAc,aAAa,CAAC;AACzC,eAAO,MAAM,sBAAsB,SAAU,CAAC;AAE9C,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAK3D,CAAC"}

package/dist/skill/loader/frontmatter.d.ts

@@ -0,0 +1,5 @@
+export declare function parseFrontmatter(raw: string): {
+    data: Record<string, unknown>;
+    body: string;
+};
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/skill/loader/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../../src/skill/loader/frontmatter.ts"],"names":[],"mappings":"AAAA,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC7C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd,CAoEA"}

package/dist/skill/loader/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Skill loading helpers for frontmatter, metadata, and bundled resources.
+ */
+export { DEFAULT_SKILL_MAX_SIZE, SKILL_FILENAME } from "./constants.js";
+export { parseFrontmatter } from "./frontmatter.js";
+export { loadSkillMetadata } from "./metadata.js";
+export { inferResourceType, loadResourceContent, loadSkillContent, } from "./resources.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/skill/loader/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/skill/loader/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC"}

package/dist/skill/loader/metadata.d.ts

@@ -0,0 +1,3 @@
+import type { SkillMetadata, SkillScope, SkillSource } from "../types.js";
+export declare function loadSkillMetadata(filePath: string, scope: SkillScope, source: SkillSource, maxSize: number): Promise<SkillMetadata | null>;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/skill/loader/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../../src/skill/loader/metadata.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1E,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CA6B/B"}

package/dist/skill/loader/resources.d.ts

@@ -0,0 +1,5 @@
+import type { SkillContent, SkillMetadata, SkillResource, SkillResourceType } from "../types.js";
+export declare function loadSkillContent(metadata: SkillMetadata): Promise<SkillContent>;
+export declare function loadResourceContent(resource: SkillResource): Promise<string>;
+export declare function inferResourceType(filePath: string): SkillResourceType;
+//# sourceMappingURL=resources.d.ts.map

package/dist/skill/loader/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../../src/skill/loader/resources.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAIrB,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAiBvB;AAED,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,MAAM,CAAC,CAWjB;AA4DD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAkBrE"}

package/dist/skill/registry.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Skill Registry — in-memory store for discovered skills
+ *
+ * The registry is the central coordination point for the skill system.
+ * It holds discovered metadata (L1), handles on-demand content loading
+ * (L2/L3), provides the prompt summary for injection, and manages
+ * the lifecycle of skill state.
+ *
+ * ```
+ *   discoverSkills() → SkillRegistry → promptSummary (L1 → system prompt)
+ *                                     → loadSkill()   (L2 → tool response)
+ *                                     → loadResource  (L3 → tool response)
+ * ```
+ *
+ * The registry is designed to be created once per agent and shared
+ * across the agent's lifetime, including across forked sub-agents.
+ *
+ * @example
+ * ```typescript
+ * const registry = await createSkillRegistry("/path/to/project", {
+ *   externalDirs: [".agents", ".claude"],
+ * });
+ *
+ * // L1: summary goes into system prompt
+ * const summary = registry.formatSummary();
+ *
+ * // L2: agent calls skill tool → full content loaded
+ * const content = await registry.loadContent("testing");
+ *
+ * // L3: agent reads a bundled reference
+ * const ref = await registry.loadResource("testing", "references/patterns.md");
+ * ```
+ */
+import type { SkillMetadata, SkillContent, SkillConfig, SkillDiscoveryResult, SkillResource } from "./types.js";
+/**
+ * In-memory registry of discovered skills with lazy content loading.
+ *
+ * Holds L1 metadata for all skills. Content (L2) and resources (L3)
+ * are loaded on demand and cached for the registry's lifetime.
+ */
+export declare class SkillRegistry {
+    /** All discovered skill metadata indexed by name */
+    private readonly skills;
+    /** Cached full content for skills that have been loaded */
+    private readonly contentCache;
+    /** Discovery metadata */
+    readonly discoveryResult: SkillDiscoveryResult;
+    constructor(discoveryResult: SkillDiscoveryResult);
+    /** Get a skill's metadata by name. Returns undefined if not found. */
+    get(name: string): SkillMetadata | undefined;
+    /** Check if a skill exists by name. */
+    has(name: string): boolean;
+    /** Get all skill metadata entries. */
+    list(): SkillMetadata[];
+    /** Number of registered skills. */
+    get size(): number;
+    /** Skill names as an array. */
+    get names(): string[];
+    /**
+     * Load a skill's full content (L2: body + resource listing).
+     *
+     * Results are cached — subsequent calls return the cached content
+     * without re-reading the filesystem.
+     *
+     * @param name Skill name
+     * @returns Full skill content, or null if the skill doesn't exist
+     */
+    loadContent(name: string): Promise<SkillContent | null>;
+    /**
+     * Load a specific bundled resource from a skill (L3).
+     *
+     * The skill's content must be loaded first (via `loadContent`)
+     * so the resource listing is available.
+     *
+     * @param skillName  Skill name
+     * @param relativePath  Relative path to the resource within the skill dir
+     * @returns Resource file content as UTF-8 string
+     * @throws If the skill or resource doesn't exist
+     */
+    loadResource(skillName: string, relativePath: string): Promise<string>;
+    /**
+     * Get the list of resources for a loaded skill.
+     *
+     * @param name Skill name
+     * @returns Resource list, or empty array if skill isn't loaded yet
+     */
+    getResources(name: string): SkillResource[];
+    /**
+     * Format a summary of all available skills for injection into the system prompt.
+     *
+     * This is the L1 layer — the agent sees names and descriptions of all
+     * available skills, enabling it to decide which to activate via tool calls.
+     *
+     * The output format uses XML tags (consistent with the instruction format
+     * in `formatInstructions`) for clear delineation in the prompt.
+     *
+     * Returns empty string if no skills are available.
+     *
+     * @example Output:
+     * ```xml
+     * <available-skills>
+     *
+     * You have access to the following skills. To activate a skill and load its
+     * full instructions, call the `skill` tool with the skill's name.
+     *
+     * <skill name="testing" scope="project">
+     * Write comprehensive test suites with vitest, covering unit, integration,
+     * and snapshot testing patterns.
+     * </skill>
+     *
+     * <skill name="frontend-design" scope="user">
+     * Create distinctive, production-grade frontend interfaces with high design quality.
+     * </skill>
+     *
+     * </available-skills>
+     * ```
+     */
+    formatSummary(): string;
+    /**
+     * Format the full content of a loaded skill for a tool response.
+     *
+     * Wraps the skill body in XML with metadata, and lists bundled resources
+     * so the agent knows what's available at L3.
+     *
+     * @param content Previously loaded skill content
+     * @returns Formatted string for tool response
+     */
+    formatContent(content: SkillContent): string;
+    /**
+     * Register an externally defined skill with optional pre-loaded content.
+     *
+     * Intended for capability packs that contribute skills without placing
+     * files on disk — the pack's inline body is stored directly in the
+     * content cache so the agent can load it without a file read.
+     *
+     * **Priority:** registered skills have lower priority than discovered
+     * skills. If a skill with the same name was already found during
+     * discovery, the discovered skill wins and this call is a no-op.
+     *
+     * @param metadata  L1 metadata describing the skill.
+     * @param content   Pre-built content (L2). When provided, this is stored
+     *                  in the cache so `loadContent()` never reads a file.
+     */
+    register(metadata: SkillMetadata, content?: SkillContent): "registered" | "updated" | "skipped";
+    /** Clear the content cache, forcing reloads on next access. */
+    clearContentCache(): void;
+    /** Check if a skill's content has been loaded and cached. */
+    isContentLoaded(name: string): boolean;
+}
+/**
+ * Create a skill registry by discovering all available skills.
+ *
+ * This is the recommended way to initialize the skill system.
+ * It runs discovery, deduplicates by scope priority, and returns
+ * a ready-to-use registry.
+ *
+ * @param cwd     Current working directory
+ * @param config  Skill configuration
+ * @returns A populated SkillRegistry
+ *
+ * @example
+ * ```typescript
+ * const registry = await createSkillRegistry("/path/to/project", {
+ *   externalDirs: [".agents", ".claude"],
+ *   roots: ["./company-skills"],
+ * });
+ *
+ * console.log(`Found ${registry.size} skills`);
+ * console.log(registry.formatSummary());
+ * ```
+ */
+export declare function createSkillRegistry(cwd: string, config?: SkillConfig): Promise<SkillRegistry>;
+/**
+ * Create an empty skill registry (for agents that don't use skills).
+ */
+export declare function emptySkillRegistry(): SkillRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/skill/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/skill/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,oBAAoB,EACpB,aAAa,EACd,MAAM,YAAY,CAAC;AAQpB;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,oDAAoD;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IAEpD,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA4B;IAEzD,yBAAyB;IACzB,QAAQ,CAAC,eAAe,EAAE,oBAAoB,CAAC;gBAEnC,eAAe,EAAE,oBAAoB;IAcjD,sEAAsE;IACtE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI5C,uCAAuC;IACvC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,sCAAsC;IACtC,IAAI,IAAI,aAAa,EAAE;IAIvB,mCAAmC;IACnC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,+BAA+B;IAC/B,IAAI,KAAK,IAAI,MAAM,EAAE,CAEpB;IAMD;;;;;;;;OAQG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAa7D;;;;;;;;;;OAUG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB5E;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE;IAQ3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,aAAa,IAAI,MAAM;IAiCvB;;;;;;;;OAQG;IACH,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM;IAyD5C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CACN,QAAQ,EAAE,aAAa,EACvB,OAAO,CAAC,EAAE,YAAY,GACrB,YAAY,GAAG,SAAS,GAAG,SAAS;IA+BvC,+DAA+D;IAC/D,iBAAiB,IAAI,IAAI;IAIzB,6DAA6D;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAGvC;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAGxB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,aAAa,CAOlD"}