harness-alchemist 0.1.0 → 0.1.2

package/.claude-plugin/plugin.json

@@ -2,13 +2,13 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "harness-alchemist",
   "displayName": "Harness Alchemist",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffold, validate, and publish portable coding-agent plugins across Claude Code, Codex, OpenCode, Antigravity, and DeepSeek Harness.",
   "author": {
     "name": "Haochuan Zhang"
   },
-  "homepage": "https://github.com/lunarmoon26/harness-alchemist",
-  "repository": "https://github.com/lunarmoon26/harness-alchemist",
+  "homepage": "git+https://github.com/lunarmoon26/harness-alchemist.git",
+  "repository": "git+https://github.com/lunarmoon26/harness-alchemist.git",
   "license": "MIT",
   "skills": "./skills/"
 }

package/.codex-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "harness-alchemist",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffold, validate, and publish portable coding-agent plugins across Claude Code, Codex, OpenCode, Antigravity, and DeepSeek Harness.",
   "author": {
     "name": "Haochuan Zhang",
-    "url": "https://github.com/lunarmoon26/harness-alchemist"
+    "url": "git+https://github.com/lunarmoon26/harness-alchemist.git"
   },
-  "homepage": "https://github.com/lunarmoon26/harness-alchemist",
-  "repository": "https://github.com/lunarmoon26/harness-alchemist",
+  "homepage": "git+https://github.com/lunarmoon26/harness-alchemist.git",
+  "repository": "git+https://github.com/lunarmoon26/harness-alchemist.git",
   "license": "MIT",
   "skills": "./skills/"
 }

package/dist/deepseek.d.ts

@@ -1,4 +1,5 @@
 import type { Context } from "@deepseek-ai/cordis";
 export declare const name = "harness-alchemist";
-export declare function apply(_context: Context): void;
+export declare function runSkillScript(script: string, payload: string): unknown;
+export declare function apply(context: Context): void;
 //# sourceMappingURL=deepseek.d.ts.map

