@cuylabs/agent-capability-pack 0.13.0

package/dist/pack/index.d.ts

@@ -0,0 +1,207 @@
+import { b as CapabilityPack, d as PackRef } from '../types-BdapSdPT.js';
+export { C as CAPABILITY_PACK_KIND, a as CAPABILITY_PACK_SCHEMA_VERSION, P as PackAuthor, c as PackMeta, e as PackSkill, f as PackSkillResource, h as PackSkillResourceType } from '../types-BdapSdPT.js';
+import { MCPConfig } from '@cuylabs/agent-core/mcp';
+import { SkillRegistry } from '@cuylabs/agent-core/skill';
+import { PluginRegistry } from '@cuylabs/agent-core/plugin';
+
+/**
+ * defineCapabilityPack — ergonomic authoring helper.
+ *
+ * Returns the pack with default manifest metadata filled in. The value lies in
+ * IDE completion, type narrowing, and the ability to statically inspect packs
+ * without executing them.
+ */
+
+/**
+ * Define a capability pack with full type checking.
+ *
+ * This is the canonical way to author a pack inline or in an npm package.
+ * The function preserves your pack shape and fills default manifest metadata
+ * when `kind` or `schemaVersion` are omitted.
+ *
+ * @example
+ * ```ts
+ * // my-pack.ts
+ * import { defineCapabilityPack } from "@cuylabs/agent-capability-pack"
+ *
+ * export default defineCapabilityPack({
+ *   id: "my-pack",
+ *   name: "My Pack",
+ *   version: "1.0.0",
+ *   skills: [{
+ *     name: "my-skill",
+ *     description: "Handles X when the task involves Y.",
+ *     body: "# My Skill\n\nInstructions...",
+ *   }],
+ * })
+ * ```
+ */
+declare function defineCapabilityPack(pack: CapabilityPack): CapabilityPack;
+
+/**
+ * Pack load result types.
+ */
+
+/**
+ * Outcome of loading a single `CapabilityPack`.
+ */
+interface PackItemResult {
+    /** Pack ID from the pack's metadata. */
+    packId: string;
+    /** Number of skills successfully registered or updated in the SkillRegistry. */
+    skillsRegistered: number;
+    /**
+     * Names of MCP servers contributed by this pack.
+     *
+     * The actual configs are aggregated in `PackLoadResult.mcpServers`.
+     */
+    mcpServerNames: string[];
+    /** Whether a plugin from this pack was loaded into the PluginRegistry. */
+    pluginLoaded: boolean;
+    /**
+     * Error message if this pack failed to load.
+     *
+     * A failed pack does not block other packs — the loader continues.
+     * Check `PackLoadResult.failed` to surface errors to the user.
+     */
+    error?: string;
+}
+/**
+ * Aggregate result of loading all packs via `PackLoader.loadAll()`.
+ */
+interface PackLoadResult {
+    /** Packs that were loaded without errors. */
+    loaded: PackItemResult[];
+    /**
+     * Packs that failed to resolve or load.
+     *
+     * Each entry includes the error message. The host can decide whether to
+     * surface these as warnings or treat them as fatal.
+     */
+    failed: PackItemResult[];
+    /**
+     * All MCP server configurations aggregated from every successfully loaded pack.
+     *
+     * Merge this into your own `MCPConfig` before constructing the `MCPManager`:
+     *
+     * ```ts
+     * const result = await loader.loadAll(packs)
+     * const mcpManager = createMCPManager({
+     *   ...myServers,
+     *   ...result.mcpServers,
+     * })
+     * await mcpManager.connect()
+     * ```
+     *
+     * When multiple packs contribute a server with the same name, the last
+     * pack in load order wins (same behavior as `Object.assign`).
+     */
+    mcpServers: MCPConfig;
+}
+
+/**
+ * PackLoader — bridges CapabilityPacks into agent-core subsystems.
+ *
+ * The loader is the orchestration layer between the pack distribution
+ * format and the three runtime systems it feeds:
+ *
+ *   pack.skills     → SkillRegistry.register()
+ *   pack.mcpServers → returned in PackLoadResult for host to merge
+ *   pack.plugin     → PluginRegistry.loadOne()
+ *
+ * MCP server configs are not applied directly to an MCPManager because
+ * the manager must receive all its server configs before `connect()` is
+ * called. The host merges `result.mcpServers` into its own config and
+ * constructs the manager — this preserves the manager's contract.
+ *
+ * @example
+ * ```ts
+ * import { PackLoader } from "@cuylabs/agent-capability-pack"
+ * import { createSkillRegistry } from "@cuylabs/agent-core"
+ * import { createMCPManager } from "@cuylabs/agent-core/mcp"
+ * import { PluginRegistry } from "@cuylabs/agent-core/plugin"
+ *
+ * const skillRegistry  = await createSkillRegistry(cwd)
+ * const pluginRegistry = new PluginRegistry()
+ *
+ * const loader = new PackLoader({ skillRegistry, pluginRegistry, cwd })
+ * const result = await loader.loadAll([
+ *   { source: "inline", pack: myPack },
+ *   { source: "npm",    package: "@myorg/agent-pack" },
+ *   { source: "local",  path: "./packs/company-tools" },
+ * ])
+ *
+ * // Merge pack-contributed servers with your own before connecting
+ * const mcpManager = createMCPManager({ ...myServers, ...result.mcpServers })
+ * await mcpManager.connect()
+ * ```
+ */
+
+interface PackLoaderOptions {
+    /**
+     * The skill registry that pack skills are registered into.
+     *
+     * Skills contributed by a pack have "global" scope and lose to any
+     * project- or user-scoped skill with the same name (scoped skills win).
+     */
+    skillRegistry: SkillRegistry;
+    /**
+     * Optional plugin registry for loading pack plugin contributions.
+     *
+     * When omitted, plugin contributions from packs are silently ignored.
+     * Provide a `PluginRegistry` instance if your agent uses the plugin system.
+     */
+    pluginRegistry?: PluginRegistry;
+    /**
+     * Working directory passed to the plugin registry when loading pack plugins.
+     *
+     * Defaults to `process.cwd()`.
+     */
+    cwd?: string;
+}
+/**
+ * Loads capability packs into agent-core subsystems.
+ *
+ * Accepts both resolved `CapabilityPack` objects and unresolved `PackRef`
+ * references. Refs are resolved before loading; resolution errors are
+ * reported in `PackLoadResult.failed` rather than throwing.
+ *
+ * The loader is non-throwing by default: individual pack failures are
+ * collected and returned so the agent can start with whatever capabilities
+ * loaded successfully.
+ */
+declare class PackLoader {
+    private readonly skillRegistry;
+    private readonly pluginRegistry;
+    private readonly cwd;
+    constructor(options: PackLoaderOptions);
+    /**
+     * Load multiple packs in order.
+     *
+     * Accepts a mix of resolved `CapabilityPack` objects and `PackRef`
+     * references. Each item is processed sequentially; one failure does not
+     * block the rest.
+     *
+     * @returns Aggregate result with per-pack outcomes and collected MCP configs.
+     */
+    loadAll(items: ReadonlyArray<CapabilityPack | PackRef>): Promise<PackLoadResult>;
+    /**
+     * Load a single resolved `CapabilityPack`.
+     *
+     * Stages pack content before mutating the runtime registries. Plugins are
+     * loaded first; only successful packs contribute skills and MCP configs.
+     */
+    loadOne(pack: CapabilityPack): Promise<PackItemResult>;
+    /**
+     * Convert a `PackSkill` into `SkillMetadata` + `SkillContent` and register
+     * both in the skill registry so the agent can discover (L1) and load (L2)
+     * the skill without any file reads.
+     *
+     * Discovered skills (project / user scope) always win if a skill with the
+     * same name already exists — see `SkillRegistry.register()`.
+     */
+    private preparePackSkill;
+    private loadPluginContribution;
+}
+
+export { CapabilityPack, type PackItemResult, type PackLoadResult, PackLoader, type PackLoaderOptions, defineCapabilityPack };

