claude-world/director-mode-lite / skills/agent-check
agent-check
VerifiedValidate 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
-
nameexists (lowercase, hyphenated; official limit 256 chars, no:, no leading-) -
descriptionexists (10-5000 chars, recommend 200-1000 with<example>blocks) -
coloris set (valid color name) — required by Director Mode convention, optional per spec -
modelis set (valid value below) — required by Director Mode convention, optional per spec
Optional Fields (official)
-
toolsare valid tool names, YAML list format (omit = all tools available) -
disallowedToolsare valid tool names -
effortis one of: low, medium, high, xhigh, max -
maxTurnsis a positive integer -
skillsis a list of skill names (references existing skills) -
memoryis one of: user, project, local -
backgroundandomitClaudeMdare boolean -
isolationisworktree -
autoCompactWindowis an integer from 100000 to 1000000 -
experimentalholds onlycacheTtl: 5m | 1h -
modelis 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 Nameheading -
## Activationsection - Process/workflow description
- Output format definition
Format Rules
-
toolsuses 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
skillsto YAML list - Add missing
colorfield (default: cyan) - Add missing
modelfield (default: inherit) - Remove plugin-ignored fields (
hooks,mcpServers,permissionMode,initialPrompt) or flag for review - Remove
forkContextand other unknown fields - Replace
default,best, oropusplanmodel values with a supported value - Remove invalid tools
- Add recommended sections
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 469k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |