skills.mdx: CacheableResult on skills/list and skills/get, state 2026-07-28 baseline

[pja-ant]

Follow-up to #138 addressing @panyam's review comment on specification/stable/skills.mdx, cross-checked against the base 2026-07-28 schema.

Before:

interface ListSkillsResult extends PaginatedResult { skills: Skill[] }
interface GetSkillResult extends Result { skill: Skill }

After:

interface ListSkillsResult extends PaginatedResult, CacheableResult { skills: Skill[] }
interface GetSkillResult extends CacheableResult { skill: Skill }

Changes:

• ListSkillsResult now extends CacheableResult. PaginatedResult alone does not carry ttlMs/cacheScope; those live on CacheableResult and are required there, as on tools/list and resources/list. The prose bullet now says the fields are required, and every skills/list example response carries them.
• GetSkillResult now extends CacheableResult. SEP-2640 left open whether skills/get carries caching attributes "as resources/read results do". This resolves it: yes, matching ReadResourceResult. A new semantics bullet explains ttlMs as the hint for when to re-call skills/get, and notes neither field is an integrity property. Every skills/get example response carries them.
• New "Protocol Revision" section stating the page is written against base revision 2026-07-28 or later and naming the base types it references. This is why the SEP's "in protocol versions 2026-07-28 and later" conditional is not carried.
• resources-capability line reworded as a consequence of the base Resources specification (a server serving resources/read declares resources) rather than a free-standing new MUST. The requirement itself is kept so the conformance suite can check it.
• The Example Message Flow's resources/read response also gains ttlMs/cacheScope, since ReadResourceResult requires them at this revision.
• docs/decisions.md gets a 2026-09-08 entry (Status: Proposed) recording the three normative points above as deliberate, per this repo's process for changes beyond the v1 SEP text.

Not changed here: ReadResourceDirectoryResult still extends PaginatedResult only. Its closest analogue ListResourcesResult is cacheable, so the same question applies; left for a separate decision.

All JSON examples parse and all internal anchors resolve.

🤖 Generated with Claude Code

Requested by Peter · Claude session #01Sure6S