package/dist/pack/index.js

@@ -0,0 +1,15 @@
+import {
+  PackLoader,
+  defineCapabilityPack
+} from "../chunk-IUGGMU63.js";
+import {
+  CAPABILITY_PACK_KIND,
+  CAPABILITY_PACK_SCHEMA_VERSION
+} from "../chunk-5E66GFAI.js";
+export {
+  CAPABILITY_PACK_KIND,
+  CAPABILITY_PACK_SCHEMA_VERSION,
+  PackLoader,
+  defineCapabilityPack
+};
+//# sourceMappingURL=index.js.map

package/dist/pack/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/sources/index.d.ts

@@ -0,0 +1,20 @@
+import { d as PackRef, b as CapabilityPack } from '../types-BdapSdPT.js';
+export { G as GitPackRef, I as InlinePackRef, L as LocalPackRef, N as NpmPackRef, U as UrlPackRef, g as gitPack, i as inlinePack, l as localPack, n as npmPack, u as urlPack } from '../types-BdapSdPT.js';
+import '@cuylabs/agent-core/mcp';
+import '@cuylabs/agent-core/plugin';
+
+/**
+ * resolvePackRef — unified entry point for resolving any PackRef.
+ */
+
+/**
+ * Resolve a `PackRef` to a `CapabilityPack`.
+ *
+ * Dispatches to the appropriate resolver based on `ref.source`.
+ * Throws if resolution fails (network error, missing file, bad manifest, etc.).
+ *
+ * @throws {Error} Resolution failed — details in the error message.
+ */
+declare function resolvePackRef(ref: PackRef): Promise<CapabilityPack>;
+
+export { PackRef, resolvePackRef };

