---
title: "Doctor: Agents Validation"
description: "OrchestKit includes 30 specialized agents validated against CC 2.1.69 frontmatter format."
canonical: "https://orchestkit.dev/docs/reference/skills/doctor/references/agents-validation"
---

# Doctor: Agents Validation

OrchestKit includes 30 specialized agents validated against CC 2.1.69 frontmatter format.

> Part of the [Doctor](/docs/reference/skills/doctor) skill reference. The main page carries the skill itself; this page holds material that used to sit at the bottom of it.

## Overview

OrchestKit includes 30 specialized agents validated against CC 2.1.69 frontmatter format.

## Agent Structure

```
src/agents/
├── backend-system-architect.md
├── code-quality-reviewer.md
├── frontend-ui-developer.md
└── ... (38 total)
```

## Validation Checks

### 1. Frontmatter Fields

Required fields:
- `name` - Agent identifier (used in Task subagent_type)
- `description` - Purpose and auto-mode keywords
- `model` - opus, sonnet, or haiku
- `tools` - Array of allowed CC tools
- `skills` - Array of skill names to auto-inject

Optional fields:
- `context` - fork or inherit
- `color` - Display color
- `hooks` - Agent-specific hooks

### 2. Model Validation

Only valid models:

```bash
# Check model values
grep "^model:" src/agents/*.md | sort | uniq -c
```

Expected: opus, sonnet, haiku

### 3. Skills References

All skills in agent frontmatter must exist:

```bash
# Check skill references
for agent in src/agents/*.md; do
  grep -A100 "^skills:" "$agent" | grep "^  - " | \
    sed 's/.*- //' | while read skill; do
      [ -d "src/skills/$skill" ] || echo "Missing: $agent -> $skill"
    done
done
```

### 4. Tools Validation

Valid CC tools:
- Bash, Read, Write, Edit, MultiEdit
- Grep, Glob
- Task, Skill
- WebFetch, WebSearch
- NotebookEdit
- AskUserQuestion
- TaskCreate, TaskUpdate, TaskGet, TaskList, TodoWrite (CC 2.1.268 offers these tools only on Claude 3.x, Opus 4.0 to 4.7, Sonnet 4.0 to 4.6, and Haiku 4.5. On models outside this allowlist, these tools are absent unless the operator sets `CLAUDE_CODE_ENABLE_TODO_TOOLS=1`. CC honours the flag only from user or managed settings (or the shell); plugin settings cannot set it, so an agent granting these tools may run without them.)

## Quick Validation

```bash
# Run full agent validation
npm run test:agents

# Or directly
./tests/agents/test-agent-frontmatter.sh
```

## Common Issues

### Invalid model

```yaml
model: sonnet  # Valid: opus, sonnet, haiku
```

### Missing skill reference

Ensure skill exists in `src/skills/` directory.

### Invalid tool name

Check tool spelling matches CC tool names exactly.

## Agent Registration Check (CC 2.1.50+)

Run `claude agents` to list all registered agents and compare against the expected count from manifests.

**Gate:** Only run if CC >= 2.1.50 (feature: `claude_agents_cli`). Skip with a note if version is older.

```bash
# Check registered agent count matches expected
expected_count=$(grep -c '"agents/' manifests/ork.json 2>/dev/null || echo 0)
registered_count=$(claude agents 2>/dev/null | wc -l | tr -d ' ')

if [ "$registered_count" -ne "$expected_count" ]; then
  echo "WARN: Agent count mismatch — expected $expected_count, got $registered_count"
  # List missing agents for investigation
  claude agents 2>/dev/null | sort > /tmp/ork-registered.txt
  ls src/agents/*.md 2>/dev/null | xargs -I{} basename {} .md | sort > /tmp/ork-expected.txt
  echo "Missing agents:"
  comm -23 /tmp/ork-expected.txt /tmp/ork-registered.txt
fi
```

**Check:** `claude agents | wc -l` should match expected agent count (38).

## Model Routing

`docs/model-routing.md` was deleted in #1302; do not look for it. The per-agent assignment is the `model:` field in each `src/agents/*.md` frontmatter (values from `src/hooks/src/lib/models.vocab.json` `shortNames`), pinned in #3872 after CC 2.1.257 made `inherit` resolve to the premium tier. The rationale and the before/after per agent are in the Lab page `docs/chore--agent-routing-2026-09-01/index.html` (published at `/lab/agent-routing-2026-09-01.html`). To list the live assignment:

```bash
grep -h '^model:' src/agents/*.md | sort | uniq -c
```

**Fail action:** List missing agents for manual investigation. Common causes:
- Plugin not installed or not rebuilt after adding agents
- Agent frontmatter parse error preventing registration
- CC version too old (< 2.1.50) to support `claude agents` CLI