| name | yaml-frontmatter-validator |
| description | Validate YAML frontmatter schemas for all GitHub Copilot configuration file types. Use when creating, reviewing, or debugging .agent.md, .instructions.md, .prompt.md, or SKILL.md files. Provides complete field schemas, type constraints, and common error patterns. |
YAML Frontmatter Validator
Validate frontmatter for all Copilot configuration file types against their canonical schemas.
How to Use
- Identify the file type being validated
- Check all required fields are present
- Verify field values match type constraints
- Cross-reference agent/file names against actual paths
Schemas
Agent Definition (.agent.md)
| Field | Required | Type | Constraints |
|---|
description | Yes | string | Max 200 characters. Must be specific and actionable. |
name | No | string | Defaults to filename (without .agent.md). |
tools | No | string[] | Valid: read, edit, search, web, execute, agent, todo, "server-name/*", "server-name/tool-name". Omit for all tools. |
agents | No | string[] | Each must match an existing .agent.md filename (without extension). |
handoffs | No | object[] | Each entry: label (required string), agent (required string), prompt (optional string), send (optional boolean), model (optional string). |
user-invocable | No | boolean | Default: true. Set false for subagent-only agents. |
disable-model-invocation | No | boolean | Default: false. Prevents automatic invocation as subagent. |
argument-hint | No | string | Placeholder text shown in chat input. |
model | No | string or string[] | AI model name, or prioritized fallback array. |
target | No | string | "vscode" or "github-copilot". |
hooks | No | object | Agent-scoped hooks (VS Code Preview). |
mcp-servers | No | object | MCP server configurations (target: github-copilot). |
Deprecated fields:
| Field | Status | Migration |
|---|
infer | RETIRED | Use user-invocable + disable-model-invocation instead. |
Instructions File (.instructions.md)
| Field | Required | Type | Constraints |
|---|
applyTo | Yes | string (glob) | Must match intended files. Test with ls or find. |
name | No | string | Display name for the instruction set. |
description | No | string | Purpose description. |
excludeAgent | No | string | "code-review" or "coding-agent". Excludes this instruction from specified agent type. |
Prompt File (.prompt.md)
| Field | Required | Type | Constraints |
|---|
name | Recommended | string | Defaults to filename (without .prompt.md). |
description | Recommended | string | Brief purpose description. |
agent | No | string | Agent to execute in agent mode. Must match existing agent name. |
argument-hint | No | string | Placeholder hint text for user input. |
tools | No | string[] | Same valid values as agent tools. |
model | No | string | AI model to use for this prompt. |
Skill File (SKILL.md)
| Field | Required | Type | Constraints |
|---|
name | Recommended | string | Lowercase, kebab-case. Must match parent directory name. |
description | Recommended | string | When to use this skill. Include trigger phrases. |
Common Validation Errors
Critical (Will break functionality)
| Error | Example | Fix |
|---|
Missing description in agent | ---
tools: ["read"]
--- | Add description: "Brief purpose" |
Missing applyTo in instructions | ---
name: python
--- | Add applyTo: "**/*.py" |
| Invalid tool name | tools: ["terminal"] | Use execute instead of terminal |
| Non-existent agent reference | agents: ["code-writer"] when no code-writer.agent.md exists | Create the agent or fix the reference |
| Invalid YAML syntax | Missing quotes around glob with {} | applyTo: "**/*.{ts,tsx}" (must quote) |
Warning (May cause unexpected behavior)
| Error | Example | Fix |
|---|
| Description over 200 chars | Long descriptions get truncated | Shorten to under 200 characters |
| Overly broad glob | applyTo: "**/*" | Narrow to specific file types |
Using deprecated infer | infer: false | Replace with disable-model-invocation: true |
| Duplicate agent names | Two files with same name: field | Use unique names |
| Missing handoff target | agent: "helper" in handoff but no helper.agent.md | Create the target agent |
Info (Style recommendations)
| Issue | Recommendation |
|---|
Agent without argument-hint | Add hint to guide users on expected input |
| Skill name doesn't match directory | Rename name: to match parent folder name |
Prompt without description | Add description for discoverability |
Cross-Reference Validation
When validating a complete configuration set, verify:
- Agent → Agent references: Every name in
agents: and handoffs[].agent has a matching .agent.md file
- Prompt → Agent references: Every
agent: in prompt frontmatter matches an existing agent
- Instruction glob coverage: No two instruction files have overlapping
applyTo patterns that could conflict
- Skill directory naming:
name: field matches the parent directory name
- Tool consistency: Agents don't request tools they never use in their instructions
Validation Procedure
1. Read the file's YAML frontmatter (between `---` delimiters)
2. Parse YAML — report any syntax errors
3. Identify file type from extension
4. Check all REQUIRED fields are present
5. Validate field values against type constraints
6. Check for deprecated fields — suggest migration
7. Cross-reference agent/file names against filesystem
8. Report: VALID (no issues) | WARNINGS (non-blocking) | INVALID (blocking issues)
