Agent Skills Spec Followups

[olaservo]

Agent Skills Spec Followups

This issue is to recap all the recurring topics related to the Agent Skills spec that we've discussed in the Skills Over MCP working group, so that we can keep tracking them in one place.

Source: transcripts from the 13 Skills over MCP office hours / working sessions held Mar 17 2026 – Aug 25 2026, meeting minutes published under Meeting Notes - Skills Over MCP WG.

---

1. Add a version field for skills

There is no version field in the spec today; the group repeatedly hit this and repeatedly said it belongs to Agent Skills, not MCP.

Candidate: a normative (or at least reserved) version field, plus guidance on what changing it means for caches and installed copies.

Discussed in: May 19 §6 "Versioning — likely an Agent Skills spec concern"; July 28 §4. April 7 is where the group set the razor that skill-level semantics like version belong in frontmatter rather than _meta.

Related work:

• discussions/420 — Proposal: Add optional version field to SKILL.md frontmatter (SemVer). Jun 12 2026. The closest match to this candidate.
• issues/46 — support versioning/locking. Open since Dec 24 2025, the oldest thread on this.
• PR #380 — feat: add optional skill versioning to .well-known spec. Open. Versioning scoped to the distribution layer instead of frontmatter.
• discussions/198 — Skill bundles with author-side version identity (skill provenance).

The spec's own metadata example already uses version: "1.0" (specification.mdx), so metadata.version is the de facto convention a normative field would have to reckon with.

---

2. Augment or rework the compatibility field

Two related problems: the spec discourages the field, and when people do use it, it is free text that only an LLM can evaluate (and its not clear if/when any hosts actually expose this field to the LLM).

Candidate: either soften/remove the advisory and add client-handling guidance, or add a structured compatibility form (key/value) alongside the free-text one so clients can filter without an LLM pass.

Discussed in: April 7 §8 "Compatibility Field Discussion", covering the "most skills don't need it" advisory and why it was added; June 2 §2 on client-side compatibility filtering; March 24.

Related work:

• discussions/299 — Proposal: structured runtime metadata for onboarding and preflight. Names both halves of this problem directly: compatibility is intentionally free-form and metadata is a flat string map, so neither can carry a checkable prerequisite.
• PR #253 — Add runtime version example to compatibility field. Merged Mar 16 2026. The current "Requires Python 3.14+ and uv" example comes from here.
• issues/440 / discussions/443 — Optional requires field for runtime-agnostic skill content portability.

The advisory text is the <Note> after the compatibility examples in specification.mdx. No open thread targets that note itself.

---

3. Standard way to declare the execution environment a skill needs

Skills can carry scripts, and nothing in the spec says what runtime they need. Because there is no declaration, implementers infer one from directory layout: the presence of scripts/ is being used as a proxy for "this skill needs a sandbox". The spec's scripts/ section says only that supported languages depend on the agent implementation, which is why the directory ends up carrying the signal.

Candidate: a declared-environment field (interpreter, sandbox, network, tool availability) that a client can check before loading or offering a skill, so the requirement is explicit in metadata rather than inferred from scripts/.

Discussed in: March 24 §2 "Script Execution and Dependency Management for Skills"; April 14 §3 on the script execution lifecycle; June 16 §4 "Non-sandbox agents and filtering out code-execution skills"; June 2 §2, where the concrete case was a client needing to filter a skill that ships a scripts directory.

Related work:

• discussions/367 — [RFC] Declared Environment Contracts for Agent Skills (env: block in SKILL.md frontmatter). May 8 2026. The most complete existing proposal for this candidate.
• discussions/299 — structured runtime metadata for onboarding and preflight.
• issues/61 — Proposal: Container Execution Fields for Agent Skills. Closed Jan 2026.
• issues/440 / discussions/443 — requires field for runtime-agnostic portability.
• issues/249 / discussions/251 — required permissions in skill metadata for least-privilege installation.
• issues/296 / discussions/303 — Flag to not load skills if code exec is required. The inference made explicit, as a boolean.
• discussions/151 — Some thought about using containerized CLI instead of scripts/. Feb 15 2026.
• discussions/166 — Skill portability among different operating systems.