package/dist/deepseek.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deepseek.d.ts","sourceRoot":"","sources":["../src/deepseek.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,eAAO,MAAM,IAAI,sBAAsB,CAAA;AAEvC,wBAAgB,KAAK,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAE7C"}
+{"version":3,"file":"deepseek.d.ts","sourceRoot":"","sources":["../src/deepseek.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,eAAO,MAAM,IAAI,sBAAsB,CAAA;AAQvC,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAcvE;AAED,wBAAgB,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK5C"}

package/dist/deepseek.js

@@ -1,5 +1,26 @@
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 export const name = "harness-alchemist";
-export function apply(_context) {
-    // Register Cordis services, tools, or lifecycle effects here.
+const scriptsDirectory = join(dirname(fileURLToPath(import.meta.url)), "..", "skills/harness-alchemist/scripts");
+export function runSkillScript(script, payload) {
+    const runtime = script.endsWith(".py") ? "python3" : process.execPath;
+    const result = spawnSync(runtime, [join(scriptsDirectory, script)], {
+        input: payload,
+        encoding: "utf8",
+    });
+    if (result.error) {
+        throw new Error(`Could not run ${script} via ${runtime}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        const diagnostic = result.stderr.trim() || `${script} exited with code ${result.status}`;
+        throw new Error(diagnostic);
+    }
+    return JSON.parse(result.stdout);
+}
+export function apply(context) {
+    context.provide(name, {
+        run: (payload, runtime = "node") => runSkillScript(runtime === "python" ? "main.py" : "main.mjs", payload),
+    });
 }
 //# sourceMappingURL=deepseek.js.map

package/dist/deepseek.js.map

@@ -1 +1 @@
-{"version":3,"file":"deepseek.js","sourceRoot":"","sources":["../src/deepseek.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,IAAI,GAAG,mBAAmB,CAAA;AAEvC,MAAM,UAAU,KAAK,CAAC,QAAiB;IACrC,8DAA8D;AAChE,CAAC"}
+{"version":3,"file":"deepseek.js","sourceRoot":"","sources":["../src/deepseek.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAC9C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAIxC,MAAM,CAAC,MAAM,IAAI,GAAG,mBAAmB,CAAA;AAEvC,MAAM,gBAAgB,GAAG,IAAI,CAC3B,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EACvC,IAAI,EACJ,kCAAkC,CACnC,CAAA;AAED,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,OAAe;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAA;IACrE,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,EAAE;QAClE,KAAK,EAAE,OAAO;QACd,QAAQ,EAAE,MAAM;KACjB,CAAC,CAAA;IACF,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,iBAAiB,MAAM,QAAQ,OAAO,KAAK,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;IACpF,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,qBAAqB,MAAM,CAAC,MAAM,EAAE,CAAA;QACxF,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAA;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;AAClC,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,OAAgB;IACpC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE;QACpB,GAAG,EAAE,CAAC,OAAe,EAAE,UAA6B,MAAM,EAAE,EAAE,CAC5D,cAAc,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC;KACzE,CAAC,CAAA;AACJ,CAAC"}

package/dist/opencode.d.ts

@@ -1,3 +1,21 @@
-declare const plugin: () => Promise<{}>;
+export declare function runSkillScript(script: string, payload: string): Promise<string>;
+declare const plugin: () => Promise<{
+    tool: {
+        harness_alchemist_run: {
+            description: string;
+            args: {
+                input: import("zod").ZodString;
+                runtime: import("zod").ZodOptional<import("zod").ZodEnum<{
+                    node: "node";
+                    python: "python";
+                }>>;
+            };
+            execute(args: {
+                input: string;
+                runtime?: "node" | "python" | undefined;
+            }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
+        };
+    };
+}>;
 export default plugin;
 //# sourceMappingURL=opencode.d.ts.map

package/dist/opencode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"opencode.d.ts","sourceRoot":"","sources":["../src/opencode.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,MAAM,mBAEO,CAAA;AAEnB,eAAe,MAAM,CAAA"}
+{"version":3,"file":"opencode.d.ts","sourceRoot":"","sources":["../src/opencode.ts"],"names":[],"mappings":"AAaA,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA0B/E;AAED,QAAA,MAAM,MAAM;;;;;;;;;;;;;;;;;EAuBO,CAAA;AAEnB,eAAe,MAAM,CAAA"}

package/dist/opencode.js

@@ -1,5 +1,58 @@
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tool } from "@opencode-ai/plugin";
+const scriptsDirectory = join(dirname(fileURLToPath(import.meta.url)), "..", "skills/harness-alchemist/scripts");
+export function runSkillScript(script, payload) {
+    return new Promise((resolveResult, rejectResult) => {
+        const runtime = script.endsWith(".py") ? "python3" : process.execPath;
+        const child = spawn(runtime, [join(scriptsDirectory, script)], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            rejectResult(new Error(`Could not run ${script} via ${runtime}: ${error.message}`));
+        });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                rejectResult(new Error(stderr.trim() || `${script} exited with code ${code}`));
+            }
+            else {
+                resolveResult(stdout);
+            }
+        });
+        child.stdin.end(payload);
+    });
+}
 const plugin = (async () => {
-    return {};
+    return {
+        tool: {
+            harness_alchemist_run: tool({
+                description: "Run the Harness Alchemist shared-skill workflow. Delegates to skills/harness-alchemist/scripts.",
+                args: {
+                    input: tool.schema
+                        .string()
+                        .describe("JSON object passed on stdin to the skill entrypoint"),
+                    runtime: tool.schema
+                        .enum(["node", "python"])
+                        .optional()
+                        .describe("Entrypoint runtime; defaults to node"),
+                },
+                execute: async (args) => {
+                    const script = args.runtime === "python" ? "main.py" : "main.mjs";
+                    const output = await runSkillScript(script, args.input);
+                    return JSON.stringify(JSON.parse(output));
+                },
+            }),
+        },
+    };
 });
 export default plugin;
 //# sourceMappingURL=opencode.js.map

package/dist/opencode.js.map

@@ -1 +1 @@
-{"version":3,"file":"opencode.js","sourceRoot":"","sources":["../src/opencode.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE;IACzB,OAAO,EAAE,CAAA;AACX,CAAC,CAAkB,CAAA;AAEnB,eAAe,MAAM,CAAA"}
+{"version":3,"file":"opencode.js","sourceRoot":"","sources":["../src/opencode.ts"],"names":[],"mappings":"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"}

package/lib/validate.mjs

@@ -31,6 +31,11 @@ Validates a universal Claude, Codex, OpenCode, Antigravity, and DeepSeek
 plugin scaffold. By default the project is resolved from the current working
 directory or from the script's containing generated project.
 
+Product skills are checked against the Agent Skills specification and their
+scripts against the shared tool contract. When the optional 'pyodide'
+devDependency is installed, Python entrypoints are also syntax-checked and
+smoke-executed in a WebAssembly CPython sandbox.
+
 Options:
   --external  Run installed platform validators, currently Claude Code.
   --json      Print a machine-readable result.
@@ -230,6 +235,110 @@ function exportTarget(exports, key, field = "import") {
   return undefined
 }
 
+const PYTHON_SMOKE_PROGRAM = `
+import contextlib
+import io
+import json
+import sys
+
+sys.stdin = io.StringIO(__ha_payload__)
+_buffer = io.StringIO()
+try:
+    with contextlib.redirect_stdout(_buffer):
+        exec(compile(__ha_source__, "<skill>", "exec"), {"__name__": "__main__"})
+except SystemExit as exit_code:
+    if exit_code.code not in (0, None):
+        raise RuntimeError(f"script exited with code {exit_code.code}")
+_buffer.getvalue()
+`
+
+async function smokePythonScripts(scripts, errors, warnings) {
+  let loadPyodide
+  try {
+    ;({ loadPyodide } = await import("pyodide"))
+  } catch {
+    warnings.push("pyodide is not installed; skipped WebAssembly Python validation")
+    return
+  }
+
+  let instance
+  try {
+    instance = await loadPyodide()
+  } catch (error) {
+    warnings.push(`Pyodide failed to initialize (${error.message}); skipped WebAssembly Python validation`)
+    return
+  }
+
+  for (const script of scripts) {
+    const source = await readFile(script, "utf8")
+    instance.globals.set("__ha_source__", source)
+    instance.globals.set("__ha_payload__", "{}")
+    let output
+    try {
+      output = instance.runPython(PYTHON_SMOKE_PROGRAM)
+    } catch (error) {
+      errors.push(`${script}: WebAssembly Python check failed (${String(error).split("\n").at(-2) ?? String(error)})`)
+      continue
+    }
+    try {
+      const parsed = JSON.parse(output)
+      if (parsed?.ok !== true || typeof parsed.plugin !== "string") {
+        errors.push(`${script}: unexpected tool-contract result ${output.trim()}`)
+      }
+    } catch {
+      errors.push(`${script}: did not print a JSON object per the tool contract`)
+    }
+  }
+
+  instance.globals.delete("__ha_source__")
+  instance.globals.delete("__ha_payload__")
+}
+
+async function checkProductSkillRuntime(skillFile, content, frontmatter, errors, pythonScripts) {
+  if ((frontmatter.description?.length ?? 0) > 1024) {
+    errors.push(`${skillFile}: description must be at most 1024 characters`)
+  }
+  if ((frontmatter.compatibility?.length ?? 0) > 500) {
+    errors.push(`${skillFile}: compatibility must be at most 500 characters`)
+  }
+
+  const skillDirectory = dirname(skillFile)
+  const references = new Set(
+    [...content.matchAll(/(?:scripts|references|assets)\/[A-Za-z0-9][A-Za-z0-9._/-]*/g)].map(
+      (match) => match[0].replace(/[.,;:)\]]+$/, ""),
+    ),
+  )
+  for (const reference of references) {
+    if (!existsSync(join(skillDirectory, ...reference.split("/")))) {
+      errors.push(`${skillFile}: referenced path '${reference}' does not exist`)
+    }
+  }
+
+  const scriptsDirectory = join(skillDirectory, "scripts")
+  if (!existsSync(scriptsDirectory)) return
+
+  const entries = await readdir(scriptsDirectory)
+  const pythonBases = new Set(
+    entries.filter((entry) => entry.endsWith(".py")).map((entry) => entry.slice(0, -3)),
+  )
+  const mjsBases = new Set(
+    entries.filter((entry) => entry.endsWith(".mjs")).map((entry) => entry.slice(0, -4)),
+  )
+  for (const base of pythonBases) {
+    if (!mjsBases.has(base)) {
+      errors.push(`${skillFile}: scripts/${base}.py is missing its scripts/${base}.mjs twin`)
+    }
+  }
+  for (const base of mjsBases) {
+    if (!pythonBases.has(base)) {
+      errors.push(`${skillFile}: scripts/${base}.mjs is missing its scripts/${base}.py twin`)
+    }
+  }
+  for (const entry of entries.filter((entry) => entry.endsWith(".py"))) {
+    pythonScripts.add(join(scriptsDirectory, entry))
+  }
+}
+
 export async function validateProject(projectRoot, options = {}) {
   const root = resolve(projectRoot)
   const errors = []
@@ -350,14 +459,15 @@ export async function validateProject(projectRoot, options = {}) {
     errors.push(`cordis.patch.yml entry '${pluginName}' must load '${expectedModule}'`)
   }
 
-  const skillFiles = [
-    ...(await collectSkillFiles(root, "skills")),
-    ...(await collectSkillFiles(root, ".agents/skills")),
-  ]
+  const maintenanceSkillFiles = await collectSkillFiles(root, ".agents/skills")
+  const productSkillFiles = await collectSkillFiles(root, "skills")
+  const skillFiles = [...productSkillFiles, ...maintenanceSkillFiles]
   if (skillFiles.length < 2) errors.push("Expected a shared skill and a project development skill")
 
+  const pythonScripts = new Set()
   for (const skillFile of skillFiles) {
-    const frontmatter = parseFrontmatter(await readFile(skillFile, "utf8"))
+    const content = await readFile(skillFile, "utf8")
+    const frontmatter = parseFrontmatter(content)
     const directoryName = basename(dirname(skillFile))
     if (!frontmatter) errors.push(`${skillFile}: missing YAML frontmatter`)
     else {
@@ -368,9 +478,16 @@ export async function validateProject(projectRoot, options = {}) {
       if (!validName.test(frontmatter.name ?? "") || (frontmatter.name?.length ?? 0) > 64) {
         errors.push(`${skillFile}: invalid Agent Skill name`)
       }
+      if (productSkillFiles.includes(skillFile)) {
+        await checkProductSkillRuntime(skillFile, content, frontmatter, errors, pythonScripts)
+      }
     }
   }
 
+  if (pythonScripts.size > 0) {
+    await smokePythonScripts([...pythonScripts], errors, warnings)
+  }
+
   for (const path of await scanForTokens(root)) {
     errors.push(`${path}: unresolved scaffold token`)
   }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "harness-alchemist",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffold, validate, and publish portable coding-agent plugins across Claude Code, Codex, OpenCode, Antigravity, and DeepSeek Harness.",
   "type": "module",
   "bin": {
-    "harness-alchemist": "./bin/harness-alchemist.mjs"
+    "harness-alchemist": "bin/harness-alchemist.mjs"
   },
   "main": "./dist/opencode.js",
   "types": "./dist/opencode.d.ts",
@@ -70,13 +70,15 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@opencode-ai/plugin": "^1.18.21",
+    "@types/node": "^26.2.0",
+    "pyodide": "^314.0.5",
     "typescript": "^5.9.3"
   },
   "author": "Haochuan Zhang",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/lunarmoon26/harness-alchemist"
+    "url": "git+https://github.com/lunarmoon26/harness-alchemist.git"
   },
   "dsh": {
     "bundle": {

package/skills/harness-alchemist/SKILL.md

@@ -56,3 +56,12 @@ npm pack --dry-run
 ```
 
 Static validation is structural evidence, not proof that remote services or host-specific lifecycle events work.
+
+## Skill Runtime
+
+`scripts/main.mjs` (Node/Bun) and `scripts/main.py` (CPython 3.10+) are
+behavioral twins demonstrating this repository's own tool contract: one JSON
+object on stdin, one JSON result plus newline on stdout, non-zero exit with a
+stderr diagnostic on failure. The `src/` adapters delegate to them; keep any
+contract change mirrored in both twins and in
+[references/compatibility.md](references/compatibility.md).

package/skills/harness-alchemist/references/compatibility.md

@@ -12,6 +12,9 @@ project/
 ├── .claude-plugin/plugin.json
 ├── .codex-plugin/plugin.json
 ├── skills/<name>/SKILL.md
+├── skills/<name>/scripts/main.mjs
+├── skills/<name>/scripts/main.py
+├── skills/<name>/references/tool-contract.md
 ├── src/opencode.ts
 ├── src/deepseek.ts
 ├── cordis.patch.yml
@@ -19,6 +22,12 @@ project/
 └── package.json
 ```
 
+Product skills own their runtime: `skills/<name>/scripts/` holds behavioral
+`.mjs`/`.py` twins (one JSON object in on stdin, one JSON result out on
+stdout), and `src/opencode.ts` and `src/deepseek.ts` stay thin adapters that
+spawn those scripts. See the generated project's tool contract reference for
+details.
+
 ## Capability Matrix
 
 | Artifact | Claude | Codex | OpenCode | Antigravity | DeepSeek |

package/skills/harness-alchemist/scripts/main.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Harness Alchemist shared-skill entrypoint (Node/Bun twin of main.py).
+// Reads one JSON payload from stdin and writes one JSON result to stdout.
+// See references/compatibility.md for the full contract.
+
+const chunks = []
+for await (const chunk of process.stdin) chunks.push(chunk)
+
+let request
+try {
+  request = JSON.parse(Buffer.concat(chunks).toString("utf8"))
+} catch (error) {
+  console.error(`Invalid JSON payload: ${error.message}`)
+  process.exit(1)
+}
+
+if (typeof request !== "object" || request === null || Array.isArray(request)) {
+  console.error("Payload must be a JSON object")
+  process.exit(1)
+}
+
+process.stdout.write(`${JSON.stringify({ ok: true, plugin: "harness-alchemist", echo: request })}\n`)

package/skills/harness-alchemist/scripts/main.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""Harness Alchemist shared-skill entrypoint (Python twin of main.mjs).
+
+Reads one JSON payload from stdin and writes one JSON result to stdout.
+See references/compatibility.md for the full contract.
+"""
+
+import json
+import sys
+
+
+def main() -> int:
+    try:
+        request = json.load(sys.stdin)
+    except json.JSONDecodeError as error:
+        print(f"Invalid JSON payload: {error}", file=sys.stderr)
+        return 1
+
+    if not isinstance(request, dict):
+        print("Payload must be a JSON object", file=sys.stderr)
+        return 1
+
+    print(json.dumps({"ok": True, "plugin": "harness-alchemist", "echo": request}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/v0.1.0/universal-typescript/.agents/skills/develop-template/SKILL.md.tpl

@@ -13,6 +13,8 @@ describe development of the Harness Alchemist CLI or its canonical templates.
 
 - `skills/{{NAME}}/SKILL.md` is the plugin's end-user workflow. Replace the
   starter procedure with the capability's domain-specific instructions.
+- `skills/{{NAME}}/scripts/` owns the skill runtime as `.mjs`/`.py` twins;
+  see `skills/{{NAME}}/references/tool-contract.md` before changing them.
 - `.agents/skills/develop-{{NAME}}/` is this repository's maintenance guidance
   and validation tooling.
 - `.claude-plugin/`, `.codex-plugin/`, `.agents/plugins/`, root `plugin.json`,
@@ -24,8 +26,9 @@ describe development of the Harness Alchemist CLI or its canonical templates.
 ## Maintenance
 
 1. Read `references/compatibility.md` before changing manifests or entrypoints.
-2. Put portable end-user workflows in `skills/` and host-specific runtime code
-   only in its corresponding entrypoint.
+2. Put portable end-user workflows and skill-owned scripts in `skills/` and
+   host-specific runtime code, kept to thin delegation adapters, in its
+   corresponding entrypoint.
 3. Run `npm run verify` before reporting completion. Before publishing, inspect
    `npm pack --dry-run` and run `claude plugin validate . --strict` when Claude
    Code is installed.

package/templates/v0.1.0/universal-typescript/.agents/skills/develop-template/references/compatibility.md.tpl

@@ -16,6 +16,35 @@
 | Antigravity | `plugin.json` | Skills use nested `<name>/SKILL.md`. |
 | DeepSeek | `src/deepseek.ts`, `cordis.patch.yml` | Function plugin uses named exports and no default export. |
 
+## Skill Script Contract
+
+- `skills/{{NAME}}/scripts/` owns the skill runtime. Entrypoints come in
+  behavioral `.mjs` and `.py` twins with identical base names.
+- Contract: one JSON object on stdin, one JSON result plus newline on stdout,
+  non-zero exit with a stderr diagnostic on failure. See
+  `skills/{{NAME}}/references/tool-contract.md`.
+- `src/opencode.ts` and `src/deepseek.ts` are thin adapters that spawn these
+  scripts. Workflow logic never lives in the adapters.
+- Maintenance scripts under `.agents/skills/develop-{{NAME}}/scripts/` are
+  maintainer tooling and are exempt from the twin rule.
+
+## Validation Tiers
+
+- Tier B (always): Agent Skills frontmatter compliance, SKILL.md relative-path
+  resolution, and twin parity for product skills.
+- Tier A (when the optional `pyodide` package is installed locally): Python
+  entrypoints are additionally compiled and smoke-executed in a WebAssembly
+  CPython sandbox without requiring native Python. This repository does not
+  declare pyodide as a dependency; install it ad hoc for deeper checks.
+
+## DeepSeek Harness Volatility
+
+DeepSeek Harness (`dsh`) is a developer preview built on the Cordis kernel.
+The generated contract pins only the verified surface: function-form named-
+export plugins, `cordis.patch.yml` insert entries resolving npm module names,
+and the `dsh.bundle.patch` package field. Re-verify against official dsh docs
+before adopting deeper Cordis services.
+
 ## Metadata
 
 `package.json` owns version, description, author, repository, license, and npm package name. `scripts/sync-metadata.mjs` propagates these values without replacing harness-specific fields.

package/templates/v0.1.0/universal-typescript/package.json.tpl

@@ -54,6 +54,7 @@
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@opencode-ai/plugin": "^1.18.21",
+    "@types/node": "^26.2.0",
     "typescript": "^5.9.3"
   },
   "author": {{AUTHOR_JSON}},

package/templates/v0.1.0/universal-typescript/skills/shared-skill/SKILL.md.tpl

@@ -1,6 +1,9 @@
 ---
 name: {{NAME}}
 description: {{SHARED_SKILL_DESCRIPTION_JSON}}
+compatibility: Requires Node.js 22+ or Bun 1.2+ for scripts/main.mjs; optional Python 3.10+ for scripts/main.py.
+metadata:
+  plugin: {{NAME}}
 ---
 
 # {{DISPLAY_NAME}}
@@ -10,9 +13,20 @@ Apply the {{DISPLAY_NAME}} workflow to the user's request.
 ## Workflow
 
 1. Confirm the requested outcome and inspect the relevant project context.
-2. Perform the smallest complete change that satisfies the request.
-3. Use harness-provided tools only when they are needed for the workflow.
-4. Verify the result with the project's available checks.
-5. Report the outcome and any unresolved external dependency.
+2. Run the skill entrypoint to perform the smallest complete change:
+
+   ```
+   echo '{"request": "..."}' | scripts/main.mjs
+   ```
+
+   When Python 3.10+ is available, `scripts/main.py` behaves identically.
+3. Interpret the JSON result; both entrypoints return `{"ok": true, ...}` on
+   success and exit non-zero with a stderr diagnostic on failure.
+4. Use harness-provided tools only when they are needed for the workflow.
+5. Verify the result with the project's available checks.
+6. Report the outcome and any unresolved external dependency.
+
+See [the tool contract](references/tool-contract.md) before changing or adding
+entrypoints, and keep the `.mjs` and `.py` twins behaviorally identical.
 
 Replace this starter workflow with the plugin's domain-specific procedure as the capability develops.

package/templates/v0.1.0/universal-typescript/skills/shared-skill/references/tool-contract.md.tpl

@@ -0,0 +1,35 @@
+# {{DISPLAY_NAME}} Tool Contract
+
+The shared skill owns its runtime. Harness entrypoints are thin adapters that
+delegate to the scripts in this directory; they must not contain workflow logic.
+
+## Entrypoints
+
+| File | Runtime | Requirement |
+| --- | --- | --- |
+| `scripts/main.mjs` | Node.js 22+ or Bun 1.2+ | Zero npm dependencies |
+| `scripts/main.py` | CPython 3.10+ | Standard library only |
+
+`main.mjs` and `main.py` are behavioral twins. Any change to one must be
+mirrored in the other, and both must keep the same name so validators can pair
+them.
+
+## I/O Contract
+
+1. Read exactly one JSON object from stdin.
+2. Write exactly one JSON result followed by a newline to stdout.
+3. On success: `{"ok": true, "plugin": "<plugin-name>", ...}` with exit code 0.
+4. On failure: write a diagnostic to stderr, write nothing to stdout, and exit
+   with a non-zero code.
+
+## Delegation Rules
+
+- Claude Code, Codex, and Antigravity agents invoke these scripts directly via
+  a shell, guided by `SKILL.md`.
+- The OpenCode adapter (`src/opencode.ts`) registers a tool that spawns the
+  scripts and returns their JSON output.
+- The DeepSeek/Cordis adapter (`src/deepseek.ts`) provides a service that
+  spawns the scripts; `cordis.patch.yml` loads it from the published package.
+
+Prefer `.mjs` when only a JavaScript runtime is guaranteed; use `.py` when
+Python is available or the workflow needs Python-only libraries.

package/templates/v0.1.0/universal-typescript/skills/shared-skill/scripts/main.mjs.tpl

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// {{DISPLAY_NAME}} shared-skill entrypoint (Node/Bun twin of main.py).
+// Reads one JSON payload from stdin and writes one JSON result to stdout.
+// See references/tool-contract.md for the full contract.
+
+const chunks = []
+for await (const chunk of process.stdin) chunks.push(chunk)
+
+let request
+try {
+  request = JSON.parse(Buffer.concat(chunks).toString("utf8"))
+} catch (error) {
+  console.error(`Invalid JSON payload: ${error.message}`)
+  process.exit(1)
+}
+
+if (typeof request !== "object" || request === null || Array.isArray(request)) {
+  console.error("Payload must be a JSON object")
+  process.exit(1)
+}
+
+process.stdout.write(`${JSON.stringify({ ok: true, plugin: "{{NAME}}", echo: request })}\n`)

package/templates/v0.1.0/universal-typescript/skills/shared-skill/scripts/main.py.tpl

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""{{DISPLAY_NAME}} shared-skill entrypoint (Python twin of main.mjs).
+
+Reads one JSON payload from stdin and writes one JSON result to stdout.
+See references/tool-contract.md for the full contract.
+"""
+
+import json
+import sys
+
+
+def main() -> int:
+    try:
+        request = json.load(sys.stdin)
+    except json.JSONDecodeError as error:
+        print(f"Invalid JSON payload: {error}", file=sys.stderr)
+        return 1
+
+    if not isinstance(request, dict):
+        print("Payload must be a JSON object", file=sys.stderr)
+        return 1
+
+    print(json.dumps({"ok": True, "plugin": "{{NAME}}", "echo": request}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/templates/v0.1.0/universal-typescript/src/deepseek.ts.tpl

@@ -1,7 +1,36 @@
+import { spawnSync } from "node:child_process"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
 import type { Context } from "@deepseek-ai/cordis"
 
 export const name = {{NAME_JSON}}
 
-export function apply(_context: Context): void {
-  // Register Cordis services, tools, or lifecycle effects here.
+const scriptsDirectory = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "skills/{{NAME}}/scripts",
+)
+
+export function runSkillScript(script: string, payload: string): unknown {
+  const runtime = script.endsWith(".py") ? "python3" : process.execPath
+  const result = spawnSync(runtime, [join(scriptsDirectory, script)], {
+    input: payload,
+    encoding: "utf8",
+  })
+  if (result.error) {
+    throw new Error(`Could not run ${script} via ${runtime}: ${result.error.message}`)
+  }
+  if (result.status !== 0) {
+    const diagnostic = result.stderr.trim() || `${script} exited with code ${result.status}`
+    throw new Error(diagnostic)
+  }
+  return JSON.parse(result.stdout)
+}
+
+export function apply(context: Context): void {
+  context.provide(name, {
+    run: (payload: string, runtime: "node" | "python" = "node") =>
+      runSkillScript(runtime === "python" ? "main.py" : "main.mjs", payload),
+  })
 }

package/templates/v0.1.0/universal-typescript/src/opencode.ts.tpl

@@ -1,7 +1,67 @@
+import { spawn } from "node:child_process"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { tool } from "@opencode-ai/plugin"
 import type { Plugin } from "@opencode-ai/plugin"
 
+const scriptsDirectory = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "skills/{{NAME}}/scripts",
+)
+
+export function runSkillScript(script: string, payload: string): Promise<string> {
+  return new Promise((resolveResult, rejectResult) => {
+    const runtime = script.endsWith(".py") ? "python3" : process.execPath
+    const child = spawn(runtime, [join(scriptsDirectory, script)], {
+      stdio: ["pipe", "pipe", "pipe"],
+    })
+    let stdout = ""
+    let stderr = ""
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk
+    })
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk
+    })
+    child.on("error", (error) => {
+      rejectResult(new Error(`Could not run ${script} via ${runtime}: ${error.message}`))
+    })
+    child.on("close", (code) => {
+      if (code !== 0) {
+        rejectResult(new Error(stderr.trim() || `${script} exited with code ${code}`))
+      } else {
+        resolveResult(stdout)
+      }
+    })
+    child.stdin.end(payload)
+  })
+}
+
 const plugin = (async () => {
-  return {}
+  return {
+    tool: {
+      "{{NAME}}_run": tool({
+        description:
+          "Run the {{DISPLAY_NAME}} shared-skill workflow. Delegates to skills/{{NAME}}/scripts.",
+        args: {
+          input: tool.schema
+            .string()
+            .describe("JSON object passed on stdin to the skill entrypoint"),
+          runtime: tool.schema
+            .enum(["node", "python"])
+            .optional()
+            .describe("Entrypoint runtime; defaults to node"),
+        },
+        execute: async (args) => {
+          const script = args.runtime === "python" ? "main.py" : "main.mjs"
+          const output = await runSkillScript(script, args.input)
+          return JSON.stringify(JSON.parse(output))
+        },
+      }),
+    },
+  }
 }) satisfies Plugin
 
 export default plugin

package/templates/v0.1.0/universal-typescript/tests/runtimes.test.mjs.tpl

@@ -1,11 +1,22 @@
 import assert from "node:assert/strict"
+import { spawnSync } from "node:child_process"
 import test from "node:test"
 
 import opencodePlugin from "../dist/opencode.js"
 import * as deepseekPlugin from "../dist/deepseek.js"
 
-test("OpenCode entrypoint returns an inert hooks object", async () => {
-  assert.deepEqual(await opencodePlugin({}), {})
+const pythonAvailable = spawnSync("python3", ["--version"], { encoding: "utf8" }).status === 0
+
+test("OpenCode tool delegates to the shared skill script", async () => {
+  const hooks = await opencodePlugin({})
+  const entry = hooks.tool?.["{{NAME}}_run"]
+  assert.equal(typeof entry?.execute, "function")
+  const result = await entry.execute({ input: '{"hello":"world"}' })
+  assert.deepEqual(JSON.parse(result), {
+    ok: true,
+    plugin: "{{NAME}}",
+    echo: { hello: "world" },
+  })
 })
 
 test("DeepSeek entrypoint exposes a Cordis namespace plugin", () => {
@@ -13,3 +24,25 @@ test("DeepSeek entrypoint exposes a Cordis namespace plugin", () => {
   assert.equal(typeof deepseekPlugin.apply, "function")
   assert.equal("default" in deepseekPlugin, false)
 })
+
+test("DeepSeek adapter delegates to the shared skill script", () => {
+  const result = deepseekPlugin.runSkillScript("main.mjs", '{"hello":"world"}')
+  assert.deepEqual(result, {
+    ok: true,
+    plugin: "{{NAME}}",
+    echo: { hello: "world" },
+  })
+})
+
+test(
+  "Python twin honors the same tool contract",
+  { skip: !pythonAvailable },
+  () => {
+    const result = deepseekPlugin.runSkillScript("main.py", '{"hello":"world"}')
+    assert.deepEqual(result, {
+      ok: true,
+      plugin: "{{NAME}}",
+      echo: { hello: "world" },
+    })
+  },
+)