agent checklist Shipped
What this lens looks for
Read a Claude Code agent against three lenses. Structure and format: file opens and closes with --- YAML frontmatter; name field present, lowercase kebab-case, matching ^[a-z][a-z0-9-]{0,63}$ and ≤64 chars; description field present, written with natural trigger keywords a user would actually say (neither too vague nor too narrow); agent lives in .claude/agents/ or ~/.claude/agents/; only recognized frontmatter fields appear (name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation); filename is lowercase kebab-case ^[a-z][a-z0-9-]*\.md$ (UPPERCASE stems reserved for identity files like SKILL.md and CLAUDE.md). Content quality: single responsibility, one clear purpose rather than a grab-bag; error handling addressed in the system prompt (tool failures, missing files, bad input); instructions concrete and actionable; no self-contradiction; well-structured markdown with headings/lists/code blocks rather than an unstructured wall. Best practices: a verification method for confirming success; does not replicate native Claude capabilities; includes examples or usage patterns; no kitchen-sink anti-pattern (stays focused, doesn't try to do everything); no infinite-exploration anti-pattern (scopes investigation, doesn't read unbounded files); not a CLAUDE.md dump of project rules; model: override matches the agent's complexity; description concise (under ~200 chars) for the context budget. Agent-specific: both name and description present; tool access restricted via tools or disallowedTools for specialized agents; model specified where it benefits the task; system prompt gives a clear, focused role and scope; permissionMode set appropriately (plan for read-only, bypassPermissions for fully automated); maxTurns set for bounded tasks; skills preloads needed domain knowledge; memory scope correct for knowledge-accumulating agents.
What its verifier checks
Frontmatter opens and closes with ---; name present and matching ^[a-z][a-z0-9-]{0,63}$; description present using natural trigger phrasing; agent file located in .claude/agents/ or ~/.claude/agents/; only recognized frontmatter fields used; filename is lowercase kebab-case (no reserved UPPERCASE stem); the agent has a single clear responsibility; error handling for failures/missing-files/bad-input is addressed; instructions are concrete and actionable; no conflicting instructions; markdown is well-structured; a verification method is provided; native Claude capabilities are not re-taught; examples or usage patterns are present; no kitchen-sink scope and no unbounded exploration; content is not a CLAUDE.md dump; any model: override fits the complexity; description is under ~200 chars; both name and description are present; tool access is restricted for specialized agents; model is set where beneficial; the system prompt is clear and focused; permissionMode matches read-only vs automated use; maxTurns is set for bounded tasks; skills preloads needed knowledge; memory scope is appropriate.