spb/skills-spboucher-ai

1# External standards and client conventions23Facts below were read from the official pages on **2026-11-09**. They drive `packages/registry-core/src/skillmd.ts` and `install.ts`. Re-verify before changing either file; these conventions move.45Items marked UNVERIFIED could not be confirmed on an official page and are not relied on.67## Agent Skills open specification89Source: https://agentskills.io/specification1011A skill is a directory containing `SKILL.md`: YAML frontmatter followed by a Markdown body.1213| Field | Required | Constraints |14|---|---|---|15| `name` | yes | 1–64 characters; lowercase `a-z`, `0-9`, hyphens; no leading or trailing hyphen; no `--`; must match the parent directory name |16| `description` | yes | 1–1024 characters; what the skill does and when to use it |17| `license` | no | licence name or bundled licence file |18| `compatibility` | no | 1–500 characters |19| `metadata` | no | map of string to string |20| `allowed-tools` | no | space-separated string, for example `Bash(git:*) Read`; experimental |2122- The specification gives no literal regular expression for `name`. The registry uses the equivalent `^[a-z0-9]+(-[a-z0-9]+)*$` with a 64-character limit (our derivation).23- `scripts/`, `references/` and `assets/` are conventions; other files are allowed.24- Recommendations: body under 5000 tokens, `SKILL.md` under 500 lines, relative file references one level deep.25- Reference validator: `skills-ref validate ./my-skill`.2627How the registry applies it: the frontmatter `name` must equal the artifact slug (the install directory), because the specification requires name and directory to match. Fields outside the specification produce a non-blocking finding.2829## Claude Code3031Skills — source: https://code.claude.com/docs/en/skills3233- Personal: `~/.claude/skills/<skill-name>/SKILL.md`34- Project: `.claude/skills/<skill-name>/SKILL.md`35- Enterprise: `.claude/skills/` in the managed settings directory36- Plugin: `<plugin>/skills/<skill-name>/SKILL.md`37- Claude Code accepts frontmatter fields beyond the open specification (`when_to_use`, `argument-hint`, `disable-model-invocation`, `user-invocable`, `model`, `context`, `agent`, `hooks`, `paths`, and others). Its documentation warns that such fields cause a hard error when packaging or uploading outside Claude Code.3839MCP — source: https://code.claude.com/docs/en/mcp4041```bash42# remote HTTP server with a header43claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"4445# local stdio server46claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server47```4849- Scopes (`--scope`): `local` (default) and `user` are stored in `~/.claude.json`; `project` is stored in `.mcp.json` at the project root.50- SSE transport is deprecated.51- `.mcp.json`:5253```json54{55  "mcpServers": {56    "api-server": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${API_KEY}" } },57    "local": { "command": "npx", "args": ["-y", "pkg"], "env": { "K": "${K}" } }58  }59}60```6162The `local` entry is a composite of the documented stdio shape, not a verbatim example from the page. Environment expansion is `${VAR}` and `${VAR:-default}`.6364## OpenAI Codex6566The pages `developers.openai.com/codex/skills` and `/codex/mcp` redirect to `learn.chatgpt.com`; facts come from that host.6768Skills — source: https://learn.chatgpt.com/docs/build-skills6970- Supported; the documentation says skills "build on the open agent skills standard".71- Repository: `.agents/skills` in the working directory and each parent up to the repository root.72- User: `$HOME/.agents/skills`73- Admin: `/etc/codex/skills`74- `name` and `description` are required; an optional `agents/openai.yaml` holds UI metadata, invocation policy and tool dependencies.75- UNVERIFIED: whether the legacy `~/.codex/skills` path is still read. The registry does not install there.7677MCP — source: https://learn.chatgpt.com/docs/extend/mcp?surface=cli7879Configured in `~/.codex/config.toml`, or a project `.codex/config.toml` for trusted projects.8081```toml82[mcp_servers.context7]            # stdio83command = "npx"84args = ["-y", "@upstash/context7-mcp"]85env_vars = ["LOCAL_TOKEN"]        # forward from the environment86[mcp_servers.context7.env]87MY_ENV_VAR = "MY_ENV_VALUE"8889[mcp_servers.figma]               # streamable HTTP90url = "https://mcp.figma.com/mcp"91bearer_token_env_var = "FIGMA_OAUTH_TOKEN"92http_headers = { "X-Figma-Region" = "us-east-1" }93```9495- Other stdio key: `cwd`. Other HTTP keys: `auth`, `env_http_headers`, `http_headers_helper`.96- CLI for stdio: `codex mcp add <server-name> --env VAR=VALUE -- <command>`.97- UNVERIFIED: CLI flags for adding an HTTP server. The registry shows the TOML block instead.9899## Cursor100101Skills — source: https://cursor.com/docs/context/skills102103- Project: `.agents/skills/` and `.cursor/skills/`104- User: `~/.agents/skills/` and `~/.cursor/skills/`105- Frontmatter: `name` and `description` required; optional `paths`, `disable-model-invocation`, `icon`, `color`, `metadata`.106107MCP — source: https://cursor.com/docs/context/mcp108109Project `.cursor/mcp.json`, global `~/.cursor/mcp.json`.110111```json112{113  "mcpServers": {114    "my-local-server": { "type": "stdio", "command": "python", "args": ["${workspaceFolder}/tools/mcp_server.py"], "env": { "API_KEY": "${env:API_KEY}" } },115    "my-remote-server": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" } }116  }117}118```119120Interpolation is `${env:NAME}`, `${userHome}`, `${workspaceFolder}` — different from Claude Code's `${VAR}`.121122## Model Context Protocol123124- Latest revision: `2026-07-28` (https://modelcontextprotocol.io/specification/latest).125- Transports: stdio and Streamable HTTP (https://modelcontextprotocol.io/specification/2026-07-28/basic/transports). Each message is an HTTP POST to a single endpoint; replies arrive as a JSON object or a request-scoped SSE stream.126- This revision makes requests stateless and self-contained: no connection-scoped `initialize` handshake and no server-initiated JSON-RPC requests. Protocol version and capabilities travel per request. A fallback for older revisions is defined.127- Authorization (https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization): optional. HTTP transports should conform when they use it; stdio should take credentials from the environment. The defined mechanism is OAuth 2.1 with RFC 9728 protected-resource metadata and RFC 8707 resource indicators. Tokens go in `Authorization: Bearer`, never in the query string.128- Static bearer tokens and API keys are not mentioned by the specification: neither defined nor forbidden. They are common practice, supported by Claude Code, Codex and Cursor through static headers. The registry uses them in V1 and says so (ADR-0008).129- Not read: the authorization sub-pages on security considerations and client registration.130131## Where the registry installs skills132133| Client id | User scope | Project scope |134|---|---|---|135| `claude-code` | `~/.claude/skills/<slug>` | `.claude/skills/<slug>` |136| `codex` | `~/.agents/skills/<slug>` | `.agents/skills/<slug>` |137| `cursor` | `~/.cursor/skills/<slug>` | `.cursor/skills/<slug>` |138| `generic-agent-skills` | `~/.agents/skills/<slug>` | `.agents/skills/<slug>` |139