Agent-check validates the metadata and structure of agent files in .claude/agents/, ensuring required fields, valid values, and proper content layout.

What formats are expected for tools?

Tools must be listed as a YAML list (not a bracketed array) and must include valid tool names from the allowed set.

How do I use auto-fix suggestions?

Follow the Auto-Fix guidance to convert bracket arrays to YAML lists, fix memory/memory-like fields, and add missing fields. Re-run validation after applying fixes.

agent-check

Scanned

npx machina-cli add skill claude-world/director-mode-lite/agent-check --openclaw

Files (1)

SKILL.md

3.4 KB

Agent File Validator

Validate agent files in .claude/agents/ for correct format.

Validation Target

With argument: validate specific file
Without: validate all .claude/agents/*.md

Required Frontmatter

---
name: agent-name          # Required: lowercase, hyphenated
description: Brief desc   # Required: under 100 chars
color: cyan               # Required: yellow, red, green, blue, magenta, cyan
tools:                    # Required: YAML list format
  - Read
  - Write
  - Grep
model: sonnet             # Required: inherit, haiku, sonnet, opus, best, sonnet[1m], opus[1m], opusplan
# forkContext: "true"     # Optional: run in forked context (string "true"/"false")
# maxTurns: 20            # Optional: max conversation turns (positive integer)
skills:                    # Optional: auto-load skills (array)
  - linked-skill
memory:                    # Optional: memory scopes to load (array)
  - user
  - project
  - local
mcpServers:                # Optional: MCP server refs or objects (array)
  - server-name
hooks:                     # Optional: agent-scoped lifecycle hooks
  PreToolUse:
    - matcher: Write
      command: ./validate.sh
  PostToolUse:
    - matcher: Bash
      command: ./log.sh
permissionMode: default    # Optional: permission handling
disallowedTools:           # Optional: explicit tool blocking
  - NotebookEdit
---

Valid Tools

Read, Write, Edit, Bash, Grep, Glob, Task,
WebFetch, WebSearch, TodoWrite, NotebookEdit

Valid Colors

yellow, red, green, blue, magenta, cyan

Valid Models

inherit, haiku, sonnet, opus, best, sonnet[1m], opus[1m], opusplan

Validation Checklist

Required Fields

name exists (lowercase, hyphenated)
description exists (under 100 chars)
tools exists (YAML list format, not bracket array)
color is set (valid color name)
model is set (inherit/haiku/sonnet/opus/best/sonnet[1m]/opus[1m]/opusplan)

Optional Fields

skills references existing skills (array, if set)
forkContext is string "true" or "false" (if set)
maxTurns is positive integer (if set)
memory is valid array of: user, project, local (if set)
mcpServers is valid array of string refs or objects (if set)
hooks has valid structure (if set)
permissionMode is valid value (if set)
disallowedTools are valid tool names (if set)

Content Structure

# Agent Name heading
## Activation section
Process/workflow description
Output format definition

Format Rules

tools uses YAML list format (not [Read, Write] bracket array)
No duplicate tools in list
All tools are valid tool names

Output Format

## Agent Validation Report

### Files Checked
| File | Status | Issues |
|------|--------|--------|
| code-reviewer.md | OK | None |
| my-agent.md | WARN | Missing color, model |

### Summary
- Total: [N]
- Valid: [N]
- Needs fixes: [N]

Auto-Fix

Convert bracket array tools to YAML list format
Convert string skills to YAML array
Add missing color field (default: cyan)
Add missing model field (default: inherit)
Convert boolean forkContext to string
Convert scalar memory to array format
Remove invalid tools
Add recommended sections

Source

git clone https://github.com/claude-world/director-mode-lite/blob/main/skills/agent-check/SKILL.mdView on GitHub

Overview

Agent-check validates the structure and frontmatter of agent files stored under .claude/agents/. It ensures required fields, valid tool lists, color and model values, and proper content structure to prevent misconfigured agents. It also provides auto-fix guidance to align files with the spec.

How This Skill Works

The tool parses the agent file's YAML frontmatter and key sections, verifying required fields (name, description, tools, color, model) and that values match allowed sets. It also checks content structure like Agent Name headings and Activation sections, and flags formatting issues such as incorrect tools lists or missing fields, offering auto-fix steps when possible.

When to Use It

When adding a new agent file to .claude/agents/ to ensure it meets the required spec.
During pull requests to validate changes to agent files before merging.
Before deployment or runtime loading to prevent misconfigured agents from failing.
When diagnosing agent load errors or unexpected behavior related to metadata.
When auditing multiple agents for consistency and compliance with guidelines.

Quick Start

Step 1: Place or create your agent file under .claude/agents/ with proper frontmatter.
Step 2: Run agent-check to validate required fields, format, and values.
Step 3: Apply auto-fix recommendations if issues are found and re-run validation.

Best Practices

Always use YAML list format for tools (not bracketed arrays).
Keep color values within the allowed set: yellow, red, green, blue, magenta, cyan.
Describe the agent in under 100 characters.
Avoid duplicate tools in the tools list and use valid tool names only.
Follow the content structure: include proper Agent Name heading and Activation section.

Example Use Cases

A valid agent file with name agent-name, color cyan, and model sonnet that loads skills and memory as expected.
An invalid file missing the color field, triggering a validation error and auto-fix suggestion.
A file using a bracket array for tools instead of a YAML list, flagged for format correction.
A file with an invalid tool name (e.g., NotebookEdit not in the approved set) detected during validation.
A file with a skills array referencing non-existent skills, prompting optional-field validation.

Frequently Asked Questions

Add this skill to your agents