@codemodekit/skills 0.2.1 → 0.3.0

package/README.md

@@ -8,8 +8,8 @@ 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.
+- `build-codemodekit-server` builds and verifies Code Mode MCP servers from Local Tools or MCP sources, including opt-in packaged-skill delivery through the experimental MCP Skills Extension.
+- `author-codemode-skill` turns a generated companion skill into domain-aware runtime guidance, maintains its Agent Plugin package, and enforces snapshot and importer limits when experimental delivery is enabled.
 
 Install either one independently:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemodekit/skills",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Agent Skills for building CodeModeKit servers and authoring their runtime skills.",
   "author": "Stephen Brown",
   "license": "Apache-2.0",

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Author, refine, or evaluate the domain-aware runtime Agent Skill inside a CodeModeKit Agent Plugin. Use after scaffolding or catalog changes, when guidance is generic, when adding workflows, examples, write safety, and result contracts, when maintaining plugin metadata, or when preparing the skill for experimental MCP delivery and OpenAI Scan Tools.
 ---
 
 # Author a Code Mode Skill
@@ -46,6 +46,8 @@ Edit the companion runtime skill under `skills/<name>/`:
 
 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.
 
+When `src/server.mjs` registers the experimental Skills Extension or the project was generated with `--experimental-mcp-skills`, read [references/experimental-delivery.md](references/experimental-delivery.md) before finalizing the skill package.
+
 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
@@ -73,4 +75,5 @@ Do not report the runtime skill as polished unless:
 - 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
+- experimental delivery, when enabled, stays within its file and byte limits and has a documented restart and re-scan result; and
 - at least one realistic evaluation demonstrates a multi-tool Code Mode advantage.

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Author Code Mode Skill"
-  short_description: "Author a domain-aware Code Mode skill"
+  short_description: "Author and package 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/experimental-delivery.md

@@ -0,0 +1,31 @@
+# Experimental skill delivery
+
+Read this only when the runtime skill is exposed through the experimental MCP Skills Extension or imported with OpenAI Scan Tools.
+
+## Preserve one canonical package
+
+Author only `skills/<name>/SKILL.md` and its focused supporting files. The MCP server snapshots those exact files and the Agent Plugin build copies them into `dist/plugin`; do not maintain transport-specific variants. Keep skill names unique and stable because clients address the primary document as `skill://<name>/SKILL.md` and verify supporting resources by digest.
+
+The extension snapshot is immutable for the life of the server process. After any authored or generated skill-file change:
+
+1. run `npm run plugin:sync` when the tool catalog changed;
+2. run `npm run plugin:build`;
+3. inspect the built skill rather than the source alone;
+4. restart the stdio or HTTP server and verify list, get, and every resource read; and
+5. re-run OpenAI Scan Tools when that importer is a target.
+
+Completion requires the client-visible bytes and digests to match the newly built files. A successful build without a server restart or importer re-scan is still stale delivery.
+
+## Stay inside importer bounds
+
+OpenAI's current supported subset accepts no more than five uniquely named skills across ten list pages, 100 files per skill, 256 KiB for `SKILL.md`, 1 MiB for each supporting file, 5 MiB total per skill, and 8 MiB across the generated scan archive.
+
+Keep the package comfortably below the ceilings:
+
+- prune duplicated or stale prose before splitting it into more files;
+- keep generated catalog shards bounded and indexed from `catalog-metadata.json`;
+- link only files the runtime agent needs and ensure every link resolves;
+- exclude secrets, `.env`, private source, development skills, and process history; and
+- fail the release check on an oversized or unreadable resource instead of dropping it silently.
+
+OpenAI import is a submission-time snapshot, not a live subscription. Record the re-scan result alongside the release verification so users are not told that edited guidance is available before it has actually been imported.

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

@@ -1,6 +1,6 @@
 ---
 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.
+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 sources, setting policy and limits, packaging an Agent Plugin, serving its skill through the experimental MCP Skills Extension, or troubleshooting tools, transports, sync, build, or installation.
 ---
 
 # Build a CodeModeKit Server
@@ -19,7 +19,7 @@ Build a walking skeleton for the user's actual source, then verify it through th
 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.
+7. If the project includes an Agent Plugin, run catalog sync and build, but do not pretend the generated runtime skill understands the domain. When an MCP client must discover the packaged skill, read [references/experimental-skills.md](references/experimental-skills.md) and verify that extension separately. 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.
@@ -44,4 +44,5 @@ Do not call the server ready until:
 - 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
+- when experimental skill delivery is requested, the built artifact passes capability, list, get, resource, digest, size, and intended-transport checks; 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

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

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

