- MDX 96.1%
- TypeScript 3.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
0e338dbc07* Add draft SEP for Skills Extension Pre-submission Extensions Track SEP defining the skill:// resource convention: skills as MCP resources following the Agent Skills spec, discovered via scoped resources/list (SEP-2093). Includes implementation guidelines for host-provided read_resource tools, virtual-filesystem unification with local skills, and SDK convenience wrappers. * Relax URI structure and make discovery optional - skill-path may be arbitrarily nested and need not match the frontmatter name; the URI is a locator, identity lives in SKILL.md - resources/list(uri="skill://") is SHOULD not MUST; response is SKILL.md entries only, supporting files excluded - resource templates are MAY, framed as user-facing (completion API) - direct URI readability is the baseline; hosts must support loading skills they have never seen listed - SEP-2093 dependency is now conditional on whether the server supports enumeration * Constrain final path segment to match frontmatter name The previous draft fully decoupled <skill-path> from the skill name, which meant the name could not be read from the URI without fetching and parsing SKILL.md. Now: the final segment of <skill-path> MUST equal the frontmatter name. Preceding segments remain an optional server-chosen prefix for organizational hierarchy. This keeps the hierarchy capability while making the skill name recoverable from the URI alone. * Replace scoped resources/list enumeration with skill://index.json Enumeration now uses a well-known skill://index.json resource whose format mirrors the Agent Skills .well-known discovery index: same $schema, same skills[] shape. Two deltas from the HTTP index: url holds the full skill:// URI, and digest is omitted (transport handles integrity over an authenticated connection). type MUST be "skill-md" since archives don't apply when every file is individually addressable. This drops the SEP-2093 dependency entirely — the extension now has zero protocol dependencies beyond resources/read. Also includes review feedback from PR #69: - Security: skill content MUST be treated as untrusted input; hosts MUST NOT honor local-execution mechanisms (hooks, scripts) without explicit opt-in; "more harm" softened to "as much harm"; user inspection SHOULD be supported - Cite agentskills.io parent-directory rule for the final-segment constraint - No-nesting constraint reworded per cliffhall suggestion - Abstract mentions progressive disclosure as delegated concern - Hosts section: SHOULD load frontmatter into context, SHOULD surface skills for user enable/disable - read_resource signature marked illustrative - "community has explicitly pushed back" softened * Relax skill:// scheme to SHOULD; add urlTemplate to index The index is now the authoritative record of which resources are skills, so the scheme prefix is no longer required for identification. Servers SHOULD use skill:// but MAY serve skills under a domain-native scheme (github://, etc.) provided they're listed in skill://index.json. Structural constraints (final segment = name, explicit SKILL.md, no nesting) apply regardless of scheme. Index entries now carry exactly one of url or urlTemplate. type stays "skill-md" either way — it describes what the resolved URL points to, not whether the entry is parameterized. Template entries omit name. Servers SHOULD register the same urlTemplate as an MCP resource template so the completion API works. The Resource Templates subsection is deleted; templates are now an index feature (a "template entry") rather than a parallel discovery mechanism. Discovery is down to two mechanisms: the index and server instructions. skill://index.json remains the one fixed URI. * Use type:"mcp-resource-template" for template index entries Template entries now reuse the url field with type as the discriminator, rather than a separate urlTemplate field. This is consistent with the upstream schema where type already discriminates how to interpret url (skill-md vs archive). The mcp-resource-template type is namespaced so upstream consumers skip it safely per the existing unrecognized-type rule. |
||
| .github | ||
| docs | ||
| .gitignore | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| README.md | ||
Skills Over MCP Working Group
⚠️ Experimental — This repository is an incubation space for the Skills Over MCP Working Group. Contents are exploratory and do not represent official MCP specifications or recommendations.
Charter: modelcontextprotocol.io/community/skills-over-mcp/charter — mission, scope, membership, active work items, and success criteria. Project board: Skills Over MCP WG Meeting notes: Skills Over MCP WG discussions Discord: #skills-over-mcp-wg
Why Skills Over MCP?
MCP servers give agents tools, but tools alone are insufficient for complex workflows — tool descriptions tell an agent what a tool does, not how to orchestrate multiple tools to achieve a goal. Skills bridge this gap. They are structured "how-to" knowledge: multi-step workflows, conditional logic, and orchestration instructions that can run to hundreds of lines.
Skills are context, and MCP is a context protocol. Agents already connect to remote services over MCP to get tools — they can get the know-how to use those tools through the same channel. A remote MCP server can serve both its tools and the instructions for using them together, as a single atomic unit. This also enables automatic discovery (connect to a server, find its skills), dynamic updates (server-side changes flow without reinstall), multi-server composition (skills orchestrating tools across servers), and enterprise distribution (RBAC, multi-tenant, version-adaptive content) — all through infrastructure MCP servers already provide.
See why-and-when.md for the full value proposition and a guide for when MCP distribution applies vs. simpler alternatives.
Problem Statement
Native "skills" support in host applications demonstrates demand for rich workflow instructions, but there's no convention for exposing equivalent functionality through MCP primitives. Current limitations include:
- Server instructions load only at initialization — new or updated skills require re-initializing the server
- Complex workflows exceed practical instruction size — some skills require hundreds of lines of markdown with references to bundled files
- No discovery mechanism — users installing MCP servers don't know if there's a corresponding skill they should also install
- Multi-server orchestration — skills may need to coordinate tools from multiple servers
See problem-statement.md for full details.
Repository Contents
| Document | Description |
|---|---|
| Problem Statement | Current limitations and gaps |
| Why Skills Over MCP? | Value proposition and decision guide |
| Use Cases | Key use cases driving this work |
| Approaches | Approaches being explored (not mutually exclusive) |
| Open Questions | Unresolved questions with community input |
| Experimental Findings | Results from implementations and testing |
| Related Work | SEPs, implementations, and external resources |
| Decision Log | Record of key decisions with context and rationale |
| Draft SEP: Skills Extension | Pre-submission SEP draft defining the skill:// resource convention |
Contributing
See CONTRIBUTING.md for how to participate.