package/dist/sources/index.js

@@ -0,0 +1,19 @@
+import {
+  gitPack,
+  inlinePack,
+  localPack,
+  npmPack,
+  urlPack
+} from "../chunk-2TICMDUA.js";
+import {
+  resolvePackRef
+} from "../chunk-5E66GFAI.js";
+export {
+  gitPack,
+  inlinePack,
+  localPack,
+  npmPack,
+  resolvePackRef,
+  urlPack
+};
+//# sourceMappingURL=index.js.map

package/dist/sources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types-BdapSdPT.d.ts

@@ -0,0 +1,325 @@
+import { MCPServerConfig } from '@cuylabs/agent-core/mcp';
+import { PluginDefinition, PluginInit } from '@cuylabs/agent-core/plugin';
+
+/**
+ * Capability Pack — core types.
+ *
+ * A CapabilityPack is the distributable unit of agent capabilities.
+ * It bundles any combination of skills, MCP server configurations,
+ * and plugin contributions into a single, composable object.
+ *
+ * Packs are source-agnostic by design: whether a pack was authored
+ * inline, loaded from an npm package, fetched from a URL, or read
+ * from a local directory, it always resolves to this same shape.
+ * The PackLoader feeds it into the agent-core subsystems.
+ *
+ * @packageDocumentation
+ */
+
+/** Marker value for JSON-backed pack manifests. */
+declare const CAPABILITY_PACK_KIND = "agent-capability-pack";
+/** Current JSON manifest schema version for capability packs. */
+declare const CAPABILITY_PACK_SCHEMA_VERSION = 1;
+/** Author information for a capability pack. */
+interface PackAuthor {
+    /** Display name of the author or organization. */
+    name: string;
+    /** Author website or GitHub profile URL. */
+    url?: string;
+    /** Contact email. */
+    email?: string;
+}
+/**
+ * Identifying metadata for a capability pack.
+ *
+ * These fields are shared by both `CapabilityPack` and pack manifest
+ * files on disk (`pack.json`).
+ */
+interface PackMeta {
+    /** Optional manifest kind marker for JSON-backed packs. */
+    kind?: typeof CAPABILITY_PACK_KIND;
+    /** Optional manifest schema version for JSON-backed packs. */
+    schemaVersion?: typeof CAPABILITY_PACK_SCHEMA_VERSION;
+    /**
+     * Unique pack identifier. Used for namespacing, deduplication, and logging.
+     * Should be kebab-case (e.g. "my-company-tools").
+     */
+    id: string;
+    /** Human-readable display name. */
+    name?: string;
+    /** Brief description of what this pack provides. */
+    description?: string;
+    /** SemVer version string. */
+    version?: string;
+    /** Author or owning organization. */
+    author?: PackAuthor;
+}
+/** Resource type classification — mirrors `SkillResourceType` from agent-core. */
+type PackSkillResourceType = "script" | "reference" | "asset" | "example";
+/**
+ * A bundled resource included with a pack skill.
+ *
+ * Resources are listed in L2 (skill content) so the agent knows
+ * what is available, and loaded on demand in L3 via the `skill_resource` tool.
+ *
+ * For programmatically defined packs, provide `content` directly.
+ * For local packs resolved from disk, `absolutePath` is set by the resolver.
+ * At least one of `content` or `absolutePath` must be set.
+ */
+interface PackSkillResource {
+    /** Path relative to the skill directory. Used by the agent to request the resource. */
+    relativePath: string;
+    /** Resource classification. */
+    type: PackSkillResourceType;
+    /**
+     * Inline resource content.
+     *
+     * Takes precedence over `absolutePath` when both are present.
+     * Use this for programmatically defined packs.
+     */
+    content?: string;
+    /**
+     * Absolute filesystem path to the resource file.
+     *
+     * Set by the local pack resolver for on-disk resources.
+     * The content is loaded lazily when the agent calls `skill_resource`.
+     */
+    absolutePath?: string;
+}
+/**
+ * An inline skill definition inside a CapabilityPack.
+ *
+ * Carries the skill's name, description (L1), and full instruction body (L2)
+ * so no file read is needed at runtime. When registered via `PackLoader`,
+ * both the metadata and content are available immediately.
+ *
+ * ## Authoring
+ *
+ * The `description` field is the most important: the agent reads it to decide
+ * whether to activate this skill. Write it as trigger phrases for task types,
+ * not as prose for humans.
+ *
+ * @example
+ * ```ts
+ * {
+ *   name: "api-integration",
+ *   description: "Connect to external REST APIs with auth, retries, and typed responses.",
+ *   body: "# API Integration\n\nAlways use the `apiClient` helper...",
+ *   version: "1.0.0",
+ *   tags: ["api", "http", "typescript"],
+ * }
+ * ```
+ */
+interface PackSkill {
+    /** Unique skill name. Must not conflict with project or user skills (project/user win). */
+    name: string;
+    /**
+     * When-to-use description. The agent reads this at L1 to decide whether to
+     * activate the skill. Written for LLM consumption, not humans.
+     */
+    description: string;
+    /**
+     * Full SKILL.md markdown body (everything below the frontmatter block).
+     * This becomes the L2 content loaded when the agent calls the `skill` tool.
+     */
+    body: string;
+    /** SemVer version string. */
+    version?: string;
+    /** Categorization tags for filtering and discovery. */
+    tags?: string[];
+    /** Names of skills this skill works best alongside. Suggested at L2 load time. */
+    dependencies?: string[];
+    /**
+     * Bundled reference material, scripts, templates, and examples (L3).
+     *
+     * The agent sees these listed after loading the skill (L2) and can
+     * read individual resources via the `skill_resource` tool.
+     */
+    resources?: PackSkillResource[];
+}
+/**
+ * A capability pack — the distributable unit of agent capabilities.
+ *
+ * A pack bundles any combination of:
+ * - **Skills**: on-demand instructions loaded by the agent via the `skill` tool.
+ * - **MCP servers**: external tool and resource providers connected via the MCP protocol.
+ * - **Plugin**: tools, middleware, commands, and prompt sections contributed as code.
+ *
+ * Packs are designed to be:
+ * - **Authored inline** in your agent code with `defineCapabilityPack()`
+ * - **Published as npm packages** that default-export a `CapabilityPack`
+ * - **Hosted at a URL** serving the JSON representation
+ * - **Stored in a local directory** with a `pack.json` manifest
+ *
+ * The `PackLoader` feeds a pack's contributions into the agent-core subsystems
+ * (`SkillRegistry`, `PluginRegistry`, and the `MCPConfig` for `MCPManager`).
+ *
+ * @example Inline pack with everything
+ * ```ts
+ * import { defineCapabilityPack } from "@cuylabs/agent-capability-pack"
+ * import { definePlugin, stdioServer } from "@cuylabs/agent-core"
+ *
+ * export default defineCapabilityPack({
+ *   id: "my-company-tools",
+ *   name: "My Company Tools",
+ *   version: "1.0.0",
+ *
+ *   skills: [{
+ *     name: "api-integration",
+ *     description: "Connect to My Company internal APIs with auth and retry logic.",
+ *     body: "# API Integration\n\nAlways use the Bearer token from...",
+ *   }],
+ *
+ *   mcpServers: {
+ *     "company-mcp": stdioServer("npx", ["-y", "@mycompany/mcp-server"]),
+ *   },
+ *
+ *   plugin: definePlugin({
+ *     id: "my-company-tools",
+ *     tools: [myCustomTool],
+ *   }),
+ * })
+ * ```
+ */
+interface CapabilityPack extends PackMeta {
+    /**
+     * Skills contributed to the agent's `SkillRegistry`.
+     *
+     * Skills use progressive disclosure: name and description (L1) are always
+     * visible to the agent in the system prompt; full body (L2) is loaded when
+     * the agent calls the `skill` tool.
+     */
+    skills?: PackSkill[];
+    /**
+     * MCP server configurations to add to the agent's `MCPManager`.
+     *
+     * These are collected by `PackLoader` and returned in `PackLoadResult.mcpServers`
+     * for the host to merge into its MCPConfig before calling `mcpManager.connect()`.
+     *
+     * Use the `stdioServer()`, `httpServer()`, and `sseServer()` helpers from
+     * `@cuylabs/agent-core/mcp` to build configs ergonomically.
+     */
+    mcpServers?: Record<string, MCPServerConfig>;
+    /**
+     * Plugin contributions: tools, middleware, commands, and prompt sections.
+     *
+     * Accepts either:
+     * - A `PluginDefinition` object (from `definePlugin()` in agent-core)
+     * - A raw `PluginInit` function
+     *
+     * The plugin is loaded into the host's `PluginRegistry` if one is provided
+     * to `PackLoader`. The pack's `id` is used as the plugin ID if the plugin
+     * definition does not specify one.
+     */
+    plugin?: PluginDefinition | PluginInit;
+}
+
+/**
+ * PackRef — typed references to capability packs from external sources.
+ *
+ * A `PackRef` tells the resolver WHERE to get a pack.
+ * Every ref resolves to the same `CapabilityPack` shape, regardless of origin.
+ *
+ * Use the helper constructors below rather than building refs by hand:
+ *
+ *   inlinePack(pack)           — already-constructed CapabilityPack
+ *   localPack("./path")        — directory on disk with a pack.json
+ *   npmPack("@org/my-pack")    — npm package exporting a CapabilityPack
+ *   urlPack("https://...")     — URL serving a pack JSON manifest
+ *   gitPack("https://...")     — Git repository containing a pack
+ */
+
+/** A pack that is already constructed — no resolution needed. */
+interface InlinePackRef {
+    source: "inline";
+    pack: CapabilityPack;
+}
+/**
+ * A pack stored in a local directory.
+ *
+ * The directory must contain a `pack.json` manifest. Skills are discovered
+ * from a `skills/` subdirectory using the SKILL.md convention. MCP server
+ * configs and plugin entry paths are read from `pack.json`.
+ */
+interface LocalPackRef {
+    source: "local";
+    /** Absolute or cwd-relative path to the pack directory. */
+    path: string;
+}
+/**
+ * A pack published as an npm package.
+ *
+ * The package must have a default export or a named export that is a
+ * `CapabilityPack`. The resolver uses a dynamic `import()`.
+ *
+ * @example
+ * ```ts
+ * npmPack("@mycompany/agent-pack")
+ * npmPack("@mycompany/agent-pack", { export: "dataPack" })
+ * ```
+ */
+interface NpmPackRef {
+    source: "npm";
+    /** npm package specifier (e.g. "@mycompany/agent-pack" or "agent-pack@1.2.0"). */
+    package: string;
+    /**
+     * Named export to use as the pack.
+     *
+     * When omitted, the default export is used.
+     */
+    export?: string;
+}
+/**
+ * A pack served as JSON at a URL.
+ *
+ * The URL must return a JSON object matching `CapabilityPack`.
+ * Only the pack metadata, skills, and MCP server configs are supported
+ * via URL packs — plugin code cannot be loaded from a URL for security.
+ */
+interface UrlPackRef {
+    source: "url";
+    /** HTTPS URL serving the pack JSON. */
+    url: string;
+}
+/**
+ * A pack stored in a Git repository.
+ *
+ * The repository root must contain a `pack.json` manifest.
+ * The resolver clones (or fetches) the repository to a local cache
+ * before reading the pack.
+ *
+ * Requires `git` to be available on PATH.
+ */
+interface GitPackRef {
+    source: "git";
+    /** Git-cloneable URL (HTTPS or SSH). */
+    url: string;
+    /** Branch, tag, or commit SHA to check out. Defaults to the default branch. */
+    ref?: string;
+}
+/** Union of all pack reference types. */
+type PackRef = InlinePackRef | LocalPackRef | NpmPackRef | UrlPackRef | GitPackRef;
+/** Reference to an already-constructed CapabilityPack. */
+declare function inlinePack(pack: CapabilityPack): InlinePackRef;
+/** Reference to a pack stored in a local directory. */
+declare function localPack(path: string): LocalPackRef;
+/**
+ * Reference to a pack published as an npm package.
+ *
+ * @param pkg  Package specifier (e.g. `"@mycompany/agent-pack"`).
+ * @param options.export  Named export to use instead of the default export.
+ */
+declare function npmPack(pkg: string, options?: {
+    export?: string;
+}): NpmPackRef;
+/** Reference to a pack served as JSON at a URL. */
+declare function urlPack(url: string): UrlPackRef;
+/**
+ * Reference to a pack in a Git repository.
+ *
+ * @param url  Git URL (HTTPS or SSH).
+ * @param ref  Branch, tag, or commit. Defaults to the default branch.
+ */
+declare function gitPack(url: string, ref?: string): GitPackRef;
+
+export { CAPABILITY_PACK_KIND as C, type GitPackRef as G, type InlinePackRef as I, type LocalPackRef as L, type NpmPackRef as N, type PackAuthor as P, type UrlPackRef as U, CAPABILITY_PACK_SCHEMA_VERSION as a, type CapabilityPack as b, type PackMeta as c, type PackRef as d, type PackSkill as e, type PackSkillResource as f, gitPack as g, type PackSkillResourceType as h, inlinePack as i, localPack as l, npmPack as n, urlPack as u };

