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
Summary
Custom agents (
.agent.md) declare their capabilities in frontmatter —tools,mcp-servers,hooks,model. Skills (SKILL.md) cannot. Today SKILL.md frontmatter supports onlyname,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:kusto-queryskill expectsrunCommand. Every agent loading it must listrunCommandintools:. Forget → the skill loads but its scripts can''t run. Silent failure.teams-searchskill expects themicrosoft-teamsMCP. Same problem. Forget → tool calls 404.session-context-primerskill that wants to fire aSessionStarthook 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).Proposal
Extend SKILL.md frontmatter with the same optional capability fields available on
.agent.md:Inheritance semantics (proposed):
toolsandmcp-serversdeclared by a skill union with the consuming agent''s declarations. Skill needs become an additive contract.hooksdeclared by a skill activate only when the skill is invoked, scoping naturally with skill lifecycle.modelis 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
kusto-queryskill declaresmcp-servers: [kusto]so any agent loading it gets Kusto access automaticallysession-context-primerskill declareshooks: ./session-start.jsonso the priming hook travels with the skillcode-reviewskill declarestools: [readFile, applyPatch]so it can edit code without per-agent reconfigurationreact-component-authorskill declaresmodel: claude-sonnet-4-highfor nuanced UI work, as a hintWhy 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.mdalready supports the proposed fields → reduces inconsistency between agents and skillsReferences
.agent.mdfields includingtools,mcp-servers,hooks,model