shadow-claw 1.26.0 → 1.27.1

package/.agents/skills/main/skill-creator/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: skill-creator
+description: Create, edit, review, and validate ShadowClaw declarative skills and their supporting resources.
+user-invocable: true
+metadata:
+  allowed-tools: read_file write_file javascript create_directory
+---
+
+# ShadowClaw Skill Creator
+
+Use this skill when creating, modifying, reviewing, or validating a ShadowClaw agent skill or declarative tool pipeline.
+
+## Workspace Layout Standards
+
+- **Skills**: Create each skill in its dedicated directory under `.agents/skills/<group>/<skill-name>/SKILL.md` (default group: `main`).
+- **Declarative Tools**: Define supporting declarative tools under `.agents/tools/<group>/<tool-name>.json` (default group: `main`).
+- **Supporting Resources**: Co-locate skill-specific assets (reference documents, templates, helper scripts) inside the skill directory alongside `SKILL.md`.
+
+## Workflow
+
+1. **Establish Contract & Scope**
+   - For existing skills, read `SKILL.md` and related resources before editing.
+   - For new skills, define the trigger prompt, intended execution outcome, required tools, and output artifacts.
+2. **Configure Frontmatter**
+   - Provide a clear, concise trigger description in `description` (1024 characters max).
+   - Set `user-invocable: true` if the skill should be triggerable via slash command (e.g. `/skill-name`).
+   - Use `disable-model-invocation: true` for skills intended strictly for slash-command execution.
+   - Place non-standard configuration (such as `allowed-tools`) within the standard `metadata` block to maintain Agent Skills specification compliance.
+3. **Structure & Draft Content**
+   - Write instructions in `SKILL.md` using clear, modular procedures.
+   - Place deterministic operations in `javascript` tool calls; use `read_file` and `write_file` for workspace persistence.
+   - Create required target directories via `create_directory` prior to writing files.
+4. **Declarative Pipelines (`execution.type: tools`)**
+   - Define sequential tool pipelines in frontmatter via `execution: { type: "tools", tools: [...] }`.
+   - Pass outputs between steps using `{ "$pipe": "prev" }` or step/tool identifiers.
+   - Optionally apply `suppressToast: true` or `suppressOutput: true` at the execution root or per step to suppress notifications and output blocks.
+5. **Verify & Validate**
+   - Re-read the saved `SKILL.md` and verify valid YAML frontmatter syntax.
+   - Ensure the skill name uses 1–64 lowercase alphanumeric characters or hyphens and all referenced resource paths exist.

package/.agents/skills/main/skill-creator/references/declarative-pipelines.md

@@ -0,0 +1,44 @@
+# Declarative Execution Pipelines
+
+Declarative execution pipelines allow skills to execute deterministic sequential tool chains directly on the worker thread without scheduling a Task or making model LLM calls.
+
+## Configuration Syntax
+
+Pipelines are declared in `SKILL.md` frontmatter under `metadata.execution`:
+
+```yaml
+---
+name: sample-pipeline
+description: Run a deterministic tool chain.
+user-invocable: true
+metadata:
+  allowed-tools: javascript show_toast
+  execution:
+    type: tools
+    suppressToast: true
+    suppressOutput: true
+    tools:
+      - name: javascript
+        input:
+          code: "Math.floor(Math.random() * 100) + 1"
+      - name: show_toast
+        input:
+          title: "Random Number"
+          message:
+            $pipe: prev
+---
+```
+
+## Data Piping (`$pipe`)
+
+Inputs in tool step configurations can reference outputs from previous steps using the `$pipe` operator:
+
+- `{ "$pipe": "prev" }` or `{ "$pipe": -1 }`: Resolves to the return output of the immediately preceding tool step.
+- `{ "$pipe": 0 }`: Resolves to the return output of step index `0` (0-indexed).
+- `{ "$pipe": "javascript" }`: Resolves to the return output of the last step that ran the `javascript` tool.
+
+## Execution Suppression
+
+- `suppressToast: true`: Suppresses step progress toasts ("Running skill tool...") during pipeline execution.
+- `suppressOutput: true`: Suppresses raw tool result blocks from being rendered in the chat thread.
+- Setting suppression options at the `execution` root cascades down to all steps unless explicitly overridden per tool step.

package/.agents/skills/main/skill-creator/references/declarative-tools.md

