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:

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 .gemini 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]