# External standards and client conventions

Facts 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.

Items marked UNVERIFIED could not be confirmed on an official page and are not relied on.

# Agent Skills open specification

Source: https://agentskills.io/specification

A skill is a directory containing SKILL.md: YAML frontmatter followed by a Markdown body.

• 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).
• scripts/, references/ and assets/ are conventions; other files are allowed.
• Recommendations: body under 5000 tokens, SKILL.md under 500 lines, relative file references one level deep.
• Reference validator: skills-ref validate ./my-skill.

How 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.

# Claude Code

Skills — source: https://code.claude.com/docs/en/skills

• Personal: ~/.claude/skills/<skill-name>/SKILL.md
• Project: .claude/skills/<skill-name>/SKILL.md
• Enterprise: .claude/skills/ in the managed settings directory
• Plugin: <plugin>/skills/<skill-name>/SKILL.md
• 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.

MCP — source: https://code.claude.com/docs/en/mcp

# remote HTTP server with a header
claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"

# local stdio server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

• Scopes (--scope): local (default) and user are stored in ~/.claude.json; project is stored in .mcp.json at the project root.
• SSE transport is deprecated.
• .mcp.json:

{
  "mcpServers": {
    "api-server": { "type": "http", "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${API_KEY}" } },
    "local": { "command": "npx", "args": ["-y", "pkg"], "env": { "K": "${K}" } }
  }
}

The local entry is a composite of the documented stdio shape, not a verbatim example from the page. Environment expansion is ${VAR} and ${VAR:-default}.

# OpenAI Codex

The pages developers.openai.com/codex/skills and /codex/mcp redirect to learn.chatgpt.com; facts come from that host.

Skills — source: https://learn.chatgpt.com/docs/build-skills

• Supported; the documentation says skills "build on the open agent skills standard".
• Repository: .agents/skills in the working directory and each parent up to the repository root.
• User: $HOME/.agents/skills
• Admin: /etc/codex/skills
• name and description are required; an optional agents/openai.yaml holds UI metadata, invocation policy and tool dependencies.
• UNVERIFIED: whether the legacy ~/.codex/skills path is still read. The registry does not install there.

MCP — source: https://learn.chatgpt.com/docs/extend/mcp?surface=cli

Configured in ~/.codex/config.toml, or a project .codex/config.toml for trusted projects.

[mcp_servers.context7]            # stdio
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]        # forward from the environment
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

[mcp_servers.figma]               # streamable HTTP
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

• Other stdio key: cwd. Other HTTP keys: auth, env_http_headers, http_headers_helper.
• CLI for stdio: codex mcp add <server-name> --env VAR=VALUE -- <command>.
• UNVERIFIED: CLI flags for adding an HTTP server. The registry shows the TOML block instead.

# Cursor

Skills — source: https://cursor.com/docs/context/skills

• Project: .agents/skills/ and .cursor/skills/
• User: ~/.agents/skills/ and ~/.cursor/skills/
• Frontmatter: name and description required; optional paths, disable-model-invocation, icon, color, metadata.

MCP — source: https://cursor.com/docs/context/mcp

Project .cursor/mcp.json, global ~/.cursor/mcp.json.

{
  "mcpServers": {
    "my-local-server": { "type": "stdio", "command": "python", "args": ["${workspaceFolder}/tools/mcp_server.py"], "env": { "API_KEY": "${env:API_KEY}" } },
    "my-remote-server": { "url": "https://api.example.com/mcp", "headers": { "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" } }
  }
}

Interpolation is ${env:NAME}, ${userHome}, ${workspaceFolder} — different from Claude Code's ${VAR}.

# Model Context Protocol

• Latest revision: 2026-07-28 (https://modelcontextprotocol.io/specification/latest).
• 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.
• 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.
• 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.
• 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).
• Not read: the authorization sub-pages on security considerations and client registration.

# Where the registry installs skills