validate-agent-files

Validate Agent Files

Validates that agent, skill, prompt, and instruction files follow the correct format and structure.

Provider Folder Reference

This skill works across multiple AI coding assistant providers:

Provider	Base Folder
GitHub Copilot	.github/
Claude Code	.claude/
Codex	.codex/
OpenCode	.config/opencode/

Throughout this document, <provider>/ represents your chosen provider's base folder.

When to Use

• Before committing new agents, skills, prompts, or instructions
• When an agent isn't behaving as expected
• To audit existing customization files for issues
• After modifying any .github customization files

Validation Process

Step 1: Identify File Type

Determine the type based on location and extension:

• <provider>/agents/*.md → Agent file (user-invokable)
• <provider>/agents/*.subagent.agent.md → Sub-agent file (workflow component)
• <provider>/skills/*/SKILL.md → Skill file
• <provider>/prompts/*.prompt.md → Prompt file
• <provider>/instructions/*.instructions.md → Instruction file

Step 2: Apply Type-Specific Validation

Agent File Validation (<provider>/agents/*.md)

Required Structure:

---
name: agent-name
description: When to use this agent (should include examples)
user-invokable: true  # Optional, defaults to true
---

[System prompt body]

Supported Frontmatter Attributes:

• name (required) - Agent identifier
• description (required) - When/how to use, with examples
• user-invokable (optional) - Set to false for sub-agents (default: true)
• tools - List of allowed tools
• model - Specific model to use
• handoffs - Other agents this can delegate to

Checks:

1. ✓ YAML frontmatter present with --- delimiters
2. ✓ name field exists and is non-empty
3. ✓ description field exists (recommend 50+ characters with examples)
4. ✓ Body content exists after frontmatter
5. ✓ If tools specified, they are valid tool names
6. ✓ If filename contains .subagent.agent.md, verify user-invokable: false is set