Clean and and re-organize repo docs (#146)
* docs: point README and AGENTS.md at the released spec and official docs SEP-2640 is Final and the extension ships from specification/stable/skills.mdx, so the README now leads with a Specification section linking the spec file, the official docs page (modelcontextprotocol.io/extensions/skills/overview), the published SEP, and the client matrix. The experimental banner is replaced with a note that docs/ holds working documents; the charter, pulls, and issues links move off the redirecting experimental-ext-skills / charter URLs. AGENTS.md no longer names the SEP PR as the source of truth; it points agents at the stable spec page and describes the decision-log flow against that file. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: accepted spec changes land in a draft revision, not the stable file The stable specification is a released snapshot. README and AGENTS.md now say accepted decision-log proposals go into a draft revision that ships as a new release, matching the ext-tasks specification layout. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: move pre-release design documents to docs/archive SEP-2640 is Final, so docs/ now holds only living working documents. Eight historical documents move to docs/archive with an index explaining what each was and what superseded it: the SEP baseline copy, why-and-when, use-cases, approaches, skill-uri-scheme, glossary, client-mcp-support (superseded by the official client matrix), and agent-plugins-analysis. Files the published SEP links to by path (decisions, experimental-findings, open-questions, problem-statement, rationale, related-work, skill-meta-keys) stay in place so those links keep working. Cross-links are rewritten and verified; the README contents table is trimmed to match. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: archive open-questions and skill-meta-keys Both are pre-release documents whose outcomes live in the decision log and the specification. The published SEP links to them by path; a companion change in modelcontextprotocol/modelcontextprotocol repoints those links. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: fix sibling links inside archived open-questions and skill-meta-keys Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: keep only the decision log and rationale in docs/ threat-model, experimental-findings, findings-template, problem-statement, and related-work move to docs/archive with index rows. The candidates tracker and the archived client-support survey are removed in favor of the official extension client matrix, and links to them are repointed there. README drops the Why and Problem Statement sections, which duplicate the SEP's Motivation and the official overview page. CONTRIBUTING routes new implementation findings to GitHub issues. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: fix sibling links inside newly archived documents Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: add a concise implementations list One table each for servers/SDKs and hosts, one line per entry, replacing the retired candidates tracker and the related-work implementation tables. Seeded from those plus PR #141 and issue #144. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: put tracking links in the Status column of the implementations list Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: add a vendor/community category to the implementations list Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: replace the interim reference package with the TypeScript SDK row The @olaservo/ext-skills package is retired in favor of first-class skills APIs in the TypeScript SDK (typescript-sdk#2798, phase 1 in #2818). The archived related-work page now points at implementations.md for current information. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: drop pre-SEP rows from the implementations list They are already recorded in the archived related-work page; the list now points there instead. FastMCP stays because its row tracks the migration to v1. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: add official SDK progress, Tachyon, and Inspector 2.6.0 to implementations From the WG Discord channel and the SDK repos as of 2026-09-15: Go, TypeScript, Python, and C# SDKs all have open SEP-2640 PRs (Go passes conformance); the conformance suite merged; Inspector 2.6.0 shipped skills verification; Tachyon reports a server implementation. Adds an "in progress" status for open PRs. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: track Goose host support via the official issue Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: only tag community rows in the implementations list Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: tag MCP-project rows as official in the implementations list Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: split the implementations list into SDKs, servers, and hosts Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: add MCPJam Inspector to hosts Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * Revise implementations table format and content Updated the implementations table to include language and status columns. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Correct links and clarify documentation references Updated links to SEP-2640 and clarified document references. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com> Co-authored-by: Sambhav Kothari <sambhavs.email@gmail.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
parent
d866efdba2
commit
5adfff5952
1 changed files with 115 additions and 305 deletions
13
AGENTS.md
13
AGENTS.md
|
|
@ -1,16 +1,17 @@
|
|||
## What to reference as a source
|
||||
|
||||
**IMPORTANT**: The v1 SEP source of truth is the PR, not this repository. The specification text for the Skills Extension lives on **[SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640)** (`modelcontextprotocol/modelcontextprotocol`, branch [`sep/skills-extension`](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/sep/skills-extension/seps/2640-skills-extension.md)). That PR is authoritative.
|
||||
**IMPORTANT**: The source of truth for the Skills extension (`io.modelcontextprotocol/skills`) is [`specification/stable/skills.mdx`](specification/stable/skills.mdx) in this repository. It is the normative text of the extension, written against base protocol revision `2026-07-28`, and is what the official documentation at [modelcontextprotocol.io/extensions/skills/overview](https://modelcontextprotocol.io/extensions/skills/overview) summarizes.
|
||||
|
||||
[`docs/sep-draft-skills-extension.md`](docs/sep-draft-skills-extension.md) is a verbatim copy of the v1 baseline, synced from that branch at a commit pinned in the file's header. It exists so Working Group discussion, meeting notes, and decision records can quote and link stable text.
|
||||
[SEP-2640](https://modelcontextprotocol.org/seps/2640-skills-extension) is the accepted proposal behind the extension (Status: Final; [PR #2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) merged 2026-09-13). [`docs/archive/sep-draft-skills-extension.md`](docs/archive/sep-draft-skills-extension.md) is a copy of that SEP text pinned at the commit named in its header, kept so Working Group discussion, meeting notes, and decision records can quote and link stable text. It is a historical baseline, not the current spec.
|
||||
|
||||
- **Do not answer questions about what the spec says from this repository alone.** The copy is only as current as its last sync — check the pinned commit in the file header against the canonical branch before relying on it.
|
||||
- **Answer questions about what the extension requires from `specification/stable/skills.mdx`**, not from the SEP copy or the `docs/` folder. Where the spec page and the SEP differ, the [decision log](docs/decisions.md) records why (see the 2026-09-08 entry).
|
||||
- The `docs/` folder holds design history, rationale, experimental findings, and trackers. Treat it as context, not as normative text.
|
||||
|
||||
## Proposing changes beyond v1
|
||||
## Proposing changes to the specification
|
||||
|
||||
Changes beyond v1 are proposed here rather than added to the upstream SEP. The vehicle is a dated entry in [`docs/decisions.md`](docs/decisions.md) with `**Status:** Proposed`, in the ADR-lite format used throughout that file (Status / Context / Decision / Rationale / References) — the PR carrying that entry is the proposal.
|
||||
Changes are proposed here. The vehicle is a dated entry in [`docs/decisions.md`](docs/decisions.md) with `**Status:** Proposed`, in the ADR-lite format used throughout that file (Status / Context / Decision / Rationale / References) — the PR carrying that entry is the proposal.
|
||||
|
||||
Once a proposal is accepted, the resulting spec text is applied to the baseline copy and that section is marked with a pointer back to its record. A section without such a marker is v1 as it stands upstream.
|
||||
`specification/stable/skills.mdx` is a released snapshot and is not edited in place. Once a proposal is accepted, the resulting text lands in a draft revision of the specification (a `draft/` directory alongside the released text, following the layout used by [ext-tasks](https://github.com/modelcontextprotocol/ext-tasks/tree/main/specification)), the entry's status is updated to Accepted, and the draft ships as a new stable revision when released.
|
||||
|
||||
When a decision supersedes or amends an earlier one, add a forward pointer to the earlier entry's `**Status:**` line rather than rewriting the entry. The log is an auditable trace of the group's reasoning over time, not a snapshot of current state.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue