@frontmcp/skills 1.2.1 → 1.4.0

package/catalog/frontmcp-deployment/references/deploy-manifest-yaml.md

@@ -0,0 +1,308 @@
+---
+name: deploy-manifest-yaml
+description: The frontmcp.deploy.yaml v1 schema — declarative manifest the GitHub Action consumes on every push to build, sign, and hot-reload the Cloudflare Worker
+---
+
+# `frontmcp.deploy.yaml` — Schema Reference
+
+This is the declarative manifest the GitHub Action ingests on every push. It is the source of truth for what your Cloudflare Worker serves. The schema is strict — unknown keys fail validation.
+
+For the runtime that consumes the bundle, see `deploy-to-cloudflare-skills-only.md` in this same folder.
+For the live docs version, see https://docs.agentfront.dev/frontmcp/deployment/deploy-manifest.
+
+## Minimum Manifest
+
+```yaml
+$schema: https://schemas.agentfront.dev/frontmcp-deploy/v1.json
+version: 1
+name: acme-mcp
+
+runtime:
+  target: cloudflare-worker
+  compatibilityDate: '2026-05-01'
+
+server:
+  info: { name: acme-mcp, version: 1.0.0 }
+
+specs: ./openapi/
+skills: { source: ./skills/ }
+
+bindings:
+  durableObjects:
+    - { binding: SESSIONS, className: SessionDO }
+  kvNamespaces:
+    - { binding: REPLAY_NONCE, id: '${env:KV_REPLAY_NONCE_ID}' }
+
+signing:
+  algorithm: ed25519
+  trustRoots:
+    - { kid: prod-2026-05, publicKeySecret: TRUSTED_PUBKEY_PROD }
+  replay: { windowSeconds: 300, nonceKv: REPLAY_NONCE }
+
+auth: { provider: none }
+
+secrets:
+  - { name: TRUSTED_PUBKEY_PROD, required: true }
+```
+
+## Top-Level Keys
+
+| Field            | Required | Notes                                                            |
+| ---------------- | -------- | ---------------------------------------------------------------- |
+| `$schema`        | optional | URL pointer for editor autocomplete                              |
+| `version`        | yes      | Literal `1` only in v1.3                                         |
+| `name`           | yes      | Identifier: `[A-Za-z][A-Za-z0-9_-]*`                             |
+| `runtime`        | yes      | `target` + `compatibilityDate` + optional `compatibilityFlags[]` |
+| `server`         | yes      | `info` + optional `instructions` (≤ 16 KB)                       |
+| `specs`          | yes      | Directory string OR `{ id, spec, baseUrl?, bindingName? }[]`     |
+| `skills`         | optional | Defaults to `{ source: './skills/' }`                            |
+| `tags`           | optional | `[{ name, description? }]` OpenAPI-shaped                        |
+| `classification` | optional | Override rules over the auto-classifier                          |
+| `bindings`       | yes      | CF DO / D1 / KV / R2 / vars (camelCase)                          |
+| `signing`        | yes      | Algorithm + trust roots + replay-guard                           |
+| `auth`           | yes      | `provider: none \| frontegg \| oauth \| apiKey`                  |
+| `secrets`        | optional | Names-only; cross-validator enforces references                  |
+| `environments`   | optional | Per-env overlay (deep-merge; bindings replace)                   |
+
+## `runtime`
+
+```yaml
+runtime:
+  target: cloudflare-worker
+  compatibilityDate: '2026-05-01' # ISO-8601 YYYY-MM-DD
+  compatibilityFlags: [nodejs_compat] # optional
+```
+
+## `server`
+
+```yaml
+server:
+  info:
+    name: acme-mcp
+    version: 1.0.0
+    title: ACME MCP # optional
+  instructions: | # optional, max 16 KB
+    Capabilities are organized as SKILLS...
+```
+
+## `specs`
+
+```yaml
+specs: ./openapi/ # directory; specId = filename stem
+```
+
+```yaml
+specs:
+  - ./openapi/acme.yaml
+  - id: billing
+    spec: ./openapi/billing.yaml
+    baseUrl: https://billing.acme.com
+    bindingName: billing # optional override for AgentScript namespace
+```
+
+## `skills`
+
+```yaml
+skills:
+  source: ./skills/
+  alwaysLoad: # forced-load skill ids (kebab-case)
+    - auth-helpers
+    - observability-helpers
+  tags:
+    include: [public, billing]
+    exclude: [admin]
+```
+
+A skill can also self-opt-in via its SKILL.md frontmatter:
+
+```yaml
+---
+name: auth-helpers
+description: Helpers every agent needs.
+alwaysLoad: true
+hideFromDiscovery: true # load without showing in search
+---
+```
+
+## `tags`
+
+```yaml
+tags:
+  - { name: public, description: Always exposed }
+  - { name: billing, description: Billing flows }
+  - { name: admin, description: Admin only }
+```
+
+## `classification` Overrides
+
+```yaml
+classification:
+  rules:
+    - { match: 'POST **/reset-password', emits: parent }
+    - { match: 'GET /metrics', expose: tool }
+    - { match: 'DELETE /users/{id}', emits: none }
+```
+
+`match` = `METHOD path-glob`. Method may be `*`. `*` matches a single segment, `**` matches across `/`. First match wins.
+
+## `bindings`
+
+Mirror wrangler shapes (camelCased). Strict — unknown keys reject.
+
+```yaml
+bindings:
+  durableObjects:
+    - { binding: SESSIONS, className: SessionDO }
+    - { binding: EVENTS, className: EventStoreDO }
+    - { binding: BUNDLE, className: BundleDO }
+  d1Databases:
+    - { binding: AUDIT, databaseName: acme-audit, databaseId: '${env:D1_AUDIT_ID}' }
+  kvNamespaces:
+    - { binding: BUNDLE_CACHE, id: '${env:KV_BUNDLE_CACHE_ID}' }
+    - { binding: REPLAY_NONCE, id: '${env:KV_REPLAY_NONCE_ID}' }
+  r2Buckets:
+    - { binding: SKILL_DATA, bucketName: acme-skill-data }
+  vars:
+    LOG_LEVEL: info
+```
+
+Binding names: SCREAMING_SNAKE_CASE.
+
+## `signing`
+
+```yaml
+signing:
+  algorithm: ed25519 # or rs256
+  trustRoots:
+    - kid: prod-2026-05
+      publicKeySecret: TRUSTED_PUBKEY_PROD
+  replay:
+    windowSeconds: 300 # default 300; [10, 3600]
+    nonceKv: REPLAY_NONCE # MUST match a kvNamespaces[].binding
+```
+
+Cross-validator enforces `replay.nonceKv` resolves to a KV binding name and every `publicKeySecret` appears in `secrets[]`.
+
+## `auth` (Discriminated Union)
+
+```yaml
+auth: { provider: none }
+```
+
+```yaml
+auth:
+  provider: frontegg
+  frontegg:
+    tenantResolver: subdomain # or 'header' / 'jwt-claim'
+    audience: acme-mcp
+    issuerSecret: FRONTEGG_ISSUER_URL
+```
+
+```yaml
+auth:
+  provider: oauth
+  oauth:
+    issuer: https://issuer.example.com
+    audience: acme-mcp
+    credentialsSecret: M2M_CREDS # optional, M2M
+```
+
+```yaml
+auth:
+  provider: apiKey
+  apiKey:
+    header: X-API-Key
+    allowlistSecret: ACME_API_KEYS
+```
+
+## `secrets`
+
+```yaml
+secrets:
+  - { name: TRUSTED_PUBKEY_PROD, required: true, description: 'Signing trust root (PEM)' }
+  - { name: FRONTEGG_ISSUER_URL, required: true }
+  - { name: ACME_API_TOKEN, required: true, description: 'ACME API bearer' }
+```
+
+SCREAMING_SNAKE_CASE names only. Inline values are forbidden by the schema.
+
+## `environments`
+
+```yaml
+environments:
+  staging:
+    specs:
+      - id: acme
+        spec: ./openapi/acme.yaml
+        baseUrl: https://api.staging.acme.com
+    skills: { tags: { include: [public, billing, ops] } }
+    bindings: { vars: { LOG_LEVEL: debug } }
+  production:
+    skills: { tags: { include: [public, billing, ops], exclude: [admin, experimental] } }
+    bindings: { vars: { LOG_LEVEL: info } }
+```
+
+Deep-merge for scalars + nested objects; `bindings` REPLACES (Wrangler non-inheritance semantics).
+
+## Cross-Field Validation
+
+After per-field schema parse, run `crossValidateManifest(parsed)`:
+
+| Check                                                     | Error shape                                                                       |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Secret referenced from auth/signing but not declared      | `Secret "<NAME>" referenced at <path> is not declared in secrets[]`               |
+| `signing.replay.nonceKv` not in `bindings.kvNamespaces[]` | `signing.replay.nonceKv "<X>" does not match any bindings.kvNamespaces[].binding` |
+| `skills.alwaysLoad[]` entry not kebab-case                | `skills.alwaysLoad entry "<X>" is not a valid kebab-case skill id`                |
+| Tag filter references undeclared tag                      | `skills.tags references unknown tag "<X>" (not in tags[])`                        |
+
+All errors aggregate in one report — not throw-on-first.
+
+```ts
+import * as YAML from 'yaml';
+
+import { crossValidateManifest, deployManifestSchema } from '@frontmcp/adapters/skills';
+
+const parsed = deployManifestSchema.parse(YAML.parse(raw));
+const cross = crossValidateManifest(parsed);
+if (!cross.ok) cross.errors.forEach((e) => console.error('manifest:', e));
+```
+
+## Auto-Classification Table (HTTP → MCP)
+
+| Method      | Path                   | Matching GET? | Surface  | Notify on success            |
+| ----------- | ---------------------- | ------------- | -------- | ---------------------------- |
+| GET         | `/users/{id}`          | (self)        | both     | —                            |
+| GET         | `/users`               | (self)        | resource | —                            |
+| POST        | `/users`               | yes           | tool     | `list_changed` on self       |
+| POST        | `/users/{id}`          | yes           | tool     | `updated` on self            |
+| POST        | `/users/{id}/reset-pw` | no            | tool     | `updated` on parent          |
+| POST        | any                    | no            | tool     | —                            |
+| PUT / PATCH | any                    | yes           | tool     | `updated` on self            |
+| PUT / PATCH | any                    | no            | tool     | `updated` on parent (if any) |
+| DELETE      | singular               | —             | tool     | `list_changed` on parent     |
+| DELETE      | collection             | yes           | tool     | `list_changed` on self       |
+
+The notification fires once per call regardless of which skill made it. Two skills calling the same PUT → still one event.
+
+## TypeScript Imports
+
+```ts
+import {
+  applyClassificationOverrides,
+  buildResourceChangeNotification,
+  ClassificationRegistry,
+  classifyOperations,
+  crossValidateManifest,
+  deployManifestSchema,
+  extractOpReferences,
+  renderResourceUri,
+  validateOpReferences,
+  type DeployManifest,
+} from '@frontmcp/adapters/skills';
+```
+
+## See Also
+
+- `references/deploy-to-cloudflare-skills-only.md` — the runtime that consumes the manifest
+- Docs: https://docs.agentfront.dev/frontmcp/deployment/deploy-manifest
+- Docs: https://docs.agentfront.dev/frontmcp/features/skills-only-deployment

