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:

.github/

.claude/

.codex/

.config/opencode/

Throughout this document,

<provider>/

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]