toolfactory 0.4.5 → 0.4.6

package/README.md

@@ -22,7 +22,7 @@ generated and every surface still installs, builds and publishes.
 - **Gemini CLI extension** — `gemini extensions install https://github.com/GoatInAHat/toolfactory`
 - **OpenClaw plugin** — `openclaw plugins install --link hosts/openclaw` from a checkout
 - **Hermes plugin** — `hermes plugins install https://github.com/GoatInAHat/toolfactory#hosts/hermes/toolfactory_hermes`
-- **DSH plugin** (experimental) — `dsh plugin --profile <profile> add ./hosts/dsh` from a checkout, or the release tarball `toolfactory-dsh-0.4.5.tgz`
+- **DSH plugin** (experimental) — `dsh plugin --profile <profile> add ./hosts/dsh` from a checkout, or the release tarball `toolfactory-dsh-0.4.6.tgz`
 - **Web app** — `npx -y toolfactory mcp --http --open` serves the operations page beside the
   MCP endpoint on one port and opens it; over MCP or a skill, the `web` operation does the same and
   returns the URL.
@@ -155,6 +155,14 @@ Toolfactory itself continues to use npm as its package registry.
 
 ## Driving toolfactory from an agent
 
+Selecting both `skill` and `openclaw-native` ships the tool's own skill with the native plugin
+by default. `openclaw.skills` is an exact override: `[]` opts out; `["my-tool", "custom"]`
+ships the generated own skill and `.agents/skills/custom/`. An explicit custom-only list
+continues to ship only those skills. The own skill's generated regions are refreshed in the
+same build; authored prose and UTF-8 text resources are retained. The native manifest declares
+`skills: ["./skills"]`, and npm packaging includes that directory. No native plugin skill is
+inferred when the standalone `skill` surface is absent.
+
 Every command is an MCP tool, so a host can drive the whole loop without a shell — and nothing is
 registered by hand. Every generated project carries the `.agents/` canon, so `toolfactory` and the
 tool's own kernel are already entries in `.agents/mcp/servers.json`, which `bash .agents/setup`

package/dist/e2e.test.js