Five separate field names have now been proposed for roughly one thing: env, requires, capabilities, credentials, and structured runtime metadata. That fragmentation is itself worth raising.

---

4. Reserve the io.modelcontextprotocol namespace inside skill metadata

Agreed in the meeting as an addition to the skill spec, not the MCP one.

Candidate: reserve the namespace in the Agent Skills spec and define a migration path for keys that later graduate to top level.

Discussed in: June 16 §2 "Reserving the io.modelcontextprotocol namespace in skill frontmatter metadata" — where this was agreed, with an action item to open a wording suggestion upstream.

Related work in this repo:

• PR #60 — Define _meta scoping guidelines for skill resources. Merged. Establishes the io.modelcontextprotocol.skills/ convention and the razor: metadata that also applies to non-MCP skills belongs in frontmatter.
• PR #98 — syncs the reverse-domain prefix sentence from SEP-2640 back into the working draft.

So the MCP side of the namespace already exists for _meta on skill resources. What is missing is the frontmatter metadata half.

Related work in agentskills/agentskills:

• discussions/211 — Open frontmatter schema (with namespacing guidance). Mar 5 2026, 7 comments. The most active existing thread on namespacing frontmatter keys.

Related work in adjacent specs:

• AI Catalog ADR-0012 — Extensibility via metadata Property. Accepted Apr 2026. Closed core schema, all vendor properties in a metadata object; explicitly weighed and rejected both an open schema (collisions, unvalidatable) and the OpenAPI-style x- prefix.
• Agent Plugins spec §8 — client-specific manifest data MUST sit under a reverse-domain namespace, with the "Why reverse-domain client extensions?" design decision giving the reasoning: a decentralized way to avoid collisions without a central registry.

Both specs made this choice already, and in the same direction. In agentskills/agentskills it is still an open split between discussions/192 (x- prefix) and discussions/211 (namespacing).

The spec currently says only "We recommend making your key names reasonably unique to avoid accidental conflicts" — no convention named.

---

5. Tool dependencies for a skill

The most-requested missing capability across the series. Everyone building at scale wants a skill to name the tools it needs.

Candidate: a first-class, specified way for a skill to reference tools/primitives, with defined client behaviour on load. May be dependent on the primitive-grouping / progressive-discovery work happening in MCP.

Discussed in: March 17 §4 "Progressive Disclosure of Tools via Skills"; April 14 §2 on where the SEP draws the line; April 21 "Tool-skill dependency validation"; May 5 "Inferred vs declared dependencies".

Related work — declaring dependencies:

• issues/485 — Proposal: machine-evaluable dependencies field in frontmatter for tools, with all/any semantics. Open, Aug 7 2026. The most recent and most fully specified version of this ask, though it has drawn no replies and the author has no other activity in the repo.
• issues/330 / discussions/392 — Proposal: Allow skills to declare tool dependencies. Apr 2026.
• discussions/217 — [PROPOSAL] Allow skills to declare tool dependencies. Mar 8 2026, 5 comments.
• discussions/195 — Standardize declarative MCP server dependencies for individual Skills. Feb 26 2026, 3 comments.

Related work in adjacent specs:

• AI Catalog ADR-0002 — Defer Dependency Expression Between Entries. Accepted Apr 2026, with participants from Microsoft, Cisco and Google. The scenario that triggered it was an agent skill that requires an MCP server, and the blocker they identified was AND vs. OR semantics — alternatives versus hard dependencies — which is the same all/any distinction issues/485 proposes. Two further arguments recorded there: dependency semantics may belong in the downstream artifact format rather than the envelope, and complex resolution belongs in dynamic registries rather than static catalogs.

---

6. Dependency representation between skills, and the overlap with the plugin format

Candidate: decide where inter-skill and skill→plugin dependency lives before conventions harden in registries.