@@ -0,0 +1,35 @@
+# Declarative Tools
+
+Declarative tools allow workspace authors to define reusable custom tools using JSON definitions placed under `.agents/tools/<group>/<tool-name>.json`.
+
+## Directory Structure
+
+```text
+.agents/tools/
+└── main/
+    └── generate_random_number.json
+```
+
+## Schema Format
+
+```json
+{
+  "name": "generate_random_number",
+  "description": "Generate a random integer within a specified range.",
+  "executor": "javascript",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "min": { "type": "number", "default": 1 },
+      "max": { "type": "number", "default": 1000000 }
+    }
+  },
+  "code": "const min = Number(inputs.min ?? 1); const max = Number(inputs.max ?? 1000000); return Math.floor(Math.random() * (max - min + 1)) + min;"
+}
+```
+
+## Features
+
+- **Automatic Discovery**: Automatically loaded from `.agents/tools/` across conversation workspaces.
+- **WebMCP Integration**: Registered with the browser ModelContext API for both manual pinning and automated agent execution.
+- **Expression Evaluation**: Code expressions automatically evaluate and return results without needing explicit wrapper boilerplate.

package/.agents/skills/main/skill-creator/references/frontmatter-spec.md

@@ -0,0 +1,50 @@
+# Frontmatter Specification
+
+Agent skills in ShadowClaw are configured via YAML frontmatter at the top of `SKILL.md`. Frontmatter attributes adhere strictly to the standard Agent Skills specification.
+
+## Specification Schema
+
+```yaml
+---
+name: skill-name
+description: Clear, concise model-facing trigger description.
+user-invocable: true
+disable-model-invocation: false
+argument-hint: "[arguments]"
+metadata:
+  allowed-tools: read_file write_file javascript
+compatibility: ShadowClaw
+license: MIT
+---
+```
+
+## Attribute Reference
+
+| Attribute                  | Type      | Required | Description                                                                                               |
+| :------------------------- | :-------- | :------- | :-------------------------------------------------------------------------------------------------------- |
+| `name`                     | `string`  | **Yes**  | Skill identifier (1–64 lowercase alphanumeric characters and single hyphens).                             |
+| `description`              | `string`  | **Yes**  | Model-facing description used for skill discovery and activation (max 1024 characters).                   |
+| `user-invocable`           | `boolean` | No       | When `true` (default), allows users to invoke the skill directly via slash commands (e.g. `/skill-name`). |
+| `disable-model-invocation` | `boolean` | No       | When `true`, hides the skill from model discovery so it is only triggered via slash command.              |
+| `argument-hint`            | `string`  | No       | Display placeholder in the UI search/autocomplete menu when typing slash commands.                        |
+| `metadata`                 | `object`  | No       | Key-value dictionary for custom metadata, tool permissions (`allowed-tools`), and `execution` pipelines.  |
+| `compatibility`            | `string`  | No       | Platform compatibility requirements or version strings.                                                   |
+| `license`                  | `string`  | No       | Open-source software license string (e.g. `MIT`, `AGPL-3.0`).                                             |
+
+## Metadata Attributes (`metadata`)
+
+Custom configuration properties and extension specifications (like declarative execution pipelines) that fall outside the standard Agent Skills frontmatter attributes should be placed inside `metadata`:
+
+```yaml
+metadata:
+  allowed-tools: javascript show_toast generate_random_number
+  author: ShadowClaw Team
+  version: 1.0.0
+  execution:
+    type: tools
+    suppressToast: true
+    tools:
+      - name: javascript
+        input:
+          code: Math.floor(Math.random() * 100) + 1
+```

package/.well-known/agent-skills/index.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+  "name": "ShadowClaw",
+  "description": "ShadowClaw - Browser-native AI agent.",
+  "skills": [
+    {
+      "name": "skill-creator",
+      "type": "skill-md",
+      "description": "Create, edit, review, and validate ShadowClaw declarative skills and their supporting resources.",
+      "url": "../../.agents/skills/main/skill-creator/SKILL.md",
+      "digest": "sha256:e9876a79ab38c3a9acd0a990f2a26a578e1971abc2f3cd0eeda1988e6529f684"
+    }
+  ]
+}

package/README.md