package/docs/README.md

@@ -0,0 +1,17 @@
+# agent-capability-pack Docs
+
+`@cuylabs/agent-capability-pack` makes skills, MCP configs, and plugin
+contributions load through one source-agnostic unit: a `CapabilityPack`.
+
+## Concepts
+
+- `CapabilityPack`: resolved runtime unit
+- `PackRef`: where a pack comes from
+- `PackLoader`: feeds a pack into `agent-core`
+- `MCPSkillBridge`: turns MCP prompts into loadable skills
+
+## Reading Order
+
+- [authoring.md](./authoring.md): how to define packs and `pack.json`
+- [sources.md](./sources.md): inline, local, npm, URL, and git source behavior
+- [mcp-bridge.md](./mcp-bridge.md): how MCP prompt bridging works

package/docs/authoring.md

@@ -0,0 +1,85 @@
+# Authoring Packs
+
+## Inline Packs
+
+Use `defineCapabilityPack()` for packs authored directly in code:
+
+```ts
+import { defineCapabilityPack } from "@cuylabs/agent-capability-pack";
+
+export default defineCapabilityPack({
+  id: "company-tools",
+  name: "Company Tools",
+  skills: [
+    {
+      name: "internal-api",
+      description: "Use for tasks involving the internal company API.",
+      body: "# Internal API\n\nUse the authenticated client first.",
+    },
+  ],
+});
+```
+
+`defineCapabilityPack()` fills in:
+
+- `kind: "agent-capability-pack"`
+- `schemaVersion: 1`
+
+## Local `pack.json`
+
+Local and git-backed packs use `pack.json` plus an optional `skills/` folder.
+
+```json
+{
+  "kind": "agent-capability-pack",
+  "schemaVersion": 1,
+  "id": "company-tools",
+  "name": "Company Tools",
+  "description": "Internal skills and MCP connections",
+  "version": "1.0.0",
+  "plugin": "./plugin.ts",
+  "mcpServers": {
+    "company-api": {
+      "transport": "http",
+      "url": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+
+Directory layout:
+
+```text
+company-tools/
+  pack.json
+  plugin.ts
+  skills/
+    internal-api/
+      SKILL.md
+      references/
+      scripts/
+```
+
+Notes:
+
+- `plugin` is a relative module path. Use `.js` for production builds or `.ts` when running with `tsx` or `jiti` (plugin loading is jiti-powered and handles TypeScript directly).
+- The plugin module must default-export a `PluginInit` function, usually created with `definePlugin()` from `@cuylabs/agent-core/plugin`.
+- Local skills are discovered from `skills/` using the normal `SKILL.md` format.
+
+## Load Semantics
+
+`PackLoader` stages pack content before mutating the runtime registries:
+
+- pack plugin is validated and loaded first
+- pack skills are registered only after plugin loading succeeds
+- MCP server configs are returned to the host only for successful packs
+
+That keeps pack loading coherent instead of partially applying a failed pack.
+
+## Examples
+
+See the runnable examples in [`examples/`](../examples/):
+
+- [01-inline-pack.ts](../examples/01-inline-pack.ts) — define and load an inline pack
+- [02-local-pack.ts](../examples/02-local-pack.ts) — load from a directory on disk
+- [04-full-setup.ts](../examples/04-full-setup.ts) — full integration with MCP and an agent