@@ -4,7 +4,7 @@
  * own node_modules isn't around to symlink in (no dependencies to run against).
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, symlinkSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, readlinkSync, symlinkSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -18,7 +18,15 @@ describe.skipIf(!existsSync(repoNodeModules))("end-to-end: init -> introspect ->
     }, async () => {
         const dir = mkdtempSync(join(tmpdir(), "toolfactory-e2e-"));
         symlinkSync(repoNodeModules, join(dir, "node_modules"), "dir");
-        const surfaces = ["skill", "agent-plugins", "claude", "mcp", "cli", "npm"];
+        const surfaces = [
+            "skill",
+            "agent-plugins",
+            "claude",
+            "mcp",
+            "cli",
+            "npm",
+            "openclaw-native",
+        ];
         const init = commands.init({
             root: dir,
             name: "hello",
@@ -33,8 +41,29 @@ describe.skipIf(!existsSync(repoNodeModules))("end-to-end: init -> introspect ->
         const echo = snapshot.ops.tools[0];
         expect(echo.inputSchema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
         expect(echo.outputSchema?.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
-        commands.build(dir);
+        const skillPath = join(dir, "skills/hello/SKILL.md");
+        writeFileSync(skillPath, readFileSync(skillPath, "utf8").replace("# hello", "# hello\n\nAuthor procedure."));
+        mkdirSync(join(dir, "skills/hello/references"));
+        writeFileSync(join(dir, "skills/hello/references/guide.md"), "Retained reference.\n");
+        const opsPath = join(dir, "src/ops.ts");
+        writeFileSync(opsPath, readFileSync(opsPath, "utf8").replace("Return the text you pass in.", "Freshly rebuilt operation."));
+        await commands.introspect(dir);
         await expect(commands.check(dir)).resolves.toBeDefined();
+        expect(commands.build(dir).result.written).toEqual([]);
+        const bundled = readFileSync(join(dir, "hosts/openclaw/skills/hello/SKILL.md"), "utf8");
+        expect(bundled).toBe(readFileSync(skillPath, "utf8"));
+        expect(bundled).toContain("Author procedure.");
+        expect(bundled).toContain("Freshly rebuilt operation.");
+        expect(bundled).not.toContain("Return the text you pass in.");
+        const packed = JSON.parse(execFileSync("npm", ["pack", "./hosts/openclaw", "--dry-run", "--json"], {
+            cwd: dir,
+            encoding: "utf8",
+        }));
+        expect(packed[0]?.files.map((file) => file.path)).toEqual(expect.arrayContaining([
+            "openclaw.plugin.json",
+            "skills/hello/SKILL.md",
+            "skills/hello/references/guide.md",
+        ]));
         const opsOnDisk = JSON.parse(readFileSync(join(dir, "dev.toolfactory/ops.json"), "utf8"));
         expect(opsOnDisk.tools.map((t) => t.name)).toEqual(["echo"]);
         const output = execFileSync(process.execPath, ["--import", "tsx", "src/toolfactory/cli.ts", "echo", "--text", "hi"], { cwd: dir, encoding: "utf8" });

package/dist/hosts/openclaw.js

@@ -14,7 +14,7 @@ import { join } from "node:path";
 import { argv, exit, stderr, stdout } from "node:process";
 import { fileURLToPath } from "node:url";
 import { loadProject } from "../project/load.js";
-import { HOST_DIR, OPENCLAW_SCAFFOLD, surface } from "../surfaces/openclaw-native.js";
+import { HOST_DIR, OPENCLAW_SCAFFOLD, shipsSkills, surface } from "../surfaces/openclaw-native.js";
 export const DRIFT_ENTRY = fileURLToPath(import.meta.url);
 /** Per-tool values: the scaffold writes its own, and the projection is expected to differ. */
 const PER_TOOL_KEYS = new Set(["name", "version", "description"]);
@@ -35,7 +35,7 @@ function overridden(project) {
         paths.add(".openclaw.compat.pluginApi");
     }
     // Shipped skills append to `files`; upstream's entries must still survive (checked below).
-    if (openclaw?.skills?.length)
+    if (shipsSkills(project))
         paths.add(".files");
     return paths;
 }
@@ -99,7 +99,7 @@ export function scaffoldDrift(project) {
                 ? []
                 : ["vitest.config.ts: upstream template changed"]),
         ];
-        if (project.tool.openclaw?.skills?.length) {
+        if (shipsSkills(project)) {
             const upstream = JSON.parse(scaffold("package.json")).files ?? [];
             const ours = JSON.parse(planned(files, "package.json")).files ?? [];
             const lost = upstream.filter((entry) => !ours.includes(entry));

package/dist/model.d.ts

@@ -281,7 +281,7 @@ export interface Project {
     toolfactoryVersion: string;
     /** From the root package.json `packageManager` field; npm when absent. */
     packageManager?: PackageManager;
-    /** Skills `openclaw.skills` declares, read once so projectors stay pure. */
+    /** Resolved OpenClaw skills, including the generated default, read once so projectors stay pure. */
     skills?: ProjectSkill[];
 }
 export interface Surface {

package/dist/model.js

@@ -194,7 +194,7 @@ export const ToolConfigSchema = z
         skills: z
             .array(z.string())
             .optional()
-            .describe("Skill directories under `.agents/skills/` that the OpenClaw plugin ships; OpenClaw loads them through the manifest's `skills` roots."),
+            .describe("Exact skill selection for the OpenClaw plugin. Omitted: the tool's own generated skill when the skill surface is selected. []: no skills. Other names resolve under `.agents/skills/`; OpenClaw loads the packaged manifest's `skills` roots."),
         dependencies: z.record(z.string(), z.string()).optional(),
         peerDependencies: z.record(z.string(), z.string()).optional(),
         devDependencies: z.record(z.string(), z.string()).optional(),

package/dist/project/apply.d.ts

@@ -1,5 +1,5 @@
 import type { PlannedFile, Region } from "../model.js";
-import { type Markers } from "./lock.js";
+import { type Lock, type Markers } from "./lock.js";
 export interface Drift {
     path: string;
     kind: "missing" | "changed" | "orphan" | "unmarked";
@@ -30,6 +30,8 @@ export declare function removeKeys(document: Record<string, unknown>, keys: read
 export declare function managedContent(file: PlannedFile): string;
 /** Compare a plan to the tree without writing. */
 export declare function check(root: string, plan: PlannedFile[], toolfactoryVersion: string): Drift[];
+/** Read-only preview of the exact bytes apply writes, retaining authored regions and extensions. */
+export declare function renderFile(root: string, file: PlannedFile, previous: Lock): string;
 /** Write a plan to the tree and refresh the lock. */
 export declare function apply(root: string, plan: PlannedFile[], toolfactoryVersion: string): ApplyResult;
 export declare function setState(root: string, path: string, state: "generated" | "manual", toolfactoryVersion: string): void;

package/dist/project/apply.js

@@ -390,7 +390,8 @@ export function check(root, plan, toolfactoryVersion) {
     }
     return drift;
 }
-function render(root, file, previous) {
+/** Read-only preview of the exact bytes apply writes, retaining authored regions and extensions. */
+export function renderFile(root, file, previous) {
     const path = join(root, file.path);
     if (file.kind === "file")
         return file.content;
@@ -468,7 +469,7 @@ export function apply(root, plan, toolfactoryVersion) {
             }
         }
         else {
-            const next = render(root, file, previous);
+            const next = renderFile(root, file, previous);
             if (existsSync(path) && readFileSync(path, "utf8") === next) {
                 result.unchanged.push(file.path);
             }

package/dist/project/load.js

@@ -1,10 +1,13 @@
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync } from "node:fs";
 import { createRequire } from "node:module";
-import { join, relative, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { z } from "zod";
 import { readIdentityFile } from "../identity/read.js";
 import { CAPABILITIES, isInstructionOnly, PACKAGE_MANAGERS, ToolConfigSchema, } from "../model.js";
-import { TOOLFACTORY_DIR } from "./lock.js";
+import { has } from "../surfaces/shared.js";
+import { skillFile } from "../surfaces/skill.js";
+import { renderFile } from "./apply.js";
+import { readLock, TOOLFACTORY_DIR } from "./lock.js";
 export const TOOL_PATH = `${TOOLFACTORY_DIR}/tool.json`;
 export const OPS_PATH = `${TOOLFACTORY_DIR}/ops.json`;
 const require = createRequire(import.meta.url);
@@ -62,13 +65,27 @@ function readPackageManager(root) {
     }
     return name;
 }
-/** `.agents/skills/<name>/` as a shippable unit: every file, sorted, content in memory. */
-function readProjectSkill(root, name) {
-    const directory = join(root, ".agents", "skills", name);
-    if (!existsSync(directory)) {
+/** The selected skill as a shippable unit: every text file, sorted, content in memory. */
+function readProjectSkill(project, name) {
+    const canonPath = `.agents/skills/${name}`;
+    const canon = join(project.root, canonPath);
+    const lock = readLock(project.root) ?? {
+        toolfactoryVersion: project.toolfactoryVersion,
+        files: {},
+    };
+    const entry = lstatSync(canon, { throwIfNoEntry: false });
+    const generatedAlias = entry?.isSymbolicLink() &&
+        resolve(dirname(canon), readlinkSync(canon)) === join(project.root, "skills", name);
+    const custom = project.tool.openclaw?.skills !== undefined &&
+        lock.files[canonPath]?.state === "manual" &&
+        !generatedAlias;
+    const own = has(project, "skill") && name === project.identity.name && !custom;
+    const planned = own ? skillFile(project) : undefined;
+    const directory = planned ? dirname(join(project.root, planned.path)) : canon;
+    if (!existsSync(directory) && !own) {
         throw new Error(`openclaw.skills declares "${name}" but ${join(".agents", "skills", name)} does not exist`);
     }
-    const files = readdirSync(directory, { recursive: true, withFileTypes: true })
+    const files = (existsSync(directory) ? readdirSync(directory, { recursive: true, withFileTypes: true }) : [])
         .filter((entry) => entry.isFile())
         .map((entry) => join(entry.parentPath, entry.name))
         .sort()
@@ -76,6 +93,18 @@ function readProjectSkill(root, name) {
         path: relative(directory, absolute).replaceAll(sep, "/"),
         content: readFileSync(absolute, "utf8"),
     }));
+    if (planned) {
+        const content = lock.files[planned.path]?.state === "manual"
+            ? readFileSync(join(project.root, planned.path), "utf8")
+            : renderFile(project.root, planned, lock);
+        return {
+            name,
+            files: [
+                ...files.filter((file) => file.path !== "SKILL.md"),
+                { path: "SKILL.md", content },
+            ].sort((a, b) => a.path.localeCompare(b.path)),
+        };
+    }
     return { name, files };
 }
 export function loadProject(rootInput = ".") {
@@ -86,14 +115,17 @@ export function loadProject(rootInput = ".") {
     }
     const tool = ToolConfigSchema.parse(JSON.parse(readFileSync(toolPath, "utf8")));
     const identityFile = readIdentityFile(join(root, tool.identity));
-    return {
+    const project = {
         root,
         tool,
         identity: identityFile.identity,
         identityExtra: identityFile.extra,
         operations: isInstructionOnly(tool) ? [] : readOps(root),
-        skills: (tool.openclaw?.skills ?? []).map((name) => readProjectSkill(root, name)),
         toolfactoryVersion: TOOLFACTORY_VERSION,
         packageManager: readPackageManager(root),
     };
+    const names = tool.openclaw?.skills ??
+        (has(project, "openclaw-native") && has(project, "skill") ? [project.identity.name] : []);
+    project.skills = names.map((name) => readProjectSkill(project, name));
+    return project;
 }

package/dist/project/load.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/project/load.test.js

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { build } from "../commands.js";
+import { HOST_DIR } from "../surfaces/openclaw-native.js";
+import { check, setState } from "./apply.js";
+import { loadProject } from "./load.js";
+import { buildPlan } from "./plan.js";
+const roots = [];
+afterEach(() => {
+    for (const root of roots.splice(0))
+        rmSync(root, { recursive: true, force: true });
+});
+function write(root, path, content) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), content);
+}
+function fixture(overrides = {}) {
+    const root = mkdtempSync(join(tmpdir(), "toolfactory-skills-"));
+    roots.push(root);
+    write(root, "plugin.json", JSON.stringify({ name: "probe", version: "0.1.0", description: "Probe" }));
+    write(root, "dev.toolfactory/tool.json", JSON.stringify({
+        schemaVersion: 1,
+        identity: "plugin.json",
+        binding: "typescript",
+        surfaces: ["skill", "cli", "openclaw-native"],
+        ...overrides,
+    }));
+    write(root, "dev.toolfactory/ops.json", JSON.stringify({
+        tools: [
+            {
+                name: "echo",
+                description: "Current operation",
+                inputSchema: { type: "object" },
+            },
+        ],
+    }));
+    return root;
+}
+function hostJson(root, name) {
+    return JSON.parse(readFileSync(join(root, HOST_DIR, name), "utf8"));
+}
+function clean(root) {
+    const project = loadProject(root);
+    expect(check(root, buildPlan(project), project.toolfactoryVersion)).toEqual([]);
+    expect(build(root).result.written).toEqual([]);
+}
+describe("OpenClaw skill loading and regeneration", () => {
+    it.each(["typescript", "python"])("ships a fresh %s tool's own skill by default", (binding) => {
+        const root = fixture({ binding });
+        expect(existsSync(join(root, "skills"))).toBe(false);
+        expect(loadProject(root).skills?.map((skill) => skill.name)).toEqual(["probe"]);
+        build(root);
+        const own = readFileSync(join(root, "skills/probe/SKILL.md"), "utf8");
+        expect(readFileSync(join(root, HOST_DIR, "skills/probe/SKILL.md"), "utf8")).toBe(own);
+        expect(own).toContain("Current operation");
+        expect(hostJson(root, "openclaw.plugin.json").skills).toEqual(["./skills"]);
+        expect(hostJson(root, "package.json").files).toContain("skills");
+        clean(root);
+    });
+    it.each([[], ["custom"], ["probe"], ["probe", "custom"]])("honors the exact explicit selection %j", (...names) => {
+        const skills = names;
+        const root = fixture({ openclaw: { skills } });
+        write(root, ".agents/skills/custom/SKILL.md", "Custom authored skill\n");
+        write(root, ".agents/skills/custom/references/guide.md", "Custom reference\n");
+        expect(loadProject(root).skills?.map((skill) => skill.name)).toEqual(skills);
+        build(root);
+        expect(existsSync(join(root, HOST_DIR, "skills/probe/SKILL.md"))).toBe(skills.includes("probe"));
+        expect(existsSync(join(root, HOST_DIR, "skills/custom/SKILL.md"))).toBe(skills.includes("custom"));
+        if (skills.includes("custom")) {
+            expect(readFileSync(join(root, HOST_DIR, "skills/custom/references/guide.md"), "utf8")).toBe("Custom reference\n");
+        }
+        expect(hostJson(root, "openclaw.plugin.json").skills).toEqual(skills.length ? ["./skills"] : undefined);
+        expect(hostJson(root, "package.json").files.includes("skills")).toBe(skills.length > 0);
+        clean(root);
+    });
+    it("refreshes generated regions in one build while retaining authored prose and text resources", () => {
+        const root = fixture({ openclaw: { skills: ["probe"] } });
+        build(root);
+        const path = "skills/probe/SKILL.md";
+        write(root, path, readFileSync(join(root, path), "utf8").replace("# probe", "# probe\n\nAuthored procedure."));
+        write(root, "skills/probe/scripts/check.py", "print('retained')\n");
+        write(root, "plugin.json", JSON.stringify({ name: "probe", version: "0.2.0", description: "Updated identity" }));
+        write(root, "dev.toolfactory/ops.json", JSON.stringify({
+            tools: [
+                {
+                    name: "new_operation",
+                    description: "Updated operation",
+                    inputSchema: { type: "object" },
+                },
+            ],
+        }));
+        build(root);
+        const bundled = readFileSync(join(root, HOST_DIR, path), "utf8");
+        expect(bundled).toBe(readFileSync(join(root, path), "utf8"));
+        expect(bundled).toContain("Authored procedure.");
+        expect(bundled).toContain("Updated identity");
+        expect(bundled).toContain("Updated operation");
+        expect(bundled).not.toContain("Current operation");
+        expect(readFileSync(join(root, HOST_DIR, "skills/probe/scripts/check.py"), "utf8")).toBe("print('retained')\n");
+        clean(root);
+    });
+    it("removes the default payload and manifest root when the author opts out", () => {
+        const root = fixture();
+        build(root);
+        const path = join(root, "dev.toolfactory/tool.json");
+        writeFileSync(path, JSON.stringify({ ...JSON.parse(readFileSync(path, "utf8")), openclaw: { skills: [] } }));
+        build(root);
+        expect(existsSync(join(root, HOST_DIR, "skills/probe/SKILL.md"))).toBe(false);
+        expect(existsSync(join(root, "skills/probe/SKILL.md"))).toBe(true);
+        expect(hostJson(root, "openclaw.plugin.json")).not.toHaveProperty("skills");
+        expect(hostJson(root, "package.json").files).not.toContain("skills");
+        clean(root);
+    });
+    it("packages an adopted own skill verbatim", () => {
+        const root = fixture();
+        build(root);
+        setState(root, "skills/probe/SKILL.md", "manual", loadProject(root).toolfactoryVersion);
+        write(root, "skills/probe/SKILL.md", "Fully authored skill without generator markers\n");
+        build(root);
+        expect(readFileSync(join(root, HOST_DIR, "skills/probe/SKILL.md"), "utf8")).toBe("Fully authored skill without generator markers\n");
+        clean(root);
+    });
+    it("retains an explicitly selected same-name custom canon when its alias was adopted", () => {
+        const root = fixture({ openclaw: { skills: ["probe"] } });
+        build(root);
+        setState(root, ".agents/skills/probe", "manual", loadProject(root).toolfactoryVersion);
+        rmSync(join(root, ".agents/skills/probe"));
+        write(root, ".agents/skills/probe/SKILL.md", "Custom same-name procedure\n");
+        write(root, ".agents/skills/probe/references/guide.md", "Custom same-name reference\n");
+        build(root);
+        expect(readFileSync(join(root, HOST_DIR, "skills/probe/SKILL.md"), "utf8")).toBe("Custom same-name procedure\n");
+        expect(readFileSync(join(root, HOST_DIR, "skills/probe/references/guide.md"), "utf8")).toBe("Custom same-name reference\n");
+        expect(readFileSync(join(root, "skills/probe/SKILL.md"), "utf8")).toContain("Current operation");
+        expect(readFileSync(join(root, ".agents/skills/probe/SKILL.md"), "utf8")).toBe("Custom same-name procedure\n");
+        clean(root);
+    });
+    it("does not infer a skill for projects without the selected pair and still validates declared custom skills", () => {
+        const hostOnly = fixture({ surfaces: ["openclaw-native"] });
+        build(hostOnly);
+        expect(loadProject(hostOnly).skills).toEqual([]);
+        expect(hostJson(hostOnly, "openclaw.plugin.json")).not.toHaveProperty("skills");
+        const instructions = fixture({ runtime: "none", surfaces: ["skill", "codex"] });
+        build(instructions);
+        expect(loadProject(instructions).skills).toEqual([]);
+        expect(existsSync(join(instructions, HOST_DIR))).toBe(false);
+        expect(readFileSync(join(instructions, "skills/probe/SKILL.md"), "utf8")).not.toContain("## Operations");
+        const custom = fixture({ surfaces: ["openclaw-native"], openclaw: { skills: ["custom"] } });
+        expect(() => loadProject(custom)).toThrow(/openclaw.skills declares "custom"/);
+        write(custom, ".agents/skills/custom/SKILL.md", "Custom only\n");
+        build(custom);
+        expect(readFileSync(join(custom, HOST_DIR, "skills/custom/SKILL.md"), "utf8")).toBe("Custom only\n");
+        clean(hostOnly);
+        clean(instructions);
+        clean(custom);
+    });
+});

package/dist/project/plan.js

@@ -86,7 +86,9 @@ export function buildPlan(project, surfaces = selectedSurfaces(project.tool.surf
     const manual = Object.entries(lock?.files ?? {})
         .filter(([, entry]) => entry.state === "manual")
         .map(([path]) => path);
-    const total = Object.keys(lock?.files ?? {}).length || files.length;
+    // Count the plan being applied, including retained manual files, rather than the previous
+    // lock: newly bundled skill resources must not leave COVERAGE.md stale after one build.
+    const total = new Set([...files.map((file) => file.path), ...manual, "COVERAGE.md"]).size;
     files.push({
         kind: "file",
         path: "COVERAGE.md",

package/dist/surfaces/openclaw-native.d.ts

@@ -96,7 +96,7 @@ export declare const ENTRY_END = "// /tf:entry";
 export declare function displayName(id: string): string;
 /** Host registrations the plugin declares beyond tools. */
 export declare function registrations(project: Project): Registration[];
-/** Whether the plugin ships `.agents/skills/` directories (`openclaw.skills` in tool.json). */
+/** Whether the loader resolved any skills for this plugin's payload. */
 export declare function shipsSkills(project: Project): boolean;
 /** `activation` for both the entry and the manifest; OpenClaw's own default is startup. */
 export declare function activation(project: Project): Record<string, unknown>;

package/dist/surfaces/openclaw-native.js

@@ -124,9 +124,9 @@ export function displayName(id) {
 export function registrations(project) {
     return project.tool.openclaw?.registers ?? [];
 }
-/** Whether the plugin ships `.agents/skills/` directories (`openclaw.skills` in tool.json). */
+/** Whether the loader resolved any skills for this plugin's payload. */
 export function shipsSkills(project) {
-    return (project.tool.openclaw?.skills?.length ?? 0) > 0;
+    return (project.skills?.length ?? 0) > 0;
 }
 /**
  * The gateway route and the Control UI tab the plugin adds when the tool also has a `web`

package/dist/surfaces/skill.d.ts

@@ -1,7 +1,8 @@
-import { type Project, type Surface } from "../model.js";
+import { type Project, type RegionFile, type Surface } from "../model.js";
 export declare const OPERATIONS_BEGIN = "<!-- tf:operations -->";
 export declare const OPERATIONS_END = "<!-- /tf:operations -->";
 export declare function skillPath(project: Project): string;
 export declare function renderOperations(project: Project): string;
 export declare function frontmatter(project: Project): string;
+export declare function skillFile(project: Project): RegionFile;
 export declare const surface: Surface;

package/dist/surfaces/skill.js

@@ -68,28 +68,31 @@ export function frontmatter(project) {
     });
     return `\n${yaml(document).trimEnd()}\n`;
 }
+export function skillFile(project) {
+    const path = skillPath(project);
+    const regions = [
+        { begin: "---", end: "---", content: frontmatter(project) },
+        { begin: OPERATIONS_BEGIN, end: OPERATIONS_END, content: renderOperations(project) },
+    ];
+    const template = [
+        "---",
+        "---",
+        "",
+        `# ${project.identity.name}`,
+        "",
+        "Explain here when an agent should reach for this tool and how to combine its operations.",
+        "",
+        OPERATIONS_BEGIN,
+        OPERATIONS_END,
+        "",
+    ].join("\n");
+    return { kind: "region", path, regions, template };
+}
 export const surface = {
     id: "skill",
     plan(project) {
-        const path = skillPath(project);
-        const regions = [
-            { begin: "---", end: "---", content: frontmatter(project) },
-            { begin: OPERATIONS_BEGIN, end: OPERATIONS_END, content: renderOperations(project) },
-        ];
-        const template = [
-            "---",
-            "---",
-            "",
-            `# ${project.identity.name}`,
-            "",
-            "Explain here when an agent should reach for this tool and how to combine its operations.",
-            "",
-            OPERATIONS_BEGIN,
-            OPERATIONS_END,
-            "",
-        ].join("\n");
         return [
-            { kind: "region", path, regions, template },
+            skillFile(project),
             {
                 kind: "file",
                 path: skillLinkPath(project),

package/dist/toolfactory/cli.js

@@ -11,7 +11,7 @@ const operations = [...authored, web];
 const program = new Command()
     .name("toolfactory")
     .description("Build an agent tool once; ship it as Agent Skills, MCP servers, Agent Plugins / Claude / Codex / Cursor bundles, OpenClaw and Hermes plugins, CLIs, and packages, with the tests and releases to match.")
-    .version("0.4.5");
+    .version("0.4.6");
 for (const op of operations) {
     if (!serves(op, "cli"))
         continue;

package/dist/toolfactory/mcp.js

@@ -30,7 +30,7 @@ const operations = [...authored, web];
 const introspecting = Boolean(process.env.TOOLFACTORY_INTROSPECT);
 /** Builds one server instance with every servable operation registered; called once for stdio, once per HTTP request. */
 function createServer() {
-    const server = new McpServer({ name: "toolfactory", version: "0.4.5" });
+    const server = new McpServer({ name: "toolfactory", version: "0.4.6" });
     for (const op of operations) {
         if (!introspecting && !serves(op, "mcp"))
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolfactory",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "Build an agent tool once; ship it as Agent Skills, MCP servers, Agent Plugins / Claude / Codex / Cursor bundles, OpenClaw and Hermes plugins, CLIs, and packages, with the tests and releases to match.",
   "license": "MIT",
   "repository": {

package/src/e2e.test.ts

@@ -7,6 +7,7 @@ import { execFileSync } from "node:child_process";
 import {
   existsSync,
   lstatSync,
+  mkdirSync,
   mkdtempSync,
   readdirSync,
   readFileSync,
@@ -33,7 +34,15 @@ describe.skipIf(!existsSync(repoNodeModules))(
       const dir = mkdtempSync(join(tmpdir(), "toolfactory-e2e-"));
       symlinkSync(repoNodeModules, join(dir, "node_modules"), "dir");
 
-      const surfaces: SurfaceId[] = ["skill", "agent-plugins", "claude", "mcp", "cli", "npm"];
+      const surfaces: SurfaceId[] = [
+        "skill",
+        "agent-plugins",
+        "claude",
+        "mcp",
+        "cli",
+        "npm",
+        "openclaw-native",
+      ];
       const init = commands.init({
         root: dir,
         name: "hello",
@@ -53,8 +62,42 @@ describe.skipIf(!existsSync(repoNodeModules))(
       expect(echo.inputSchema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
       expect(echo.outputSchema?.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
 
-      commands.build(dir);
+      const skillPath = join(dir, "skills/hello/SKILL.md");
+      writeFileSync(
+        skillPath,
+        readFileSync(skillPath, "utf8").replace("# hello", "# hello\n\nAuthor procedure."),
+      );
+      mkdirSync(join(dir, "skills/hello/references"));
+      writeFileSync(join(dir, "skills/hello/references/guide.md"), "Retained reference.\n");
+      const opsPath = join(dir, "src/ops.ts");
+      writeFileSync(
+        opsPath,
+        readFileSync(opsPath, "utf8").replace(
+          "Return the text you pass in.",
+          "Freshly rebuilt operation.",
+        ),
+      );
+      await commands.introspect(dir);
       await expect(commands.check(dir)).resolves.toBeDefined();
+      expect(commands.build(dir).result.written).toEqual([]);
+      const bundled = readFileSync(join(dir, "hosts/openclaw/skills/hello/SKILL.md"), "utf8");
+      expect(bundled).toBe(readFileSync(skillPath, "utf8"));
+      expect(bundled).toContain("Author procedure.");
+      expect(bundled).toContain("Freshly rebuilt operation.");
+      expect(bundled).not.toContain("Return the text you pass in.");
+      const packed = JSON.parse(
+        execFileSync("npm", ["pack", "./hosts/openclaw", "--dry-run", "--json"], {
+          cwd: dir,
+          encoding: "utf8",
+        }),
+      ) as { files: { path: string }[] }[];
+      expect(packed[0]?.files.map((file) => file.path)).toEqual(
+        expect.arrayContaining([
+          "openclaw.plugin.json",
+          "skills/hello/SKILL.md",
+          "skills/hello/references/guide.md",
+        ]),
+      );
 
       const opsOnDisk = JSON.parse(readFileSync(join(dir, "dev.toolfactory/ops.json"), "utf8"));
       expect(opsOnDisk.tools.map((t: { name: string }) => t.name)).toEqual(["echo"]);

package/src/hosts/openclaw.ts

@@ -16,7 +16,7 @@ import { fileURLToPath } from "node:url";
 import type { PlannedFile, Project } from "../model.js";
 import type { Drift } from "../project/apply.js";
 import { loadProject } from "../project/load.js";
-import { HOST_DIR, OPENCLAW_SCAFFOLD, surface } from "../surfaces/openclaw-native.js";
+import { HOST_DIR, OPENCLAW_SCAFFOLD, shipsSkills, surface } from "../surfaces/openclaw-native.js";
 
 export const DRIFT_ENTRY = fileURLToPath(import.meta.url);
 
@@ -39,7 +39,7 @@ function overridden(project: Project): Set<string> {
     paths.add(".openclaw.compat.pluginApi");
   }
   // Shipped skills append to `files`; upstream's entries must still survive (checked below).
-  if (openclaw?.skills?.length) paths.add(".files");
+  if (shipsSkills(project)) paths.add(".files");
   return paths;
 }
 
@@ -111,7 +111,7 @@ export function scaffoldDrift(project: Project): string[] {
         ? []
         : ["vitest.config.ts: upstream template changed"]),
     ];
-    if (project.tool.openclaw?.skills?.length) {
+    if (shipsSkills(project)) {
       const upstream = (JSON.parse(scaffold("package.json")) as { files?: string[] }).files ?? [];
       const ours = (JSON.parse(planned(files, "package.json")) as { files?: string[] }).files ?? [];
       const lost = upstream.filter((entry) => !ours.includes(entry));