@codemodekit/skills 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# CodeModeKit skills
+
+Install CodeModeKit's two project-level Agent Skills with the open skills CLI:
+
+```sh
+npx skills add stjbrown/codemodekit
+```
+
+The repository contains:
+
+- `build-codemodekit-server` builds and verifies Code Mode MCP servers from Local Tools or MCP sources.
+- `author-codemode-skill` turns a generated companion skill into domain-aware runtime guidance and maintains its Agent Plugin package.
+
+Install either one independently:
+
+```sh
+npx skills add stjbrown/codemodekit --skill build-codemodekit-server
+npx skills add stjbrown/codemodekit --skill author-codemode-skill
+```
+
+For an explicit, non-interactive install of both into Cursor:
+
+```sh
+npx skills add stjbrown/codemodekit \
+  --skill '*' \
+  --agent cursor \
+  --copy \
+  --yes
+```
+
+## npm and programmatic installation
+
+The `@codemodekit/skills` npm package backs `create-codemodekit` and can also copy both skills directly into the current project's portable `.agents/skills` directory:
+
+```sh
+npx @codemodekit/skills
+```
+
+Install one from the npm package with `--skill`:
+
+```sh
+npx @codemodekit/skills --skill build-codemodekit-server
+```
+
+CodeModeKit-generated projects install both automatically. Use the skills CLI for agent-specific destinations, global installation, symlinks, updates, or discovery through [skills.sh](https://skills.sh/).

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CODEMODEKIT_SKILL_NAMES, installCodeModeKitSkills, } from "./index.js";
+async function run(args) {
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(usage());
+        return;
+    }
+    let root;
+    let overwrite = false;
+    const skills = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--overwrite") {
+            overwrite = true;
+            continue;
+        }
+        if (argument === "--skill") {
+            const value = args[index + 1];
+            if (value === undefined || !isSkillName(value)) {
+                throw new TypeError(`--skill must be one of: ${CODEMODEKIT_SKILL_NAMES.join(", ")}`);
+            }
+            skills.push(value);
+            index += 1;
+            continue;
+        }
+        if (argument?.startsWith("-") === true) {
+            throw new TypeError(`Unknown option: ${argument}`);
+        }
+        if (argument !== undefined) {
+            if (root !== undefined)
+                throw new TypeError(`Unexpected argument: ${argument}`);
+            root = argument;
+        }
+    }
+    const result = await installCodeModeKitSkills({
+        root: root ?? process.cwd(),
+        ...(skills.length === 0 ? {} : { skills }),
+        overwrite,
+    });
+    process.stdout.write(`Installed CodeModeKit skills in ${result.skillsRoot}\n` +
+        (skills.length === 0 ? CODEMODEKIT_SKILL_NAMES : skills)
+            .map((skill) => `  ${skill}\n`)
+            .join(""));
+}
+function isSkillName(value) {
+    return CODEMODEKIT_SKILL_NAMES.includes(value);
+}
+function usage() {
+    return `Install CodeModeKit development skills into .agents/skills.
+
+Usage:
+  npx @codemodekit/skills [project-directory]
+  codemodekit-skills [project-directory] [--skill <name>] [--overwrite]
+
+Skills:
+  build-codemodekit-server
+  author-codemode-skill
+`;
+}
+if (process.argv[1] !== undefined &&
+    realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+    run(process.argv.slice(2)).catch((error) => {
+        process.stderr.write(`codemodekit-skills: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export declare const CODEMODEKIT_SKILL_NAMES: readonly ["build-codemodekit-server", "author-codemode-skill"];
+export type CodeModeKitSkillName = (typeof CODEMODEKIT_SKILL_NAMES)[number];
+export interface InstallCodeModeKitSkillsOptions {
+    readonly root: string;
+    readonly skills?: readonly CodeModeKitSkillName[];
+    readonly overwrite?: boolean;
+}
+export interface InstallCodeModeKitSkillsResult {
+    readonly root: string;
+    readonly skillsRoot: string;
+    readonly directories: Readonly<Partial<Record<CodeModeKitSkillName, string>>>;
+}
+/** Install CodeModeKit's development-time skills into the portable project path. */
+export declare function installCodeModeKitSkills(options: InstallCodeModeKitSkillsOptions): Promise<InstallCodeModeKitSkillsResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,uBAAuB,gEAG1B,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CAC/E;AAID,oFAAoF;AACpF,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,8BAA8B,CAAC,CA6CzC"}

package/dist/index.js

@@ -0,0 +1,66 @@
+import { cp, lstat, mkdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+export const CODEMODEKIT_SKILL_NAMES = [
+    "build-codemodekit-server",
+    "author-codemode-skill",
+];
+const BUNDLED_SKILLS_ROOT = fileURLToPath(new URL("../skills", import.meta.url));
+/** Install CodeModeKit's development-time skills into the portable project path. */
+export async function installCodeModeKitSkills(options) {
+    const root = path.resolve(options.root);
+    const skillsRoot = path.join(root, ".agents", "skills");
+    const selected = options.skills ?? CODEMODEKIT_SKILL_NAMES;
+    const unique = [...new Set(selected)];
+    if (unique.length === 0) {
+        throw new TypeError("Select at least one CodeModeKit skill to install");
+    }
+    for (const skillName of unique) {
+        if (!isCodeModeKitSkillName(skillName)) {
+            throw new TypeError(`Unknown CodeModeKit skill: ${String(skillName)}`);
+        }
+        const destination = path.join(skillsRoot, skillName);
+        if ((await pathExists(destination)) && options.overwrite !== true) {
+            throw new Error(`CodeModeKit skill already exists: ${destination}`);
+        }
+    }
+    await mkdir(skillsRoot, { recursive: true });
+    const installed = new Map();
+    for (const skillName of unique) {
+        const destination = path.join(skillsRoot, skillName);
+        const staging = path.join(skillsRoot, `.${skillName}.${String(process.pid)}.${String(Date.now())}.tmp`);
+        await rm(staging, { recursive: true, force: true });
+        await cp(path.join(BUNDLED_SKILLS_ROOT, skillName), staging, {
+            recursive: true,
+        });
+        try {
+            await rm(destination, { recursive: true, force: true });
+            await rename(staging, destination);
+        }
+        catch (error) {
+            await rm(staging, { recursive: true, force: true });
+            throw error;
+        }
+        installed.set(skillName, destination);
+    }
+    const directories = Object.fromEntries(installed);
+    return { root, skillsRoot, directories };
+}
+function isCodeModeKitSkillName(value) {
+    return CODEMODEKIT_SKILL_NAMES.includes(value);
+}
+async function pathExists(file) {
+    try {
+        await lstat(file);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@codemodekit/skills",
+  "version": "0.1.0",
+  "description": "Agent Skills for building CodeModeKit servers and authoring their runtime skills.",
+  "author": "Stephen Brown",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stjbrown/codemodekit.git",
+    "directory": "packages/skills"
+  },
+  "homepage": "https://github.com/stjbrown/codemodekit#readme",
+  "bugs": {
+    "url": "https://github.com/stjbrown/codemodekit/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "codemodekit-skills": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist/*.js", "dist/*.d.ts", "dist/*.map", "skills/**/*"],
+  "keywords": [
+    "code-mode",
+    "mcp",
+    "agent-skill",
+    "agent-skills",
+    "agent-plugin",
+    "skills.sh"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/author-codemode-skill/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: author-codemode-skill
+description: Author, refine, or evaluate the domain-aware runtime Agent Skill inside a CodeModeKit Agent Plugin. Use after a Code Mode MCP server is scaffolded or its catalog changes, when generated skill guidance is too generic, when adding user workflows and exact multi-tool examples, when defining safe write behavior and result expectations, or when updating plugin.json, skill references, catalog sync, build, and release metadata for an Agent Plugins package.
+---
+
+# Author a Code Mode Skill
+
+Turn a mechanically valid CodeModeKit plugin into a useful domain product. The catalog explains what calls exist; infer how people should use them from repository evidence and the user, never from tool names alone.
+
+## 1. Establish current truth
+
+1. Locate `plugin.json`, `mcp.json`, `src/server.mjs`, `package.json`, and every immediate `skills/*/SKILL.md`.
+2. Run `npm run plugin:sync` when the configured sources are available. If it fails, preserve the current generated files and report the connectivity or credential blocker.
+3. Read `references/catalog-metadata.json` and search focused sections of `references/tools.d.ts`. Never edit either file; CodeModeKit owns them.
+4. Inspect project documentation, tests, source configuration, tool descriptions, policy, and existing examples for domain evidence.
+5. Read [references/discovery.md](references/discovery.md) and create a concise authoring brief. Ask the user only for high-impact facts that cannot be recovered locally. Do not invent organization policy, approval boundaries, or intended users.
+
+Current truth is established when every configured source and runtime skill is accounted for, generated catalog status is known, and the brief separates evidence from unanswered consequential questions.
+
+## 2. Design around jobs, not inventory
+
+Choose the few user jobs that justify activating this skill. For each one, identify:
+
+- the user intent and expected answer or artifact;
+- the exact source tools and required sequence;
+- which calls are independent versus dependent;
+- ambiguity that requires clarification;
+- write, destructive, external-communication, or privacy risk;
+- the smallest useful final value; and
+- common failure and recovery behavior.
+
+Read [references/runtime-skill-design.md](references/runtime-skill-design.md) before editing. A good runtime skill teaches decisions and workflows that cannot be derived from `tools.d.ts`; it does not restate the whole catalog.
+
+Design is complete when each selected job maps to exact current tools, a result contract, its ambiguity and safety decisions, and a checkable completion condition.
+
+## 3. Author the runtime package
+
+Edit the companion runtime skill under `skills/<name>/`:
+
+- Rewrite `SKILL.md` with a specific trigger description and compact workflow routing.
+- Preserve the stable Code Mode execution rules or link to `references/runtime.md` and `references/result-contract.md`.
+- Replace generic `references/examples.md` with real, type-correct compositions for the selected jobs.
+- Add focused references such as `workflows.md`, `domain-rules.md`, or `write-safety.md` only when each has a clear loading condition from `SKILL.md`.
+- Delete obsolete agent-authored references. Do not add README, changelog, or process-history files inside the skill.
+- Keep references one level below `SKILL.md` and use relative links.
+
+Update the root Agent Plugin when the semantic product changed. Read [references/plugin-maintenance.md](references/plugin-maintenance.md) before editing `plugin.json`, `mcp.json`, or the plugin version.
+
+Authorship is complete when every line in `SKILL.md` changes runtime behavior, every context pointer says when to load its target, and each meaning has one source of truth.
+
+## 4. Evaluate behavior
+
+Use [references/evaluation.md](references/evaluation.md) to create realistic should-trigger, should-not-trigger, read, composition, ambiguity, failure, and write-safety cases. Test the skill through an agent with the built plugin when available; do not judge it only by reading Markdown.
+
+Run the project checks, then:
+
+```sh
+npm run plugin:sync
+npm run plugin:build
+```
+
+Re-read the built `dist/plugin/skills/<name>/SKILL.md` and references. Confirm the build contains the authored files and current generated catalog but no secrets or development-only authoring skills.
+
+Evaluation is complete when every minimum case has an observed result and each failed assertion is either fixed or recorded as a specific remaining limitation.
+
+## Quality gate
+
+Do not report the runtime skill as polished unless:
+
+- its description names concrete triggering requests and avoids claiming unrelated tasks;
+- every documented tool call exists in the current `tools.d.ts` and matches its input shape;
+- examples return bounded user-relevant values rather than raw provider payloads;
+- write workflows state when to clarify, preview, confirm, or stop based on the user's actual policy;
+- live `search_tools` remains the recovery path for stale or dynamic catalogs;
+- plugin and MCP manifests still target the same Agent Plugins version; and
+- at least one realistic evaluation demonstrates a multi-tool Code Mode advantage.

package/skills/author-codemode-skill/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Author Code Mode Skill"
+  short_description: "Author a domain-aware Code Mode skill"
+  default_prompt: "Use $author-codemode-skill to turn this CodeModeKit plugin into a polished domain-aware agent skill."

package/skills/author-codemode-skill/references/discovery.md

@@ -0,0 +1,36 @@
+# Domain discovery
+
+Build an authoring brief before changing the runtime skill.
+
+## Recover locally first
+
+Inspect:
+
+- product README and examples;
+- `src/server.mjs` source names, Local Tool implementations, annotations, and policy;
+- generated `tools.d.ts` and catalog metadata;
+- tests and evaluation prompts;
+- existing skill instructions and references;
+- plugin name, description, keywords, version, and license; and
+- domain documentation already committed to the project.
+
+## Authoring brief
+
+Record concise answers for:
+
+1. Who invokes this skill?
+2. What jobs should reliably trigger it?
+3. What nearby jobs should not trigger it?
+4. Which two or three workflows provide the most value?
+5. What must the agent clarify before acting?
+6. Which operations read, write, delete, communicate externally, spend money, or affect access?
+7. What authorization or confirmation policy did the user actually specify?
+8. What result shape is useful to the user?
+9. What domain vocabulary or identifiers are easy to confuse?
+10. Which upstream failures have a meaningful recovery path?
+
+## Ask only consequential questions
+
+Ask one to three short questions when missing answers would materially change the skill. Prioritize intended users and jobs, write/approval boundaries, and required output. Do not block on naming or prose preferences that can be revised safely.
+
+Never infer a permissive write policy from tool availability. Never describe an organization-specific workflow as required unless repository evidence or the user establishes it.

package/skills/author-codemode-skill/references/evaluation.md

@@ -0,0 +1,34 @@
+# Skill evaluation
+
+Test behavior, not prose coverage. Keep a small table or JSON fixture outside the runtime skill directory so evaluation artifacts are not shipped as instructions unless intentionally useful.
+
+## Minimum cases
+
+Create at least:
+
+- two requests that should activate the skill;
+- one nearby request that should not activate it;
+- one simple read workflow;
+- one dependent multi-tool workflow;
+- one ambiguous request that should trigger a focused question;
+- one upstream failure or missing-result case; and
+- one write or destructive case when such tools exist.
+
+## Assertions
+
+Grade whether the agent:
+
+- activates the intended skill and avoids unrelated activation;
+- uses `run_typescript` rather than trying to call hidden upstream tools directly;
+- chooses tools and arguments present in the current declarations;
+- composes related work into one execution;
+- asks only consequential questions;
+- respects tool policy and documented write boundaries;
+- handles missing structured content or tool failure safely; and
+- returns a bounded answer shaped for the request.
+
+## Forward test
+
+When an agent runner is available, run representative cases with the authored skill and with the generated baseline or prior version. Use fresh contexts and compare tool traces, outputs, retries, and user-facing quality. Do not reveal the expected implementation or suspected defect to the test agent.
+
+Repeat flaky trigger cases several times before changing the description. A description succeeds when relevant prompts activate reliably without capturing adjacent unrelated work.

package/skills/author-codemode-skill/references/plugin-maintenance.md

@@ -0,0 +1,26 @@
+# Agent Plugin maintenance
+
+Target the current Agent Plugins schema already declared by the project. For Agent Plugins 1.0:
+
+- `plugin.json` is required at the plugin root.
+- Skills are immediate child directories of `skills/`, each with a conforming `SKILL.md` whose name matches its directory.
+- `mcp.json` is the only portable MCP configuration location.
+- `plugin.json` and `mcp.json` must target the same specification version.
+- Package-owned paths must stay inside the plugin root.
+- stdio `command` is one bare executable or plugin-relative token; arguments remain separate.
+- `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` are supported only in the fields defined by the specification.
+- Portable `env` and HTTP headers are visible package data, not secret storage.
+
+## What to edit
+
+Update `plugin.json` description and keywords when the plugin's user-facing purpose becomes more specific. Preserve its name unless the user intends an identity change. Use Semantic Versioning: workflow additions are normally minor; corrections are patch; removing or incompatibly changing a promised workflow is major.
+
+Edit `mcp.json` only when the server connection itself changes. Runtime-skill improvements do not require an MCP configuration change.
+
+Do not add portable manifest fields outside the closed schema. Client-specific behavior belongs under a reverse-domain extension namespace and should be added only for a client the user explicitly targets.
+
+## Build boundary
+
+`npm run plugin:build` recreates `dist/plugin`. Never hand-edit the artifact. Verify it contains root manifests, the bundled server, QuickJS WASM, and runtime skills. It must exclude `.env`, source files, `node_modules`, and `.agents/skills` development guidance.
+
+Cursor uses a concrete installed copy rather than the portable `${PLUGIN_ROOT}` configuration. Re-run `npm run plugin:install:cursor` and reload Cursor after rebuilding for local testing.

package/skills/author-codemode-skill/references/runtime-skill-design.md

@@ -0,0 +1,73 @@
+# Runtime skill design
+
+## Optimize for predictability
+
+A runtime skill should make the agent follow a predictable process while allowing the answer to vary with the request and tool results.
+
+- Front-load the description with the domain action users will actually request.
+- Give each genuine invocation branch one trigger. Collapse synonyms that merely rename the same branch.
+- Keep steps required on every run in `SKILL.md`. End each step with a condition the agent can verify before moving on.
+- Move branch-specific rules and examples behind context pointers that state exactly when to read them.
+- Co-locate a concept's rule, exception, and caveat instead of scattering them.
+- Keep one source of truth for each behavior. Generated types define call shapes; domain references define domain rules; do not duplicate either in the body.
+- Prune lines that merely tell a capable agent to be helpful, careful, or thorough. Remove stale instructions rather than layering corrections over them.
+
+## Separate generated and authored truth
+
+CodeModeKit owns:
+
+- `references/tools.d.ts`;
+- `references/catalog-metadata.json`; and
+- `dist/plugin`.
+
+The skill author owns:
+
+- the runtime `SKILL.md`;
+- domain workflows and rules;
+- worked examples; and
+- routing to focused references.
+
+`npm run plugin:sync` updates generated catalog files only. `npm run plugin:build` packages both generated and authored files.
+
+## Description
+
+Write the description for activation. Include what the skill enables and concrete request classes that should trigger it. Use domain language users will say. Avoid generic phrases such as “use upstream tools,” which collide with other skills and fail to disclose actual value.
+
+## Body
+
+Keep `SKILL.md` procedural and compact:
+
+1. state the primary interface (`run_typescript`);
+2. route the agent among the supported jobs;
+3. specify critical clarification and safety decisions;
+4. link to exact references with a condition for reading each; and
+5. define the completion standard.
+
+Do not paste the entire catalog into the body. Search `tools.d.ts` for exact names and shapes. Preserve `search_tools` as the live recovery path when declarations are pending, stale, incomplete, or too large to search efficiently.
+
+## Code Mode examples
+
+Every example must compile as the body of an async function:
+
+```ts
+const first = await tools.source.firstTool({ query: "value" });
+const second = await tools.source.secondTool({
+  id: first.structuredContent.id,
+});
+return {
+  name: first.structuredContent.name,
+  status: second.structuredContent.status,
+};
+```
+
+- Use exact names and schemas from `tools.d.ts`.
+- Prefer `structuredContent`; inspect text content defensively only when the provider lacks structured output.
+- Use `Promise.all` only for independent calls.
+- Pass the smallest necessary data between calls.
+- Filter, join, aggregate, and reshape in the sandbox.
+- Return only what the user needs.
+- Catch a tool error only when the workflow can recover or add a useful bounded outcome.
+
+## Write workflows
+
+Document writes separately from reads. Base preview, clarification, confirmation, and execution rules on the user's policy and host behavior. The runtime skill cannot bypass CodeModeKit tool policy; explain a denial as a policy result rather than suggesting workarounds.

package/skills/build-codemodekit-server/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: build-codemodekit-server
+description: Build, retrofit, debug, or verify CodeModeKit Code Mode MCP servers from application-owned Local Tools, stdio MCP commands, or remote MCP URLs. Use when scaffolding a CodeModeKit project, defining local tools and schemas, composing multiple sources, setting tool policy and limits, packaging an Agent Plugin, or troubleshooting run_typescript, search_tools, plugin sync, build, or Cursor installation.
+---
+
+# Build a CodeModeKit Server
+
+Build a walking skeleton for the user's actual source, then verify it through the downstream MCP surface. Keep model-authored code in CodeModeKit's sandbox and host integrations behind tool providers.
+
+## Build workflow
+
+1. Inspect the repository, package manager, local instructions, existing MCP configuration, and relevant application functions. Do not overwrite unrelated work.
+2. Choose the source boundary:
+   - Use Local Tools for functions or APIs the application owns.
+   - Use `mcp.stdio` for a shell-free executable and argument array.
+   - Use `mcp.http` for a Streamable HTTP MCP endpoint.
+   - Compose sources when one authored program needs more than one namespace.
+3. For a new project, prefer the generator. Read [references/generator.md](references/generator.md) for commands and generated-file ownership.
+4. For a retrofit or custom server, read [references/server-api.md](references/server-api.md), preserve the batteries-included facade, and expose compiler or sandbox configuration only when the user needs an expert override.
+5. Define an explicit tool policy. Read [references/policy-and-security.md](references/policy-and-security.md) before enabling writes, handling credentials, or binding Streamable HTTP beyond loopback.
+6. Keep the initial implementation compact. A single `src/server.mjs` is the default; split it only when domain code already has a natural module boundary.
+7. If the project includes an Agent Plugin, run catalog sync and build, but do not pretend the generated runtime skill understands the domain. Invoke `$author-codemode-skill` after the server works.
+8. Verify the downstream behavior using [references/verification.md](references/verification.md). Exercise `run_typescript`, not merely imports or direct provider functions.
+
+The walking skeleton is complete when one realistic downstream execution crosses compilation, QuickJS, policy, the bridge, and the chosen provider and returns the expected bounded value.
+
+## Local Tool quality bar
+
+- Give tools stable action-oriented names and descriptions that distinguish them from siblings.
+- Use bounded input and output schemas. Prefer Standard JSON Schema-compatible schemas when the project already uses one; plain JSON Schema requires no extra dependency.
+- Return plain JSON values and declare an output schema when the result has a stable shape.
+- Use the execution context's `signal` for fetches and other cancellable work.
+- Throw `ToolError` only when its message is safe for model-authored code. Keep credentials, raw upstream responses, stack traces, and internal paths out of it.
+- Keep authentication and network access in the trusted host function. Never add ambient `fetch`, filesystem, process, or package access to the sandbox to make a tool work.
+- Mark read-only, destructive, idempotent, and open-world annotations accurately. Treat annotations as policy hints, not authorization.
+
+## Completion criteria
+
+Do not call the server ready until:
+
+- dependencies install and typecheck or syntax checks pass;
+- the server advertises `run_typescript` and, unless intentionally disabled, `search_tools`;
+- at least one realistic TypeScript execution calls the configured source and returns a bounded value;
+- policy denials and a representative invalid input fail safely;
+- plugin catalog sync is current or its exact connectivity blocker is documented;
+- `dist/plugin` builds when an Agent Plugin is requested; and
+- the domain-aware runtime skill has either been authored or is explicitly reported as a generated baseline requiring `$author-codemode-skill`.

package/skills/build-codemodekit-server/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Build CodeModeKit Server"
+  short_description: "Build and verify Code Mode MCP servers"
+  default_prompt: "Use $build-codemodekit-server to build a CodeModeKit MCP server for this project."

package/skills/build-codemodekit-server/references/generator.md

@@ -0,0 +1,55 @@
+# Generator and lifecycle
+
+## New weather Local Tools project
+
+```sh
+npm create codemodekit@latest
+```
+
+The noninteractive equivalent is:
+
+```sh
+npm create codemodekit@latest weather-code-mode -- --example weather
+```
+
+## Wrap a stdio MCP server
+
+```sh
+npm create codemodekit@latest my-code-mode -- \
+  --mcp-name upstream \
+  --mcp-command 'uvx upstream-mcp' \
+  --agent-plugin
+```
+
+The command is parsed into one executable and an argument array. Do not pass pipes, redirection, command substitution, or leading environment assignments.
+
+## Wrap a remote MCP server
+
+```sh
+npm create codemodekit@latest my-code-mode -- \
+  --mcp-name upstream \
+  --mcp-url https://example.com/mcp \
+  --agent-plugin
+```
+
+## Useful options
+
+- `--policy deny-all`: scaffold closed while a narrower policy is implemented.
+- `--no-install`: write files without installing dependencies.
+- `--no-sync`: defer live catalog capture when credentials or connectivity are not ready.
+- `--no-agent-plugin`: omit portable plugin packaging.
+- `--plugin-name`, `--skill-name`, `--plugin-description`, `--plugin-license`: override portable metadata.
+- `--no-authoring-skill`: omit both project development skills.
+
+## Generated project lifecycle
+
+```sh
+npm start
+npm run plugin:sync
+npm run plugin:build
+npm run plugin:install:cursor
+npm run plugin:status:cursor
+npm run plugin:uninstall:cursor
+```
+
+Catalog sync owns `references/tools.d.ts` and `references/catalog-metadata.json`. Plugin build owns `dist/plugin`. The developer or `$author-codemode-skill` owns the runtime `SKILL.md`, domain workflows, and examples.

package/skills/build-codemodekit-server/references/policy-and-security.md

@@ -0,0 +1,28 @@
+# Policy and security
+
+## Tool authorization
+
+CodeModeKit requires a host-side tool policy. `allowAllToolCalls()` is suitable for a runnable starter only when every visible tool is authorized for the model's users. `denyAllToolCalls()` starts closed. A custom policy receives validated source, tool, input, annotations, execution IDs, and cancellation signal.
+
+For write-capable catalogs:
+
+- prefer an upstream read-only mode or allowlist when available;
+- authorize by source and exact tool, not by description text;
+- inspect arguments for tenant, repository, channel, or resource boundaries when needed;
+- fail closed when an approval or policy dependency is unavailable; and
+- never infer authorization from read-only or destructive annotations.
+
+## Secret handling
+
+- Keep secrets in the host environment, an ignored `.env`, or the upstream provider's credential mechanism.
+- Never write credentials into `plugin.json`, `mcp.json`, runtime skills, generated references, tool errors, or portable artifacts.
+- Agent Plugins 1.0 has no portable credential-reference or OAuth configuration field.
+- Treat configured plugin `env` and HTTP headers as visible package data.
+
+## Sandbox boundary
+
+Model-authored TypeScript receives `tools`, bounded console support, and safe JavaScript globals. Do not expose Node modules, `process`, filesystem access, ambient network access, dynamic imports, `eval`, or `Function` to solve an integration problem. Put the capability in a provider.
+
+## HTTP exposure
+
+`serveCodeModeHttp` binds to loopback by default. A non-loopback unauthenticated bind requires an explicit acknowledgement but does not create authentication. Put an authenticated gateway in front of it or integrate authentication at the owning host.

package/skills/build-codemodekit-server/references/server-api.md

@@ -0,0 +1,77 @@
+# Server API
+
+## Application-owned Local Tools
+
+```ts
+import {
+  allowAllToolCalls,
+  defineTool,
+  local,
+  serveCodeModeStdio,
+  ToolError,
+} from "codemodekit";
+
+const lookup = defineTool({
+  description: "Look up one record by identifier",
+  inputSchema: {
+    type: "object",
+    properties: { id: { type: "string", minLength: 1 } },
+    required: ["id"],
+    additionalProperties: false,
+  },
+  outputSchema: {
+    type: "object",
+    properties: { id: { type: "string" }, status: { type: "string" } },
+    required: ["id", "status"],
+    additionalProperties: false,
+  },
+  execute: async ({ id }, { signal }) => {
+    const response = await fetch(`https://example.com/records/${id}`, { signal });
+    if (!response.ok) throw new ToolError(`Record lookup failed with HTTP ${response.status}`);
+    return await response.json();
+  },
+});
+
+await serveCodeModeStdio({
+  name: "records-code-mode",
+  version: "0.1.0",
+  toolPolicy: allowAllToolCalls(),
+  sources: [local({ name: "records", tools: { lookup } })],
+});
+```
+
+`defineTool` accepts plain JSON Schema or Standard JSON Schema-compatible schemas. Local executors run in the trusted host; the model's TypeScript still runs in QuickJS.
+
+## MCP source
+
+```ts
+import { allowAllToolCalls, mcp, serveCodeModeStdio } from "codemodekit";
+
+await serveCodeModeStdio({
+  name: "github-code-mode",
+  version: "0.1.0",
+  toolPolicy: allowAllToolCalls(),
+  sources: [
+    mcp.stdio({
+      name: "github",
+      command: "docker",
+      args: ["run", "-i", "--rm", "ghcr.io/github/github-mcp-server"],
+    }),
+  ],
+});
+```
+
+Use `mcp.http({ name, url })` for Streamable HTTP. Source names become the first segment below `tools`; preserve them exactly and use bracket notation for names that are not TypeScript identifiers.
+
+## Composition
+
+Every source is a provider in one normalized catalog:
+
+```ts
+sources: [
+  local({ name: "application", tools: { lookup } }),
+  mcp.http({ name: "tickets", url: "https://example.com/mcp" }),
+]
+```
+
+The low-level `CodeMode`, compiler, sandbox, and provider classes are expert APIs. Stay on the facade unless a custom host or sandbox is an explicit requirement.

package/skills/build-codemodekit-server/references/verification.md

@@ -0,0 +1,38 @@
+# Verification
+
+Verify from the downstream MCP boundary because direct provider calls bypass compilation, sandboxing, policy, bridge limits, and result projection.
+
+## Minimum smoke
+
+1. Start the generated server over stdio.
+2. List tools and assert `run_typescript` is present. Expect `search_tools` unless disabled intentionally.
+3. Call `search_tools` with a narrow capability query and inspect its generated TypeScript call shape.
+4. Call `run_typescript` with one realistic workflow:
+
+   ```ts
+   const result = await tools.source.tool({ value: "test" });
+   return result.structuredContent;
+   ```
+
+5. Compose two dependent calls when the source supports it; pass only the required fields from the first result into the second.
+6. Send one schema-invalid input and assert the provider is not invoked.
+7. Exercise one denied call when a custom or deny-all policy is used.
+8. Confirm errors contain bounded safe diagnostics rather than credentials, stack traces, or raw upstream payloads.
+
+## Agent Plugin
+
+Run:
+
+```sh
+npm run plugin:sync
+npm run plugin:build
+```
+
+Then verify:
+
+- `dist/plugin/plugin.json`, `mcp.json`, `server.mjs`, QuickJS WASM, and runtime skill exist;
+- `dist/plugin` contains no `.env`, source tree, or `node_modules`;
+- the bundled server starts from outside the project directory; and
+- a downstream MCP client can execute the same realistic `run_typescript` call through the artifact.
+
+Use `$author-codemode-skill` after this mechanical verification to author and evaluate the user-facing runtime guidance.