modelcontextprotocol/ext-skills
Watch
1
0
Fork
You've already forked ext-skills
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add contributing guidelines, problem statement updates, and related work documentation

Browse source
This commit is contained in:
olaservo 2026-02-03 09:43:37 -07:00
commit 9540cb7774
3 changed files with 249 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

63
docs/experimental-findings.md Normal file
View file

@ -0,0 +1,63 @@
# Experimental Findings
## McpGraph: Skills in MCP Server Repo
**Repo:** [TeamSparkAI/mcpGraph](https://github.com/TeamSparkAI/mcpGraph)
**Skill:** [mcpgraphtoolkit/SKILL.md](https://github.com/TeamSparkAI/mcpGraph/blob/main/skills/mcpgraphtoolkit/SKILL.md) (875+ lines)
Bob Dickinson built a standalone SKILL.md file that lives in the same repo as the MCP server, but they weren't formally connected. The skill instructs agents on building directed graphs of MCP nodes to orchestrate tool calls.
**Findings:**
- Claude ignored the SKILL.md initially, even when the skill and server had similar descriptions
- Claude would fail at using the server tools a couple times, then read the skill and succeed
- Expected Claude to start with the skill ("I know how to do X") before the server ("I do X"), but it didn't
**Resolution:** Added a server instruction telling the agent to read the SKILL.md before using the tool. That one change caused Claude to reliably read the skill first.
**Remaining concerns:**
- This workaround works for 1:1 skill-to-server case, but doesn't solve discovery — users installing from a registry don't know to also install the skill
- Distinguishes between "skill required to make the server work at all" vs. "skill that orchestrates tools you could use without it" — potentially different solutions needed
## Skilljack MCP
**Repo:** [olaservo/skilljack-mcp](https://github.com/olaservo/skilljack-mcp)
Loads skills into tool descriptions. Uses dynamic tool updates to keep the skills manifest current.
## worfcat's Three-Way Comparison
Tested skills exposed in three ways across multiple clients:
### 1. Skills as MCP Resources (with a simple `validate_skill` tool)
**Result: Bad.** The model never used them or looked at them unless explicitly asked.
### 2. Skills as Tools in an MCP Server (`list_skills` and `read_skills`)
**Result: Mixed.** Needed some tool description tuning to get used. More brittle than native. Worked with Claude Code, OpenAI agent builder, and a few other clients.
### 3. Native Skills (installing in `skills/` folder of Claude Code)
**Result: Best.** Easiest, worked out of the box.
**Key insight:**
> "There is a many-many relationship between skills and tools. A skill should not require pieces of instruction like 'here's how you use this single tool'. If an instruction of how to use an MCP server is copied across skills, it should live at the server level. Context decomposition basically."
**Note:** Claude Code's skill implementation is just a tool call — `Skill(<n>)` returns the SKILL.md file. Nothing fancy (at least for now).
## FastMCP 3.0 Skills Support
**URL:** [gofastmcp.com/servers/providers/skills](https://gofastmcp.com/servers/providers/skills)
FastMCP added skills support in version 3.0. Worth examining for alignment with other approaches.
**Related:** [jlowin/fastmcp#2694](https://github.com/jlowin/fastmcp/issues/2694)
## PydanticAI Skills Support
**PR:** [pydantic/pydantic-ai#3780](https://github.com/pydantic/pydantic-ai/pull/3780)
Introduces support for agent skills with a tools-based approach.

43
docs/problem-statement.md
View file

@ -1,6 +1,6 @@
# 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.
[Agent Skills](https://agentskills.io/home) support in AI applications demonstrates demand for rich workflow instructions, but there's no convention for exposing equivalent functionality through MCP primitives.
## Current Limitations
@ -11,42 +11,13 @@ Native "skills" support in host applications demonstrates demand for rich workfl
## Key Use Cases
### 1. Complex Workflow Orchestration
See [use-cases.md](use-cases.md) for detailed use cases and community input. In summary:
Bob Dickinson's [mcpGraph](https://github.com/TeamSparkAI/mcpGraph) toolkit requires a skill file of 875+ lines to instruct agents on building directed graphs of MCP nodes. This orchestration logic is "way more than you'd want to put in instructions."
### 2. Conditional Workflows
Workflows that reference tools conditionally based on context, requiring rich structured instructions that can be dynamically loaded.
### 3. Multi-Server Composition
Skills that leverage tools from multiple off-the-shelf servers where you can't (or don't want to) modify their individual instructions.
### 4. Progressive Disclosure
Skills broken into linked sets of files for effective context management, loaded progressively as the agent needs them rather than all at once.
1. **Complex Workflow Orchestration** — Multi-step workflows requiring 875+ lines of instruction (e.g., [mcpGraph](https://github.com/TeamSparkAI/mcpGraph))
2. **Conditional Workflows** — Branching instructions dynamically loaded based on context
3. **Multi-Server Composition** — Skills leveraging tools from multiple off-the-shelf servers
4. **Progressive Disclosure** — Skills broken into linked file sets, loaded on demand
## Open Questions
1. **Is this a registry problem or an MCP server problem?** Should skills be discoverable through registry metadata ("if you install this server, also install this skill") or contained within the MCP server itself?
2. **How do "first-class" skills differ from "skills as context"?** Native agent skills can be presented through the user agent, bundled with subagents, etc. Do MCP-surfaced skills lose capabilities compared to directly installed skills?
3. **Should server.instructions be extended for richer content?** Or is the separation between "primitive server" and "skill that uses the primitive" the right abstraction?
4. **How should skills relate to multiple servers?** A skill orchestrating tools from several servers can't live in any single server's instructions.
5. **Do clients actually leverage skills when presented via MCP?** Early experiments suggest they do, but more rigorous testing is needed.
6. **How do we coordinate with agent skills spec owners?** The contribution model for the skills spec isn't clear, and MCP-related efforts should be brought to their attention.
7. **What would MCP have had to get right for skills to have been shipped over MCP from the beginning?** (https://github.com/keithagroves)
8. **What could MCP reasonably change so that it will be the obvious choice for new formats?** (https://github.com/keithagroves)
9. **Who gets visibility into skill content, and who decides when it gets loaded?** The control model question — model-controlled vs. application-controlled. (https://github.com/olaservo)
10. **How should skills handle security and trust boundaries?** If skills can be abused for prompt injection, what mitigations should be spec'd? (provenance, gating, explicit policy) (https://github.com/Agent-Hellboy)
11. **Should the control model be use-case specific?** Perhaps resources (application-controlled) for some use cases, tools (model-controlled) for others? Can a convention support both? (https://github.com/olaservo)
See [open-questions.md](open-questions.md) for the full list of unresolved questions with community input.

34
docs/related-work.md Normal file
View file

@ -0,0 +1,34 @@
# Related Work
## Open SEPs and Proposals
| Proposal | Venue | Description |
| :--- | :--- | :--- |
| [SEP-2076](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076) | MCP Spec | Agent Skills as a first-class MCP primitive |
| [skills.json format proposal](https://github.com/modelcontextprotocol/registry/discussions/895) | MCP Registry | Skills metadata in registry schema |
| [FastMCP #2694](https://github.com/jlowin/fastmcp/issues/2694) | FastMCP | Add Skills support |
| [PydanticAI #3780](https://github.com/pydantic/pydantic-ai/pull/3780) | PydanticAI | Introduce support for agent skills |
## Implementations
| Implementation | Author | URL | Notes |
| :--- | :--- | :--- | :--- |
| skilljack-mcp | Ola Hungerford | [github.com/olaservo/skilljack-mcp](https://github.com/olaservo/skilljack-mcp) | Skills as tools with dynamic updates |
| mcpGraph skill | Bob Dickinson | [github.com/TeamSparkAI/mcpGraph](https://github.com/TeamSparkAI/mcpGraph) | 875+ line skill for graph orchestration |
| skills-over-mcp | Keith Groves | [github.com/keithagroves/skills-over-mcp](https://github.com/keithagroves/skills-over-mcp) | Example using skills with current MCP primitives |
| chrome-devtools-mcp | Anthropic | [github.com/anthropics/anthropic-quickstarts/…/chrome-devtools-mcp](https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-servers/chrome-devtools-mcp) | Real-world example: `skills/` folder requires separate install path |
| NimbleBrain skills repo | NimbleBrain | [github.com/NimbleBrainInc/skills](https://github.com/NimbleBrainInc/skills) | Monorepo with `.skill` artifact format |
| NimbleBrain registry | NimbleBrain | [registry.nimbletools.ai](https://registry.nimbletools.ai/) | Registry with skill metadata support |
| FastMCP 3.0 Skills | FastMCP | [gofastmcp.com/servers/providers/skills](https://gofastmcp.com/servers/providers/skills) | Native skills provider |
| mcp-cli | philschmid | [github.com/philschmid/mcp-cli](https://github.com/philschmid/mcp-cli) | Wraps MCP servers as CLI for progressive disclosure |
| mcp-execution | bug-ops | [github.com/bug-ops/mcp-execution](https://github.com/bug-ops/mcp-execution) | Compiles MCP servers into skill packages |
| Astronomer agents | Kaxil Naik | [github.com/astronomer/agents](https://github.com/astronomer/agents) | Skills distribution via MCP for Apache Airflow |
## External Resources
- **Agent Skills Standard:** [agentskills.io](https://agentskills.io/)
- **Anthropic's guidance on progressive disclosure:** [Equipping agents for the real world with agent skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- **"MCP and Skills: Why Not Both?"** (Kurtis Van Gent): [kvg.dev/posts/20260125-skills-and-mcp/](https://kvg.dev/posts/20260125-skills-and-mcp/) — Frames MCP (connectivity) and Skills (context saturation) as complementary; discusses hybrid approaches
- **Conceptual spec visualization** (Keith Groves): [enact-465fb1fc.mintlify.app/specification/draft/server/skills](https://enact-465fb1fc.mintlify.app/specification/draft/server/skills) — "What if" exploration
- **Apache Airflow AIP-91** (MCP integration): [cwiki.apache.org/…/AIP-91+-+MCP](https://cwiki.apache.org/confluence/display/AIRFLOW/AIP-91+-+MCP)
- **Video background:** [youtube.com/watch?v=CEvIs9y1uog](https://www.youtube.com/watch?v=CEvIs9y1uog)