Discussed in: March 17 §6 "Skill Front Matter & Plugin Format Overlap"; March 24 §2; May 5 "Inferred vs declared dependencies".

This might also be a topic for Agent Plugins.

Related work — skill to skill:

• issues/100 — Best practice on having a skill use/depend on other skills. Open since Jan 2026.
• issues/95 — Inconsistent skill-to-skill invocation behavior between implementations. Open.
• issues/110 — Skill dependencies with version validation and testing. Open.
• discussions/210 — Skill Package Manifest for Dependency Resolution and Distribution. Mar 5 2026, 12 comments, the largest thread on this.
• discussions/270 — emerge and evolves-from fields for skill composition.

Related work in Agent Plugins:

• FUTURE_CONSIDERATIONS.md — "Dependency resolution" records that plugins currently cannot declare dependencies on other plugins, and names what a future version may define: a dependencies manifest field with version constraints, resolution order and conflict handling for transitive dependencies, and peer dependency semantics. Deferred deliberately rather than unconsidered.
• discussions/51 — Add dependencies field to plugin manifest. Open, maintainer engaged.
• Agent Plugins Discord, Aug 28 2026 — request for a skill-level dependency graph in plugin.json so a base skill is loaded deterministically by the host rather than by instruction in SKILL.md.
• OpenAI said it plans to ship this as an OpenAI-specific extension first and upstream it if there is broader interest.
• Claude Code's plugin.json already supports a dependencies key.
• Agent Plugins spec §7.1 — defines the skill→plugin seam already: plugins bundle Agent Skills, defer the format entirely to the Agent Skills spec, and specify only how skills are discovered within a plugin.

---

7. Skill naming, uniqueness and portability

Candidate: the skills spec is doesn't include guidance on namespacing, and collision guidance sits in the client-implementation docs rather than the spec. It's worth stating the name constraints and that name is not a global identifier.

Discussed in: August 25 §5 "Search, tagging, namespacing, and progressive discovery".

This might also be a topic for Agent Plugins.

Related work — namespacing and collisions:

• Agent Plugins PR #67 — Add namespaced skill discovery. Open since Aug 19 2026, authored by the Agent Skills maintainer. Would let skills sit under namespace directories inside a plugin so skills/aws/deploy/ and skills/gcp/deploy/ can both be named deploy. The thread carries the cross-vendor consequence directly: one client noted it treats a skill's name as its unique identity and would need path-based identities instead. This is the most active thread anywhere on skill name collisions.
• issues/312 / discussions/318 — RFC: Collection-based namespace convention for multi-author skill ecosystems. Apr 12 2026.
• issues/109 — Allow namespaced names using forward slashes. Closed by the author as overlapping issues/59 and issues/15, both still open. The namespacing question got absorbed into a directory-layout question and has not come back.

Related work — the name field and layout:

• PR #345 — Clarify Unicode support in skill name spec. Open, but no comments or reviews since Apr 29 2026.
• issues/115 — path-based, recursive skill discovery. Open.
• issues/513 — adopt XDG Base Directory paths for global skills. Open.
• discussions/166 — Skill portability among different operating systems.

Related work in adjacent specs:

• AI Catalog ADR-0015 — Agent Identifier Naming. Accepted, with participants from Microsoft, Cisco, Google, Amazon and Pulse MCP. Keeps identifier open text for local systems but standardizes urn:air:{publisher}:{namespace}:{name} for federated ones, anchored on a publisher domain. A decided answer to "name is not a global identifier".
• Agent Plugins spec §5.5 — plugin names permit periods (acme.tools) where Agent Skills names do not, so a plugin name is not always a valid skill name.

The name rules are already tight (1–64 chars, lowercase alphanumeric and hyphens, must match the parent directory), and docs/client-implementation/adding-skills-support.mdx already sets a collision precedence rule: project-level skills override user-level ones, either first-found or last-found is acceptable within a scope, and clients should warn when a skill is shadowed.