Skip to content

Commit cb6df6a

Browse files
olaservoclaude
andcommitted
Add cross-reference links from docs to tracking issues
Link open questions, approaches, use cases, and experimental findings to their corresponding GitHub issues so readers can find the active discussion without hunting through the issues list. - open-questions.md: "Tracked in" and "See also" links on Q1, Q4, Q5, Q7, Q8, Q12, Q13 - approaches.md: "See also" links on Approach 3, distribution section, and sampling variant - use-cases.md: "See also" links on UC3 (multi-server) and UC4 (progressive disclosure) - experimental-findings.md: contribution template note and skill reliability link Supersedes modelcontextprotocol#56. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 6aa5ba7 commit cb6df6a

4 files changed

Lines changed: 29 additions & 0 deletions

File tree

docs/approaches.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,7 @@ Examples:
6262
- Expose skills via tools like `list_skills` and `read_skills`. Server instructions can direct the agent to call the skill tool first.
6363
- Expose skills as resources (e.g. skill://...), which can also be exposed through tools
6464

65+
**See also:** [#41](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/41) — Server-side reference implementation, [#55](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/55) — Recommended _meta keys for skill resources
6566

6667
**Implementations:**
6768

@@ -99,6 +100,8 @@ Several design considerations have been suggested in community discussion and pr
99100
- **Git-based distribution:** Versioned distribution via git (tags, pinned refs) can be viable without a formal registry. Clare Liguori (AWS) noted that Terraform operated without a formal registry for a long time — Feb 26 office hours.
100101
- **Domain-level discovery:** The [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) proposes `/.well-known/skills/` for organizations to publish skills at predictable URLs with content integrity (SHA-256 digests). This is complementary to MCP — it handles discovery and distribution while MCP handles runtime consumption.
101102

103+
**See also:** [#44](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/44) — Define well-known URI schemes and naming patterns for skill resources
104+
102105
**Community input:**
103106

104107
> "Installless/temporary/ephemeral skill availability while server is installed feels like a good pattern. Clients could optionally offer to permanently install." — [Sam Morrow](https://github.com/SamMorrowDrums) (GitHub), via Discord
@@ -115,6 +118,8 @@ Instead of exposing skill tools to the main agent, use MCP's Sampling with Tools
115118

116119
**Source:** [jbnitorum](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076#issuecomment-3806151745)
117120

121+
**See also:** [#42](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/42) — Test skills-via-sampling approach
122+
118123
## 4. Gateway/Composition Pattern
119124

120125
A gateway-style server that provides a group of MCPs as one, ensuring they get requisite configuration and instructions to work in harmony.

docs/experimental-findings.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Experimental Findings
22

3+
> **Contributing findings?** See [#50](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/50) for the contribution template proposal.
4+
35
## McpGraph: Skills in MCP Server Repo
46

57
**Repo:** [TeamSparkAI/mcpGraph](https://github.com/TeamSparkAI/mcpGraph)
@@ -86,3 +88,5 @@ Multiple community members have independently reported that models do not reliab
8688
> "Skills are ephemeral and/or time decaying — it clicks once and then give it some time and they lose the plot." — Kryspin (qcompute), via Discord
8789
8890
> "I've seen lazy load skills with various degrees of success, actually looks like it might be model specific… [best pattern is] putting them in with a subagent that similarly named or mentions the topic in their description." — Kryspin (qcompute), via Discord
91+
92+
**See also:** [#37](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/37) — Compare skill delivery mechanisms: file-based vs MCP-based

docs/open-questions.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
## 1. Is this a registry problem or an MCP server problem?
44

5+
> **See also:** [#44](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/44) — Define well-known URI schemes and naming patterns for skill resources
6+
57
Should skills be discoverable through registry metadata ("if you install this server, also install this skill") or contained within the MCP server itself?
68

79
A third option is emerging: domain-level discovery via `/.well-known/skills/` (see [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc)). This decouples skill discovery from both registries and MCP servers — an organization publishes skills at a predictable URL on its own domain. This could complement MCP-level discovery rather than replace it: `.well-known` handles "find available skills," MCP handles "load and use them at runtime."
@@ -18,6 +20,8 @@ Or is the separation between "primitive server" and "skill that uses the primiti
1820

1921
## 4. How should skills relate to multiple servers?
2022

23+
> **Tracked in:** [#39](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/39) — Research skill dependency declaration and host-mediated resolution
24+
2125
A skill orchestrating tools from several servers can't live in any single server's instructions.
2226

2327
**Related:** [agentskills/agentskills#110](https://github.com/agentskills/agentskills/issues/110) — Discusses how skills should declare their tool/server dependencies. The lack of explicit dependency configuration makes multi-server skill execution unpredictable: if required servers and tools aren't already loaded, the skill can't reliably execute.
@@ -36,6 +40,9 @@ The agentskills.io spec currently has a freeform [compatibility field](https://a
3640
3741
## 5. Do clients actually leverage skills when presented via MCP?
3842

43+
> **Tracked in:** [#38](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/38) — Survey client resource-loading support across major MCP clients
44+
> **See also:** [#37](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/37) — Compare skill delivery mechanisms: file-based vs MCP-based
45+
3946
Early experiments suggest they do, but more rigorous testing is needed.
4047

4148
**Community input:**
@@ -48,10 +55,14 @@ Early experiments suggest they do, but more rigorous testing is needed.
4855

4956
## 7. What would MCP have had to get right for skills to have been shipped over MCP from the beginning?
5057

58+
> **See also:** [#47](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/47) — Create evaluation matrix mapping approaches to requirements
59+
5160
[Keith Groves](https://github.com/keithagroves)
5261

5362
## 8. What could MCP reasonably change so that it will be the obvious choice for new formats?
5463

64+
> **See also:** [#54](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/54) — The case for custom metadata instead of a URI convention
65+
5566
[Keith Groves](https://github.com/keithagroves)
5667

5768
**Community input:**
@@ -94,6 +105,8 @@ Note: Some apps like Claude Code have started to indicate in the skill frontmatt
94105

95106
## 12. Why not just resources?
96107

108+
> **See also:** [#54](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/54) — The case for custom metadata instead of a URI convention, [#55](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/55) — Define recommended _meta keys for skill resources
109+
97110
**Core Maintainer input:**
98111

99112
> "Why not just resources? That feels like the obvious implementation since skills are just files and resources already exist to expose files. i.e. just expose skills as resources the same as they're currently exposed on the filesystem and then just use the existing Agent Skills specification — client can find skills using resources/list to find SKILL.md files." — [Peter Alexander](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2076#discussion_r2736299627)
@@ -108,6 +121,9 @@ See also [Approaches](approaches.md) for more notes on using resources.
108121

109122
## 13. What is the optimal relationship between skills and MCP?
110123

124+
> **Tracked in:** [#75](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/75) — Skills Extension SEP
125+
> **See also:** [#47](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/47) — Create evaluation matrix mapping approaches to requirements
126+
111127
Skills already work as simple files that agents load directly. Adding MCP to the process should provide clear value beyond what standalone skills already offer.
112128

113129
**Community input:**

docs/use-cases.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ Skills that leverage tools from multiple off-the-shelf servers where you can't (
3030
3131
Beyond multi-server tool orchestration, skills themselves may be composable — one skill depending on another skill's output or behavior. This extends the dependency model beyond tool availability to skill availability, and raises questions about declarative dependency metadata. See [Open Question 4](open-questions.md#4-how-should-skills-relate-to-multiple-servers) for the emerging proposal on host-mediated dependency resolution.
3232

33+
**See also:** [#39](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/39) — Skill dependency declaration, [#45](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/45) — Worked examples for multi-server composition
34+
3335
## 4. Progressive Disclosure
3436

3537
Skills broken into linked sets of files for effective context management, loaded progressively as the agent needs them rather than all at once.
@@ -46,6 +48,8 @@ Skills broken into linked sets of files for effective context management, loaded
4648
4749
**Related:** [Anthropic's guidance on progressive disclosure](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
4850

51+
**See also:** [#45](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/45) — Worked examples for progressive disclosure, [#40](https://github.com/modelcontextprotocol/experimental-ext-skills/issues/40) — Client-side reference implementation for model-driven resource loading
52+
4953
## 5. Server-Skill Pairing
5054

5155
Servers that are difficult or impossible to use effectively without an accompanying skill.

0 commit comments

Comments
 (0)