package/catalog/frontmcp-deployment/references/deploy-to-cloudflare-skills-only.md

@@ -0,0 +1,174 @@
+---
+name: deploy-to-cloudflare-skills-only
+description: Deploy a FrontMCP server to Cloudflare Workers using the v1.3 skills-only model — OpenAPI as capability inventory, AgentScript with namespaced bindings, four meta-tools, hot-reload via GitHub Action and a signed-bundle webhook
+---
+
+# Deploy to Cloudflare Workers (Skills-Only Model)
+
+The v1.3 Cloudflare Worker target hosts FrontMCP as a control plane where the MCP surface is just **four meta-tools** (`searchSkills`, `searchKnowledge`, `describe`, `execute`) and every capability is reached through a skill. OpenAPI specs ship to the project but are NEVER directly exposed — they are the capability inventory, classified by HTTP semantics into resources / tools, with auto-derived `notifications/resources/*` events.
+
+For the conceptual picture, see [Skills-Only Deployment](https://docs.agentfront.dev/frontmcp/features/skills-only-deployment).
+For the older Express-to-Workers adapter, see [`deploy-to-cloudflare.md`](./deploy-to-cloudflare.md).
+
+## When to Use This Skill
+
+### Must Use
+
+- Deploying a FrontMCP server using the v1.3 skills-only model on Cloudflare
+- Setting up GitHub-Action-driven hot-reload of skills + OpenAPI specs without a wrangler redeploy on every push
+- Configuring AgentScript with namespaced OpenAPI bindings (`acme.getUser({...})`)
+
+### Recommended
+
+- Standing up the first hosted FrontMCP runtime
+- Migrating from the flat-tools model to skills-only
+
+### Skip When
+
+- You want a long-running Node process — use `deploy-to-node`
+- You need the full `@enclave-vm/core` CodeCall VM (pause / rerun) — host on Node; the Worker uses AST-preflight only
+- You're shipping `scripts/` skill blobs (Anthropic Agent Skills spec) — that ships in v1.7
+
+## Worker Entry File
+
+```ts
+// worker.ts (~10 lines)
+import { createWorker } from '@frontmcp/worker';
+
+import deployBundle from './frontmcp.deploy.bundle.js'; // emitted by the GH Action
+
+const { handler, durableObjects } = createWorker({
+  bundle: deployBundle,
+  env: 'production',
+});
+
+export default handler;
+export const { SessionDO, EventStoreDO, BundleDO } = durableObjects;
+```
+
+`createWorker` parses the manifest, applies the `environments.production` overlay, verifies the signed envelope against `TRUSTED_KEYS`, and assembles the FrontMCP runtime.
+
+## Storage Layout (Opinionated Default)
+
+| Binding        | Class / kind        | Purpose                                                     |
+| -------------- | ------------------- | ----------------------------------------------------------- |
+| `SESSIONS`     | DO (`SessionDO`)    | MCP session store; survives Worker restarts                 |
+| `EVENTS`       | DO (`EventStoreDO`) | Event store for Streamable HTTP + SSE resumability          |
+| `BUNDLE`       | DO (`BundleDO`)     | Last-good envelope + active classifications (hot-swappable) |
+| `AUDIT`        | D1                  | Hash-chained skill action audit log (v1.2 audit spec)       |
+| `BUNDLE_CACHE` | KV                  | Fallback bundle reused if a resync push fails               |
+| `REPLAY_NONCE` | KV                  | Replay-guard nonce dedupe (`signing.replay.windowSeconds`)  |
+| `SKILL_DATA`   | R2                  | Large skill `data/` blobs                                   |
+
+## Hot-Reload Cycle
+
+```text
+GitHub push → frontmcp/deploy-action@v1
+   1. Parse + cross-validate frontmcp.deploy.yaml
+   2. Apply environments.<env> overlay
+   3. Walk skills/; run the markdown op-reference harvester
+   4. Run the OpenAPI → MCP classifier
+   5. Inline & content-address artifacts
+   6. Sign envelope (Ed25519 by default)
+   7. POST → worker/_frontmcp/resync
+            ↓
+Worker:
+   - Verify signature against signing.trustRoots[].publicKeySecret
+   - Replay-guard via REPLAY_NONCE KV
+   - Diff: structural change (DO classes, bindings) → require redeploy
+   - Otherwise: atomic swap of skill + classification registries
+   - Emit notifications/{skills,tools,resources,prompts}/list_changed
+   - Persist envelope into BUNDLE_CACHE KV
+```
+
+Day-to-day skill / OpenAPI edits are pure hot-reload. `wrangler deploy` is only needed for structural changes.
+
+## Isolation Strategy
+
+`codecall:execute` runs agent-authored AgentScript inside the Worker isolate. Two layers:
+
+1. **AST preflight on every call** via `@enclave-vm/ast` (pure-JS, Acorn-based, Worker-safe). Rejects `eval`, `Function`, `process`, `require`, dynamic `import`, raw `fetch`, prototype-walks, etc. before the script runs.
+2. **Frozen capability scope.** Script executes with `new Function('skills', 'ctx', code)` against a frozen object that holds only the active skills' generated namespaces + `callTool` / `getTool` / `mcpLog` / `mcpNotify`.
+
+`@enclave-vm/core` (full VM) needs `node:vm` and is NOT Worker-safe — the Worker target uses AST-preflight + frozen scope only.
+
+## Auth at the Edge
+
+```yaml
+auth:
+  provider: frontegg
+  frontegg:
+    tenantResolver: subdomain
+    audience: acme-mcp
+    issuerSecret: FRONTEGG_ISSUER_URL
+```
+
+Frontegg JWT verification runs at the Worker edge — no upstream hop. Other providers (`oauth`, `apiKey`, `none`) share the same shape.
+
+## Secrets
+
+Names-only in the manifest:
+
+```yaml
+secrets:
+  - { name: TRUSTED_PUBKEY_PROD, required: true, description: 'Signing trust root (PEM)' }
+  - { name: FRONTEGG_ISSUER_URL, required: true }
+  - { name: ACME_API_TOKEN, required: true }
+```
+
+Bind values out-of-band:
+
+```bash
+wrangler secret put TRUSTED_PUBKEY_PROD
+wrangler secret put FRONTEGG_ISSUER_URL
+wrangler secret put ACME_API_TOKEN
+```
+
+The cross-validator REJECTS any manifest that references a secret name not declared in `secrets[]`.
+
+## Sample `.github/workflows/deploy.yml`
+
+```yaml
+name: Deploy
+on:
+  push: { branches: [main] }
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions: { contents: read }
+    steps:
+      - uses: actions/checkout@v6
+      - uses: frontmcp/deploy-action@v1
+        with:
+          environment: production
+          signingKey: ${{ secrets.FRONTMCP_SIGNING_KEY }}
+          secrets: |
+            TRUSTED_PUBKEY_PROD
+            FRONTEGG_ISSUER_URL
+            ACME_API_TOKEN
+        env:
+          TRUSTED_PUBKEY_PROD: ${{ secrets.TRUSTED_PUBKEY_PROD }}
+          FRONTEGG_ISSUER_URL: ${{ secrets.FRONTEGG_ISSUER_URL }}
+          ACME_API_TOKEN: ${{ secrets.ACME_API_TOKEN }}
+```
+
+Action outputs:
+
+- `deployment-url` — the Worker URL
+- `bundle-sha256` — content-addressed envelope digest (pin in release notes)
+
+## Common Mistakes
+
+- **Embedding secrets in `wrangler.toml` or the deploy YAML.** The cross-validator + schema both reject inline secret values. Always `wrangler secret put`.
+- **Using `wrangler deploy` for every push.** Once the Worker has its DO + KV + D1 bindings, day-to-day skill changes flow through `POST /_frontmcp/resync`. Only structural changes need a redeploy.
+- **Forgetting to declare `signing.replay.nonceKv`.** The cross-validator requires the value to match a binding in `bindings.kvNamespaces[]`. Without it the Worker can't dedupe replays.
+- **Mixing `acme-api` as both a spec id AND an AgentScript namespace.** Dashes aren't valid JS identifiers — add `bindingName: acmeApi` on the spec entry, or rename the spec.
+- **Assuming `notifications/resources/updated` carries no URI.** It does — `notifications/resources/list_changed` is the one with empty params.
+
+## See Also
+
+- `references/deploy-manifest-yaml.md` — full `frontmcp.deploy.yaml` schema reference
+- `references/deploy-to-cloudflare.md` — the older Express-to-Workers adapter path
+- `references/wrangler-config.md` — wrangler.toml checklist
+- Docs: https://docs.agentfront.dev/frontmcp/deployment/cloudflare-worker
+- Docs: https://docs.agentfront.dev/frontmcp/features/skills-only-deployment

package/catalog/frontmcp-deployment/references/mcp-client-integration.md

@@ -61,6 +61,16 @@ When building a FrontMCP server with a coding agent (Claude Code, Cursor, Windsu
    ```
 3. Code and iterate — every file save triggers a server reload
 
+> **The endpoint path must match the `url`.** `frontmcp dev` serves the MCP
+> endpoint at `transport.http.path` from `frontmcp.config.ts` (default `/`). The
+> `url` above ends in `/mcp`, so set `transport: { default: 'http', http: { path: '/mcp' } }`
+> in `frontmcp.config.ts` — otherwise the client hits `/mcp` while the server
+> listens on `/` and every request 404s (issue #446). `dev` honors the configured
+> path (it propagates it to the server via `FRONTMCP_HTTP_ENTRY_PATH`), and the
+> generated `clients.*.url` derives from the same `transport.http.path`, so
+> `frontmcp eject` and `dev` stay in sync. (A hard-coded
+> `@FrontMcp({ http: { entryPath } })` in metadata wins over both — keep them aligned.)
+
 ### Why HTTP for development (not stdio)
 
 - **Hot reload:** Server restarts on file change (~200ms), client reconnects automatically
@@ -68,6 +78,37 @@ When building a FrontMCP server with a coding agent (Claude Code, Cursor, Windsu
 - **Debugging:** Logs visible in terminal, Inspector UI available via `npm run inspect`
 - **Persistence:** Server stays running across edits, no new process per connection
 
+### `frontmcp dev --stdio` bridge (issue #399)
+
+If the client must speak stdio (MCPB-installed bundles, certain Claude Code configurations) and you still want the dev hot-reload loop, run the first-party watch-aware stdio bridge — replaces the third-party `mcp-remote` recipe:
+
+```bash
+frontmcp dev --stdio                  # HTTP loopback under the hood
+frontmcp dev --stdio --serve          # stdio-over-pipe (no HTTP listener)
+```
+
+Wire the client at the bridge:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "frontmcp", "dev", "--stdio"]
+    }
+  }
+}
+```
+
+Bridge guarantees:
+
+- Stdout is 100% JSON-RPC frames; diagnostics go to `./.frontmcp/dev.log` (override with `--log-file`).
+- Session id survives reload (pinned via `FRONTMCP_DEV_FORCE_SESSION_ID`).
+- Buffered RPCs during reload drain in FIFO once the child reports ready.
+- Reload deadline + buffer overflow surface structured errors (`dev_server_unreachable` / `dev_buffer_full` / `dev_reload_deadline` — codes -32099 / -32098 / -32097) so the client spinner clears instead of hanging.
+
+Flags: `--stdio`, `--serve`, `--log-file <path>`, `--buffer-size <n>` (default 8), `--reload-deadline-ms <ms>` (default 30000), `-p <port>` (HTTP-mode loopback, default 3000).
+
 ## Stdio Transport
 
 The most common transport. The MCP client spawns your server as a child process and communicates via stdin/stdout JSON-RPC.
@@ -78,6 +119,8 @@ The most common transport. The MCP client spawns your server as a child process
 - All logs are automatically redirected to stderr and `~/.frontmcp/logs/`
 - stdout contains ONLY MCP JSON-RPC protocol messages
 - One client per process (no multiplexing)
+- **Stdio binds no TCP port** — the HTTP server is disabled, so multiple stdio
+  instances of the same server run without an `EADDRINUSE` conflict
 
 ### npx (published npm package)
 
@@ -108,19 +151,43 @@ The most common transport. The MCP client spawns your server as a child process
 }
 ```
 
-### Node.js bundle
+### Node.js CLI bundle
+
+Run the **CLI bundle** (`frontmcp build --target cli`) — it parses `--stdio`
+itself before any framework initialization:
 
 ```json
 {
   "mcpServers": {
     "my-server": {
       "command": "node",
-      "args": ["/path/to/my-server.bundle.js", "--stdio"]
+      "args": ["/path/to/my-server-cli.bundle.js", "--stdio"]
     }
   }
 }
 ```
 
+### Server runner (`--target node`)
+
+`frontmcp build --target node` emits a runner at `dist/node/<name>`. Pass
+`--stdio` to serve over stdin/stdout instead of HTTP — the runner sets
+`FRONTMCP_STDIO=1`, so the server connects over stdio and binds no port:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "/path/to/dist/node/my-server",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+> Do not run the raw `--target node` bundle as `node dist/node/my-server.bundle.js --stdio`
+> — that bundle is your `@FrontMcp` server module and starts the HTTP server on
+> import. Use the runner above, or set `FRONTMCP_STDIO=1` before the bundle loads.
+
 ## HTTP Transport
 
 Connect to a running FrontMCP HTTP server. The server must be started separately.
@@ -190,6 +257,82 @@ The `url` hostname is ignored for Unix sockets; only the path (`/mcp`) is used f
 | VS Code        | `.vscode/mcp.json`           | Project root                                    |
 | Windsurf       | `mcp_config.json`            | `~/.codeium/windsurf/`                          |
 
+## Claude Code plugin install (issue #411)
+
+For Claude Code specifically, you can ship the whole server — MCP entry +
+prompts (as slash commands) + `@Skill`s — as a single Claude Code plugin
+folder, registered in one command. This is the recommended path when you
+want users to enable/disable the server from `/plugins` rather than
+hand-edit `.mcp.json`.
+
+### From a project source (dev tool)
+
+```bash
+# At a FrontMCP project root — emits .claude/plugins/<name>/ in cwd
+frontmcp plugin install --claude
+
+# Inspect the plan without writing
+frontmcp plugin install --claude --dry-run
+
+# Also drop a Codex mcp_servers entry into ~/.codex/config.toml
+frontmcp plugin install --claude --codex
+
+# Report install state
+frontmcp plugin status --claude
+
+# Remove what install wrote (preserves user-added files)
+frontmcp plugin uninstall --claude
+```
+
+### From a built bin (end-user)
+
+Every CLI built with `frontmcp build --target cli` inherits the same
+behavior under its `install` verb (no new top-level verb):
+
+```bash
+my-bin install -p claude              # write .claude/plugins/my-bin/
+my-bin install -p claude --scope user # ~/.claude/plugins/my-bin/
+my-bin install -p claude -p codex     # both providers in one call
+my-bin install --status               # report state per provider
+my-bin uninstall -p claude            # remove only managed files
+```
+
+### What gets written
+
+```text
+.claude/plugins/<bin>/
+├── .claude-plugin/plugin.json   # name, version, mcpServers, skills, _meta.frontmcp.managedFiles
+├── commands/<prompt>.md         # one per @Prompt the server advertises
+└── skills/<name>/SKILL.md       # one per @Skill, with references/examples/scripts/assets subdirs
+```
+
+### SKILL.md frontmatter synthesis
+
+Claude Code's filesystem loader discovers skills via the YAML frontmatter at
+the top of each `SKILL.md` (`name`, `description`, optional `tags`,
+`license`). A `@Skill`-decorated entry typically points
+`instructions.file` at a plain markdown body **without** frontmatter, so the
+install flow composes the frontmatter from the decorator metadata before
+writing the file:
+
+- `name` and `description` come from `@Skill({ name, description })`.
+- `tags` and `license` are forwarded when present.
+- The instruction file body is copied verbatim AFTER the synthesized
+  frontmatter block.
+- If the instruction file **already starts with `---`**, the existing
+  frontmatter is preserved as-is — the author is treated as authoritative.
+
+Skill names are validated against the same allowlist as plugin names
+(`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`) before any filesystem write, so a malicious
+`@Skill({ name: '../escape' })` cannot land outside the plugin tree.
+
+### Idempotency
+
+Re-runs are idempotent: any file not listed in `_meta.frontmcp.managedFiles`
+(including unknown top-level keys the user added to `plugin.json`, like
+`hooks` or extra `mcpServers`) is preserved. Use `--dry-run` to inspect
+the planned tree before writing.
+
 ## Common Patterns
 
 | Pattern     | Correct                       | Incorrect              | Why                                                 |