jburlison/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

Naming Convention Checks:

• User-facing agents: <name>.agent.md or <name>.md
• Sub-agents: <name>.subagent.agent.md with user-invokable: false

Common Issues:

• Missing --- delimiters
• Empty or minimal description
• No usage examples in description
• Body content missing or too brief
• Sub-agent missing user-invokable: false
• Sub-agent not using .subagent.agent.md naming convention

Skill File Validation (<provider>/skills/*/SKILL.md)

Required Structure:

---
name: skill-name
description: What this skill does and when to use it.
---

[Skill instructions body]

Supported Frontmatter Attributes:

• name (required) - Must match parent directory name, lowercase with hyphens
• description (required) - Max 1024 chars, describes function and triggers
• license (optional) - License information
• compatibility (optional) - Environment requirements
• metadata (optional) - Key-value pairs for additional info
• allowed-tools (optional) - Space-delimited pre-approved tools

Checks:

1. ✓ File is named SKILL.md inside a directory
2. ✓ name matches parent directory name exactly
3. ✓ name is lowercase, alphanumeric with hyphens only
4. ✓ name doesn't start/end with hyphen or have consecutive hyphens
5. ✓ description is 1-1024 characters
6. ✓ Body content provides clear instructions

Common Issues:

• name doesn't match directory name
• Uppercase characters in name
• Description too vague (should include trigger keywords)
• Missing instructions in body

Prompt File Validation (<provider>/prompts/*.prompt.md)

Required Structure:

---
mode: agent
description: What this prompt does
---

[Prompt template with {{variables}}]

Supported Frontmatter Attributes:

• mode (optional) - One of: agent (default), ask, edit, generate
• tools (optional) - Available tools for this prompt
• description (optional but recommended) - What the prompt accomplishes

Checks:

1. ✓ File has .prompt.md extension
2. ✓ If mode present, it's a valid value
3. ✓ Variables use {{variableName}} syntax
4. ✓ Body content exists (the prompt itself)

Common Issues:

• Wrong extension (.md instead of .prompt.md)
• Invalid mode value
• Undefined variables in template

Instruction File Validation (<provider>/instructions/*.instructions.md)

Required Structure:

---
applyTo: "**/*.ts"
---

[Contextual instructions]

Supported Frontmatter Attributes:

• applyTo (required) - Glob pattern(s) for when instructions apply

Checks:

1. ✓ File has .instructions.md extension
2. ✓ applyTo field exists
3. ✓ applyTo contains valid glob pattern(s)
4. ✓ Body content provides meaningful guidance

Common Issues:

• Wrong extension
• Missing applyTo field
• Invalid glob syntax
• Empty or minimal instructions

Output Format

## Validation: [filename]

**Type:** [Agent|Skill|Prompt|Instruction]
**Status:** ✅ Valid | ⚠️ Warnings | ❌ Invalid

### Issues
- [Issue 1 with line number if applicable]
- [Issue 2]

### Recommendations
- [Suggestion for improvement]

Batch Validation

When validating all files, provide summary:

## Validation Summary

| Type | Total | Valid | Warnings | Invalid |
|------|-------|-------|----------|---------|
| Agents | X | X | X | X || Sub-Agents | X | X | X | X || Skills | X | X | X | X |
| Prompts | X | X | X | X |
| Instructions | X | X | X | X |

### Files Requiring Attention
- [List files with issues]