Skip to content

claude-world/director-mode-lite / skills/agent-check

agent-check

Verified

Validate custom agent file format and structure. Use after creating or editing an agent, before committing agent changes, or when an agent fails to load.

Agent File Validator

Validate agent files in .claude/agents/ for correct format against the official Claude Code spec (plus Director Mode conventions).


Validation Target

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

Required Frontmatter

---
name: agent-name          # Required: lowercase, hyphenated, 3-50 chars
description: >            # Required: 10-5000 chars, include triggering conditions + <example> blocks
  Use this agent when [conditions]. Examples:
  <example>
  Context: [situation]
  user: "[request]"
  assistant: "[response using this agent]"
  </example>
color: cyan               # Required by Director Mode convention (CI-enforced); OPTIONAL per official spec
model: sonnet             # Required by Director Mode convention (CI-enforced); OPTIONAL per official spec.
                          #   Valid: fable, opus, sonnet, haiku, inherit, default, best, sonnet[1m], opus[1m]
                          #   (or a full model ID). inherit is the recommended default. NOT opusplan.
effort: medium            # Optional: low, medium, high, xhigh, max
tools:                    # Optional: YAML list (omit = all tools available)
  - Read
  - Write
  - Grep
disallowedTools:          # Optional: explicit tool blocking
  - NotebookEdit
maxTurns: 20              # Optional: max agentic turns (positive integer)
skills:                    # Optional: preloaded skill names (list, at most 32)
  - linked-skill
memory: project            # Optional: one of user, project, local
background: false          # Optional: true keeps the agent in the background (boolean)
isolation: worktree        # Optional: run the agent in an isolated git worktree
omitClaudeMd: false        # Optional (2.1.271+): true starts without CLAUDE.md files
autoCompactWindow: 200000  # Optional (2.1.296+): integer, 100000-1000000
---

Valid Tools

Read, Write, Edit, Bash, Grep, Glob, Agent (Task = legacy alias),
Skill, WebFetch, WebSearch, TodoWrite, NotebookEdit, AskUserQuestion
(TodoWrite is only offered on older models unless CLAUDE_CODE_ENABLE_TODO_TOOLS=1;
list an MCP server as mcp__<whole server name>__*)

Valid Colors

red, blue, green, yellow, purple, orange, pink, cyan

Valid Models

sonnet, opus, haiku, fable, inherit, sonnet[1m], opus[1m], or a full model ID
(claude-opus-5-5). inherit recommended. Not default, best, or opusplan (/model values).

Ignored for plugin subagents (WARN if present)

hooks           # Honored in .claude/agents/; ignored when loaded from a plugin
mcpServers      # Honored in .claude/agents/; ignored when loaded from a plugin
permissionMode  # Honored in .claude/agents/; ignored when loaded from a plugin
initialPrompt   # Main-session agents only; ignored when loaded from a plugin

Director Mode ships its agents as a plugin too, so its catalog omits them. forkContext is not an official field: flag it as unknown.


Validation Checklist

Required Fields

  • name exists (lowercase, hyphenated; official limit 256 chars, no :, no leading -)
  • description exists (10-5000 chars, recommend 200-1000 with <example> blocks)
  • color is set (valid color name) — required by Director Mode convention, optional per spec
  • model is set (valid value below) — required by Director Mode convention, optional per spec

Optional Fields (official)

  • tools are valid tool names, YAML list format (omit = all tools available)
  • disallowedTools are valid tool names
  • effort is one of: low, medium, high, xhigh, max
  • maxTurns is a positive integer
  • skills is a list of skill names (references existing skills)
  • memory is one of: user, project, local
  • background and omitClaudeMd are boolean
  • isolation is worktree
  • autoCompactWindow is an integer from 100000 to 1000000
  • experimental holds only cacheTtl: 5m | 1h
  • model is valid: sonnet, opus, haiku, fable, inherit, sonnet[1m], opus[1m], or a full model ID

Plugin-Ignored / Unknown Fields (WARN, do not silently accept)

  • Warn on hooks, mcpServers, permissionMode, initialPrompt — ignored for plugin subagents
  • Flag any other field outside the official list (for example forkContext): Claude Code ignores it silently

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) — Director Mode / CI house rule
  • 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 list
  • Add missing color field (default: cyan)
  • Add missing model field (default: inherit)
  • Remove plugin-ignored fields (hooks, mcpServers, permissionMode, initialPrompt) or flag for review
  • Remove forkContext and other unknown fields
  • Replace default, best, or opusplan model values with a supported value
  • Remove invalid tools
  • Add recommended sections
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall