Add capability declaration fields to SKILL.md frontmatter (tools, mcp-servers, hooks, model)

Summary

Custom agents (.agent.md) declare their capabilities in frontmatter — tools, mcp-servers, hooks, model. Skills (SKILL.md) cannot. Today SKILL.md frontmatter supports only name, description, argument-hint, user-invocable, disable-model-invocation. The asymmetry forces every consuming agent to know and re-declare a skill''s capability requirements, which leads to silent under-capability and ecosystem-specific workarounds.

Problem

If a skill needs a tool, an MCP server, a companion hook, or a specific model, that requirement is currently expressible only on the consuming .agent.md. Practical consequences:

• Tool drift. A kusto-query skill expects runCommand. Every agent loading it must list runCommand in tools:. Forget → the skill loads but its scripts can''t run. Silent failure.
• MCP drift. A teams-search skill expects the microsoft-teams MCP. Same problem. Forget → tool calls 404.
• Hooks can''t travel with the skill. A session-context-primer skill that wants to fire a SessionStart hook has no way to declare it; the hook must live at workspace or user scope (over-broad) or in the consuming agent (duplicated across consumers).
• Model preference can''t be expressed. A skill that''s known to work better with a specific model can''t say so — even as a hint.

Proposal

Extend SKILL.md frontmatter with the same optional capability fields available on .agent.md:

---
name: kusto-query
description: ...
tools: [readFile, runCommand]
mcp-servers: [kusto]
hooks: ./hooks.json
model: claude-sonnet-4
---

Inheritance semantics (proposed):

• tools and mcp-servers declared by a skill union with the consuming agent''s declarations. Skill needs become an additive contract.
• hooks declared by a skill activate only when the skill is invoked, scoping naturally with skill lifecycle.
• model is advisory — consuming agent''s model wins on conflict.

Backward compatibility

All new fields are optional. Existing SKILL.md files unchanged. Implementations that don''t recognize the fields ignore them.

Use cases

• A kusto-query skill declares mcp-servers: [kusto] so any agent loading it gets Kusto access automatically
• A session-context-primer skill declares hooks: ./session-start.json so the priming hook travels with the skill
• A code-review skill declares tools: [readFile, applyPatch] so it can edit code without per-agent reconfiguration
• A react-component-author skill declares model: claude-sonnet-4-high for nuanced UI work, as a hint

Why this matters

Today, ecosystems building shared skill libraries — internal teams, awesome-copilot, dobby — work around this gap with vendor-specific manifests, plugin-level bundling (whole plugin enables together, coarse), or convention-based docs. All of these are workarounds for the platform gap. Closing it natively makes skills truly composable as the unit of capability.

Related platform surfaces

• .agent.md already supports the proposed fields → reduces inconsistency between agents and skills
• Plugin bundling provides a coarser grouping (whole plugin enables/disables together) but doesn''t replace per-skill capability declaration
• Cross-tool relevance: the same gap exists in GitHub Copilot CLI''s SKILL.md handling (cross-filed for awareness)

References

• VS Code agent-skills docs — current SKILL.md frontmatter fields
• VS Code custom-agents docs — .agent.md fields including tools, mcp-servers, hooks, model
• GitHub Copilot CLI plugin reference — plugin-level capability declarations (coarser than per-skill)