@@ -0,0 +1,43 @@
+# Experimental MCP skill delivery
+
+Use this branch only when an MCP client must discover the Agent Plugin's runtime skill through the server. The filesystem under `skills/` remains canonical; do not generate a second copy for MCP.
+
+## Generate the integration
+
+For a new project, opt in explicitly:
+
+```sh
+npm create codemodekit@latest my-code-mode -- \
+  --mcp-name upstream \
+  --mcp-command 'uvx upstream-mcp' \
+  --agent-plugin \
+  --experimental-mcp-skills
+```
+
+The generated entrypoint snapshots `skills/` once at process startup with the exact pinned `@olaservo/ext-skills` dependency. It registers the `io.modelcontextprotocol/skills` capability under `capabilities.extensions`, the `skills/list` and `skills/get` methods, and digest-manifested files through `resources/read`. Keep this surface protocol-native; do not add skills to the Code Mode tool catalog.
+
+For a retrofit, use `CodeModeMcpOptions.configureServer` to call `registerSkillResources` for every fresh `McpServer`. Discover the complete directory before serving, register the same immutable snapshot on each server instance, and keep the package version pinned while the extension is experimental. Prefer the generator's implementation as the reference rather than recreating method handlers.
+
+## Serve the same snapshot
+
+`npm start` serves stdio for the portable Agent Plugin. `npm run start:http` serves the identical application over Streamable HTTP, including the skill extension. Restart either process after changing any file under `skills/`; the running process intentionally does not watch or partially refresh its snapshot.
+
+For remote clients, deploy the HTTP mode behind an authenticated TLS-terminating ingress. The generated non-loopback acknowledgement enables binding only; it is not authentication. Request/response skill discovery does not require sticky sessions, but every replica must run the same built artifact so names, bytes, and digests agree.
+
+## Verify from MCP
+
+Do not stop at filesystem or direct library checks. Connect to the built `server.mjs` over every intended downstream transport and confirm:
+
+1. Initialize advertises `capabilities.extensions["io.modelcontextprotocol/skills"]`, not a legacy `experimental` field.
+2. Paginated `skills/list` returns every expected unique skill.
+3. `skills/get` returns the same entry advertised by the list.
+4. Every declared resource is readable and each `resources/read` response contains exactly one item.
+5. Lowercase SHA-256 digests match the exact returned bytes.
+6. The server still advertises `run_typescript` and `search_tools`, and one bounded Code Mode execution succeeds.
+7. The self-contained artifact works from outside the project directory without `node_modules`.
+
+## OpenAI import boundary
+
+[OpenAI Scan Tools](https://developers.openai.com/plugins/build/mcp-server#import-skills-from-the-mcp-server) imports a submission-time snapshot; it does not keep reading the live server. Its current supported subset allows at most five uniquely named skills across ten list pages, 100 files per skill, 256 KiB for `SKILL.md`, 1 MiB per supporting file, 5 MiB total per skill, and an 8 MiB aggregate scan archive. Re-run Scan Tools after any skill change.
+
+Treat those limits as build gates when OpenAI is a target. Report a limit violation instead of silently omitting a file, renaming a skill, or serving bytes whose digest no longer matches the manifest.

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

@@ -54,12 +54,14 @@ npm create codemodekit@latest work-code-mode -- \
 - `--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.
+- `--experimental-mcp-skills`: with `--agent-plugin`, snapshot and serve the generated runtime skill through experimental SEP-2640 methods and MCP resources.
 - `--no-authoring-skill`: omit both project development skills.
 
 ## Generated project lifecycle
 
 ```sh
 npm start
+npm run start:http
 npm run verify
 npm run plugin:sync
 npm run plugin:build
@@ -68,6 +70,10 @@ npm run plugin:status:cursor
 npm run plugin:uninstall:cursor
 ```
 
+`npm start` uses stdio for local MCP clients and portable Agent Plugins. `npm run start:http` serves the same application over Streamable HTTP, including configured protocol-native extensions such as packaged skills, with a readiness endpoint at `/healthz`. It reads `CODEMODEKIT_HTTP_HOST`, `CODEMODEKIT_HTTP_PORT` (or `PORT`), `CODEMODEKIT_HTTP_PATH`, and `CODEMODEKIT_HTTP_HEALTH_PATH`. A non-loopback bind also requires `CODEMODEKIT_ALLOW_UNAUTHENTICATED_REMOTE_ACCESS=true`; put an authenticated TLS-terminating ingress or gateway in front of it.
+
 `npm run verify` checks the downstream Code Mode surface and sandbox without invoking provider tools. For one semantic live-provider assertion, set `CODEMODEKIT_VERIFY_CODE_FILE` to bounded TypeScript that returns `{ verified: true }`.
 
 Catalog sync owns `references/tools.d.ts`, every generated `references/tools.*.d.ts` shard, and `references/catalog-metadata.json`. It stages the complete file set before replacing the prior snapshot. Plugin build owns `dist/plugin`. The developer or `$author-codemode-skill` owns the runtime `SKILL.md`, domain workflows, and examples.
+
+When `--experimental-mcp-skills` is selected, follow [experimental skill delivery](experimental-skills.md) after the ordinary Code Mode and plugin checks. The extension is a separate protocol-native surface and is not proven by `npm run verify` alone.

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

@@ -75,3 +75,7 @@ sources: [
 ```
 
 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.
+
+## Protocol-native extensions
+
+Use `configureServer(server, context)` to register resources or extension methods on each fresh downstream `McpServer`. They remain outside the normalized `tools` catalog and are unavailable to sandbox-authored TypeScript unless separately exposed through a trusted provider. For packaged Agent Skills, prefer the generator's `--agent-plugin --experimental-mcp-skills` integration and follow [experimental skill delivery](experimental-skills.md); do not hand-roll draft protocol handlers.

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

@@ -47,3 +47,5 @@ Then verify:
 - 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.
+
+When experimental MCP skill delivery is enabled, continue with the capability, pagination, get, resource, digest, size, stdio, and HTTP checks in [experimental skill delivery](experimental-skills.md). Code Mode tool success does not verify that separate surface.