Repository navigation
docs: align Skills corrections with the final SEP and website - #147
Merged
Merged
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The edits bypass the documented draft-and-release process for the immutable stable specification.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Aligns Skills documentation with the final SEP and current website.
Changes:
- Restores compatibility and capability guidance.
- Corrects example hashes, sizes, and content.
- Marks draft-era documents as historical and fixes the SEP URL.
File summaries
| File | Description |
|---|---|
specification/stable/skills.mdx |
Updates requirements and examples. |
docs/archive/why-and-when.md |
Adds historical notice. |
docs/archive/use-cases.md |
Adds historical notice. |
docs/archive/threat-model.md |
Adds historical notice. |
docs/archive/skill-uri-scheme.md |
Adds historical notice. |
docs/archive/skill-meta-keys.md |
Adds historical notice. |
docs/archive/sep-draft-skills-extension.md |
Adds historical notice. |
docs/archive/related-work.md |
Adds historical notice. |
docs/archive/problem-statement.md |
Adds historical notice. |
docs/archive/open-questions.md |
Adds historical notice. |
docs/archive/glossary.md |
Adds historical notice. |
docs/archive/findings-template.md |
Adds historical notice. |
docs/archive/experimental-findings.md |
Adds historical notice. |
docs/archive/approaches.md |
Adds historical notice. |
docs/archive/agent-plugins-analysis.md |
Adds historical notice. |
AGENTS.md |
Corrects the SEP domain. |
Review details
- Files reviewed: 16/16 changed files
- Comments generated: 1
- Review effort level: Balanced
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
olaservo
approved these changes
Sep 16, 2026
olaservo
pushed a commit
that referenced
this pull request
Oct 15, 2026
…157) Fixes #156. Aligns `specification/stable/skills.mdx` with the `2026-07-28` base schema and records the decision. - `skills/get`, `resources/directory/read`: named params interfaces, so `_meta` is required - `ReadResourceDirectoryResult` extends `CacheableResult` (**breaking**: `ttlMs`, `cacheScope` required) - `*ResultResponse` types for each method; optional `_meta` on `Skill` - Request examples carry the full required `_meta` ## Why this lands in stable These are corrections to the published page rather than new design: - **The page doesn't compile against its own stated baseline.** It says its types are those of the `2026-07-28` schema, and `ReadResourceDirectoryRequest` fails to type-check against it (#156). - **`_meta` was already required.** The page's text says every request MUST include it. Only the types and examples disagreed. - **Directory-read caching was missed in the 2026-09-08 pass.** That decision made `skills/list` and `skills/get` cacheable so that every result type in the extension stays uniform with the base protocol; `resources/directory/read` was the one it didn't catch. This is the only change that adds a requirement on servers, and it affects an optional method behind `directoryRead: true`. Corrections like these have landed on stable in place before (#139, and #147 after SEP-2640 went Final), so I've followed that route rather than opening a `draft/` revision. `index.md` excerpt ranges are re-anchored to the new line numbers. ## Verification All interfaces and all 16 examples type-check under `--strict` against the base schema; `docs:build` passes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01M8b7Vuu2jRefMhoZB3BrrX --- _Generated by [Claude Code](https://claude.ai/code)_ Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The stable Skills page missed the final SEP's Agent Skills compatibility clause, and its examples used abbreviated hashes and inconsistent byte sizes. Archived drafts also retained current-sounding source-of-truth guidance.
This corrects the stable page directly to match already-established requirements: restores the compatibility clause, shows the resources capability and server/discover, explains omitted request metadata, and makes the example manifests and content consistent. It also labels archived documents as historical and fixes the SEP domain in AGENTS.md. This is an editorial alignment, not a new extension proposal; #142 remains separate.
Validation: all JSON examples parsed; all 13 manifest entries checked against sample bytes for SHA-256 and size; the corrected specification builds with the VitePress publishing site; git diff --check passed.
AI assistance: prepared with Codex.