@@ -62,7 +62,7 @@ A fully-functional agent runtime built on browser-native technology — the orch
 - **Model registry** — Dynamic metadata fetch (context window, modality support)
 - **Attachment capabilities** — Native multimodal delivery with automatic text fallback
 - **Remote MCP** — Discover and execute tools from external MCP servers
-- **Stateless MCP server** — Expose ShadowClaw CLI commands and live browser tools to external agent hosts (Claude Desktop, Cursor, Goose) via STDIO (`npx shadow-claw mcp`) or Streamable HTTP (`POST /mcp`)
+- **Stateless MCP server** — Expose ShadowClaw CLI commands and live browser tools to external agent hosts (Claude Desktop, Cursor, Goose) via STDIO (`npx shadow-claw mcp`) or Streamable HTTP (`POST /mcp`), featuring multi-client tool targeting (`shadowclaw_set_active_client`), per-tool client capability validation, client-side execution guards, and interactive `ask_user` relaying
 - **A2UI interactive surfaces** — Render responsive UI components (Text, Button, TextField, Row/Column layouts) from agents via PeerJS WebRTC with two-way data binding
 - **Multi-Agent Shared State** — Synchronize agent knowledge across participants using `STATE_SNAPSHOT` and `STATE_DELTA` events
 - **Email integration** — IMAP/SMTP support with encrypted credentials
@@ -243,6 +243,7 @@ Pages complement the **main group MEMORY** (auto-created as `MEMORY.md` on first
 ## Agent Skills and Declarative Tools
 
 - **Workspace Agent Skills** — Discovers `.agents/skills/**/SKILL.md` instruction packages, presents model-invocable skill descriptions in the system prompt, and loads instructions plus bundled resources through `activate_skill`. Default bundled skills include `skill-creator`.
+- **Agent Skills Discovery Index** — Automatically indexes skills, tools, and scripts into `/.well-known/agent-skills/index.json` complying with Agent Skills Discovery RFC v0.2.0, computing SHA-256 digests and RFC 3986 relative URLs. Integrated into static builds (`bin/build/build.mjs`) and runnable via `npx shadow-claw skills:index [dir]` (alias `agent-skills`).
 - **Slash Commands & Declarative Execution Pipelines** — User-invocable skills support `/skill-name` slash-command triggers. Skills with `execution: { type: "tools", tools: [...] }` execute tool pipelines directly on the worker thread via `executeToolChain` without scheduling Tasks or invoking LLM prompts. Supports `$pipe` output chaining and step-level or cascaded `suppressToast: true` and `suppressOutput: true` options.
 - **Declarative Tools** — Content repositories can define executable tools as JSON under `.agents/tools/main/` using sandboxed Bash or JavaScript, or delegate to existing tools without changing ShadowClaw source (e.g. `generate_random_number` in the starter template repository).
 - **Enhanced JS Tool Expression Evaluation** — The `javascript` tool automatically evaluates single expressions without explicit `return` statements by wrapping them in `return (<expression>);`.
@@ -252,7 +253,7 @@ Pages complement the **main group MEMORY** (auto-created as `MEMORY.md` on first
 ShadowClaw packages its UI components as standard Web Components built on TC39 Signals and native Custom Elements:
 
 - **Modular Package Exports** — Import pre-bundled components and utilities directly via `shadow-claw/components` (e.g. `ShadowClawToast`, `ShadowClawCard`, `ShadowClawDialog`, `ShadowClawEmptyState`, `ShadowClawPageHeader`) and `shadow-claw/utils` (e.g. `namespacedStorage`, `ulid`). TypeScript declaration files (`.d.ts`) are provided out of the box.
-- **Storybook Workbench** — Interactive visual development environment powered by Storybook (`@storybook/web-components-vite`) with dark mode default, live controls, and isolated component testing (`npm run storybook`).
+- **Storybook Workbench** — Interactive visual development environment powered by Storybook (`@storybook/web-components-vite`) with dark mode default, live controls, and isolated component testing (`npm run storybook`), including all 18 A2UI catalog components and UI primitives.
 - **Reactive Element Lifecycle** — Custom elements extending `ShadowClawElement` observe attributes (`observedAttributes`) for declarative reactive DOM updates.
 
 ## WebVM (Optional Alpine Linux)
@@ -277,7 +278,7 @@ ShadowClaw uses **IndexedDB** for structured data (messages, config, tasks) and
 - **30-second key expiry** for plaintext operations
 - **No plaintext secrets on disk** — encrypted before storage
 - **Trusted Types enforcement** — idempotent `"default"` policy (`src/security/default-trusted-types-policy.ts`) registered at boot via `theme-init.ts`; `getPolicy()` fallback prevents duplicate-creation errors on module reload
-- **Custom element security guards** — `installCustomElementsRegistryGuard` and `installCustomElementDomGuard` prevent unauthorized custom element registration and dynamic DOM injection, strictly enforcing allowlists from `shadow-claw.config.json` (or `site-config.json`) or storage
+- **Custom element security guards** — `installCustomElementsRegistryGuard` and `installCustomElementDomGuard` prevent unauthorized custom element registration and dynamic DOM injection, strictly enforcing allowlists from `shadow-claw.config.json` (or `site-config.json`) or storage. Script declarations support URLs and `{ src, hasInit }` descriptors (standardized on `src`), invoking `init()` exclusively when `hasInit: true` is configured.
 - **Iframe sandbox & CSP hardening** — sandboxed preview iframes omit `allow-same-origin` by default to enforce opaque-origin (`null`) isolation without Chrome sandbox escape warnings, while injecting a transparent `postMessage` storage proxy bridge (`iframe-storage-bridge.js`) to provide namespaced `IndexedDB` and `localStorage` persistence for custom elements, trapping `ServiceWorker`/`caches` `SecurityError` rejections, polyfilling `showOpenFilePicker`/`showSaveFilePicker`, and relaying programmatic/link navigation and declarative `BroadcastChannel` messages via `IframeBroadcastProxy`
 - **Iframe embed sanitization** — DOMPurify-based iframe allowlisting protects markdown and HTML previews, with Settings-backed host patterns and a safe default host list
 - **SSRF proxy hardening** — `/proxy` blocks non-HTTP/S schemes and private/loopback IP ranges by default; bypassed via `--allow-private-proxy` flag or the authenticated service-worker JSON format
@@ -430,6 +431,7 @@ npx shadow-claw server --tmp                         # Run services with tempora
 npx shadow-claw server --cache-dir <dir>             # Run services with custom cache directory
 npx shadow-claw webrtc listen                        # Start headless WebRTC DataChannel daemon
 npx shadow-claw peer-id                              # Get or generate persistent CLI Peer ID
+npx shadow-claw skills:index                         # Generate or update .well-known/agent-skills/index.json
 ```
 
 When launching `dev`, `run`, `serve`, or `server` without an existing cache, ShadowClaw prompts interactively to select between the local directory (`.cache`), system temporary storage (`tmpdir()`), or a custom path (skip prompting via `--tmp`, `-y`, `--cache-dir <dir>`, or `SHADOWCLAW_CACHE_DIR`).

package/bin/build/build.mjs

@@ -18,11 +18,6 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const projectRoot = resolve(__dirname, "../..");
 
-async function run(command, options = {}) {
-  console.log(`> ${command}`);
-  execSync(command, { stdio: "inherit", ...options });
-}
-
 async function pathExists(p) {
   try {
     await stat(p);
@@ -33,6 +28,28 @@ async function pathExists(p) {
 }
 
 export async function runBuild(options = {}) {
+  const isQuiet =
+    options.quiet ?? (process.env.NODE_ENV === "test" && !process.env.VERBOSE);
+  const defaultStdio =
+    options.stdio ??
+    (process.env.NODE_ENV === "test" && !process.env.VERBOSE
+      ? "pipe"
+      : "inherit");
+
+  const log = (...args) => {
+    if (!isQuiet) {
+      console.log(...args);
+    }
+  };
+
+  async function run(command, runOptions = {}) {
+    if (!isQuiet && !runOptions.quiet) {
+      console.log(`> ${command}`);
+    }
+    const stdio = runOptions.stdio ?? defaultStdio;
+    execSync(command, { stdio, ...runOptions });
+  }
+
   const contentRoot = resolve(
     options.contentRoot || env.SHADOWCLAW_CONTENT_ROOT || process.cwd(),
   );
@@ -120,6 +137,39 @@ export async function runBuild(options = {}) {
       });
     } catch {}
 
+    try {
+      await cp(".agents/scripts", "dist/public/.agents/scripts", {
+        recursive: true,
+      });
+    } catch {}
+
+    // Generate / sync Agent Skills Discovery index (.well-known/agent-skills/index.json)
+    if (await pathExists(".agents/skills")) {
+      try {
+        const { generateSkillsIndex } =
+          await import("../commands/skills-index.mjs");
+        await generateSkillsIndex(projectRoot);
+        if (await pathExists(".well-known/agent-skills/index.json")) {
+          await cp(".well-known", "dist/public/.well-known", {
+            recursive: true,
+            force: true,
+          });
+        }
+      } catch (err) {
+        console.warn(
+          "Notice: Failed to auto-generate agent-skills index:",
+          err,
+        );
+      }
+    } else if (await pathExists(".well-known")) {
+      try {
+        await cp(".well-known", "dist/public/.well-known", {
+          recursive: true,
+          force: true,
+        });
+      } catch {}
+    }
+
     await run("npm run -s rolldown");
 
     if (prerenderMainMemory) {
@@ -141,14 +191,14 @@ export async function runBuild(options = {}) {
     } catch {}
 
     if (isProduction) {
-      console.log("Running production post-build steps...");
+      log("Running production post-build steps...");
 
       const pagesOrigin = options.pagesOrigin || env.PAGES_ORIGIN;
       const basePath =
         options.basePath || (env.PAGES_BASE_PATH ?? "/shadow-claw/");
 
-      console.log(`  PAGES_ORIGIN   : ${pagesOrigin || "(relative ./)"}`);
-      console.log(`  PAGES_BASE_PATH: ${basePath}`);
+      log(`  PAGES_ORIGIN   : ${pagesOrigin || "(relative ./)"}`);
+      log(`  PAGES_BASE_PATH: ${basePath}`);
 
       if (pagesOrigin) {
         try {
@@ -175,6 +225,7 @@ export async function runBuild(options = {}) {
       try {
         meta = execSync("npm run -s build:pkg:get:meta", {
           encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
         }).trim();
       } catch {}
       if (meta) {
@@ -191,7 +242,7 @@ export async function runBuild(options = {}) {
     await run("npm run -s build:service-worker");
     await run("node bin/patch-service-worker-trusted-types.mjs");
 
-    console.log("Build completed successfully.");
+    log("Build completed successfully.");
     return;
   }
 
@@ -206,7 +257,7 @@ export async function runBuild(options = {}) {
   const toolchainDist = join(toolchainRoot, "dist/public");
   const toolchainBuilt = await pathExists(join(toolchainDist, "index.js"));
   if (!toolchainBuilt) {
-    console.log("Building ShadowClaw core toolchain...");
+    log("Building ShadowClaw core toolchain...");
     await run("npm run -s build:clean", { cwd: toolchainRoot });
     await run("npm run -s rolldown", { cwd: toolchainRoot });
   }
@@ -289,20 +340,100 @@ export async function runBuild(options = {}) {
     });
   }
 
-  // 6. Copy .agents from contentRoot
+  // 6. Copy .agents from contentRoot (fallback to toolchainRoot)
   const contentSkills = join(contentRoot, ".agents/skills");
   if (await pathExists(contentSkills)) {
     await cp(contentSkills, join(distPublicDir, ".agents/skills"), {
       recursive: true,
       force: true,
     });
+  } else {
+    const toolchainSkills = join(toolchainRoot, ".agents/skills");
+    if (await pathExists(toolchainSkills)) {
+      await cp(toolchainSkills, join(distPublicDir, ".agents/skills"), {
+        recursive: true,
+        force: true,
+      });
+    }
   }
+
   const contentTools = join(contentRoot, ".agents/tools");
   if (await pathExists(contentTools)) {
     await cp(contentTools, join(distPublicDir, ".agents/tools"), {
       recursive: true,
       force: true,
     });
+  } else {
+    const toolchainTools = join(toolchainRoot, ".agents/tools");
+    if (await pathExists(toolchainTools)) {
+      await cp(toolchainTools, join(distPublicDir, ".agents/tools"), {
+        recursive: true,
+        force: true,
+      });
+    }
+  }
+
+  const contentScripts = join(contentRoot, ".agents/scripts");
+  if (await pathExists(contentScripts)) {
+    await cp(contentScripts, join(distPublicDir, ".agents/scripts"), {
+      recursive: true,
+      force: true,
+    });
+  } else {
+    const toolchainScripts = join(toolchainRoot, ".agents/scripts");
+    if (await pathExists(toolchainScripts)) {
+      await cp(toolchainScripts, join(distPublicDir, ".agents/scripts"), {
+        recursive: true,
+        force: true,
+      });
+    }
+  }
+
+  // 6b. Generate / sync Agent Skills Discovery index (.well-known/agent-skills/index.json)
+  const distSkillsDir = join(distPublicDir, ".agents/skills");
+  if (await pathExists(distSkillsDir)) {
+    try {
+      const { generateSkillsIndex } =
+        await import("../commands/skills-index.mjs");
+      await generateSkillsIndex(distPublicDir, {
+        metadataRoot: contentRoot,
+        outDir: ".well-known/agent-skills",
+      });
+      // Also keep contentRoot/.well-known/agent-skills/index.json in sync if contentSkills exists
+      if (await pathExists(contentSkills)) {
+        try {
+          await generateSkillsIndex(contentRoot, {
+            toolchainRoot,
+            includeBundled: true,
+          });
+        } catch {}
+      }
+    } catch (err) {
+      console.warn("Notice: Failed to auto-generate agent-skills index:", err);
+      const contentWellKnown = join(contentRoot, ".well-known");
+      if (await pathExists(contentWellKnown)) {
+        await cp(contentWellKnown, join(distPublicDir, ".well-known"), {
+          recursive: true,
+          force: true,
+        });
+      }
+    }
+  } else {
+    const contentWellKnown = join(contentRoot, ".well-known");
+    if (await pathExists(contentWellKnown)) {
+      await cp(contentWellKnown, join(distPublicDir, ".well-known"), {
+        recursive: true,
+        force: true,
+      });
+    } else {
+      const toolchainWellKnown = join(toolchainRoot, ".well-known");
+      if (await pathExists(toolchainWellKnown)) {
+        await cp(toolchainWellKnown, join(distPublicDir, ".well-known"), {
+          recursive: true,
+          force: true,
+        });
+      }
+    }
   }
 
   // 7. Prerender DSD Shell
@@ -348,11 +479,11 @@ export async function runBuild(options = {}) {
   } catch {}
 
   if (isProduction) {
-    console.log("Running production post-build steps...");
+    log("Running production post-build steps...");
 
     const pagesOrigin = options.pagesOrigin || env.PAGES_ORIGIN;
-    console.log(`  PAGES_ORIGIN   : ${pagesOrigin || "(relative ./)"}`);
-    console.log(`  PAGES_BASE_PATH: ${basePath}`);
+    log(`  PAGES_ORIGIN   : ${pagesOrigin || "(relative ./)"}`);
+    log(`  PAGES_BASE_PATH: ${basePath}`);
 
     if (pagesOrigin) {
       try {
@@ -377,12 +508,14 @@ export async function runBuild(options = {}) {
       meta = execSync("git rev-parse HEAD", {
         cwd: contentRoot,
         encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
       }).trim();
     } catch {
       try {
         meta = execSync("git rev-parse HEAD", {
           cwd: toolchainRoot,
           encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
         }).trim();
       } catch {}
     }
@@ -425,7 +558,7 @@ export async function runBuild(options = {}) {
     await run(`node "${patchSwScript}" "${swPath}"`);
   }
 
-  console.log("Build completed successfully.");
+  log("Build completed successfully.");
 }
 
 const isMainModule =

package/bin/build/build.test.mjs

@@ -121,6 +121,22 @@ describe("build without and with pages", () => {
       manifest.skills.filter((s) => s.displayPath.endsWith("SKILL.md")),
     ).toHaveLength(2);
     expect(manifest.skillsPurgeId).toBe("skills-build-001");
+
+    const wellKnownIndexPath = path.join(
+      tempProjectRoot,
+      "dist/public/.well-known/agent-skills/index.json",
+    );
+    expect(fs.existsSync(wellKnownIndexPath)).toBe(true);
+    const wellKnownIndex = JSON.parse(
+      await readFile(wellKnownIndexPath, "utf8"),
+    );
+    expect(wellKnownIndex.$schema).toBe(
+      "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+    );
+    expect(wellKnownIndex.skills.map((s) => s.name)).toEqual(
+      expect.arrayContaining(["skill-creator", "example"]),
+    );
+    expect(wellKnownIndex.tools.map((t) => t.name)).toContain("echo");
   });
 
   it("builds with no pages directory and keeps default pages", async () => {
@@ -146,5 +162,117 @@ describe("build without and with pages", () => {
       path.join(tempProjectRoot, "site-config.json"),
     ].find((p) => fs.existsSync(p));
     expect(await readFile(configPath, "utf8")).toContain("ShadowClaw");
+
+    const wellKnownIndexPath = path.join(
+      tempProjectRoot,
+      "dist/public/.well-known/agent-skills/index.json",
+    );
+    expect(fs.existsSync(wellKnownIndexPath)).toBe(true);
+  });
+
+  it("builds an external consumer content root and falls back to toolchain .agents and .well-known", async () => {
+    const tempConsumerRoot = await mkdtemp(
+      path.join(os.tmpdir(), "shadow-claw-consumer-"),
+    );
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const { runBuild: runConsumerBuild } = await import("./build.mjs");
+      await runConsumerBuild({
+        contentRoot: tempConsumerRoot,
+        toolchainRoot: tempProjectRoot,
+        isProduction: false,
+        quiet: true,
+        stdio: "pipe",
+      });
+
+      const consumerDistPublic = path.join(tempConsumerRoot, "dist/public");
+      expect(
+        fs.existsSync(
+          path.join(consumerDistPublic, ".well-known/agent-skills/index.json"),
+        ),
+      ).toBe(true);
+      expect(
+        fs.existsSync(
+          path.join(
+            consumerDistPublic,
+            ".agents/skills/main/skill-creator/SKILL.md",
+          ),
+        ),
+      ).toBe(true);
+    } finally {
+      logSpy.mockRestore();
+      await rm(tempConsumerRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("builds an external consumer with custom skills and retains bundled skill-creator in .well-known index", async () => {
+    const tempConsumerRoot = await mkdtemp(
+      path.join(os.tmpdir(), "shadow-claw-custom-consumer-"),
+    );
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      await writeFile(
+        path.join(tempConsumerRoot, "shadow-claw.config.json"),
+        JSON.stringify({
+          site: {
+            title: "Custom Hub",
+            description: "Custom hub description.",
+          },
+        }),
+        "utf8",
+      );
+
+      const skillDir = path.join(
+        tempConsumerRoot,
+        ".agents",
+        "skills",
+        "main",
+        "custom-skill",
+      );
+      await mkdir(skillDir, { recursive: true });
+      await writeFile(
+        path.join(skillDir, "SKILL.md"),
+        "---\nname: custom-skill\ndescription: Custom consumer skill.\n---\n",
+        "utf8",
+      );
+
+      const { runBuild: runConsumerBuild } = await import("./build.mjs");
+      await runConsumerBuild({
+        contentRoot: tempConsumerRoot,
+        toolchainRoot: tempProjectRoot,
+        isProduction: true,
+        quiet: true,
+        stdio: "pipe",
+      });
+
+      const consumerDistPublic = path.join(tempConsumerRoot, "dist/public");
+      const wellKnownPath = path.join(
+        consumerDistPublic,
+        ".well-known/agent-skills/index.json",
+      );
+      expect(fs.existsSync(wellKnownPath)).toBe(true);
+
+      const wellKnownIndex = JSON.parse(await readFile(wellKnownPath, "utf8"));
+      expect(wellKnownIndex.name).toBe("Custom Hub");
+      expect(wellKnownIndex.description).toBe("Custom hub description.");
+      expect(wellKnownIndex.skills.map((s) => s.name)).toEqual(
+        expect.arrayContaining(["custom-skill", "skill-creator"]),
+      );
+
+      const contentWellKnownPath = path.join(
+        tempConsumerRoot,
+        ".well-known/agent-skills/index.json",
+      );
+      expect(fs.existsSync(contentWellKnownPath)).toBe(true);
+      const contentIndex = JSON.parse(
+        await readFile(contentWellKnownPath, "utf8"),
+      );
+      expect(contentIndex.skills.map((s) => s.name)).toEqual(
+        expect.arrayContaining(["custom-skill", "skill-creator"]),
+      );
+    } finally {
+      logSpy.mockRestore();
+      await rm(tempConsumerRoot, { recursive: true, force: true });
+    }
   });
 });