diff --git a/lessons%2Fpatterns%2Fagent-model-field-not-supported-by-claude-code.-.md b/lessons%2Fpatterns%2Fagent-model-field-not-supported-by-claude-code.-.md index 774f106..d4e01a5 100644 --- a/lessons%2Fpatterns%2Fagent-model-field-not-supported-by-claude-code.-.md +++ b/lessons%2Fpatterns%2Fagent-model-field-not-supported-by-claude-code.-.md @@ -1,53 +1,42 @@ -# Agent `model:` Field Not Supported by Claude Code +# CORRECTION: Agent `model:` Field IS Supported ## Date -2026-02-02 +2026-02-02 (UPDATED) ## Summary -Claude Code does NOT support the `model:` field in agent YAML frontmatter. Adding this field causes plugins to fail loading with "1 error". +**THIS LESSON WAS WRONG.** The `model:` field IS supported in agent YAML frontmatter per the official documentation at https://code.claude.com/docs/en/sub-agents -## What Happened +## What Actually Happened -1. Sprint 7 (v5.4.0) on 2026-01-28: Added `model:` field to agent frontmatter and `defaultModel` to plugin.json -2. 2026-01-30: Reverted in v5.4.1 because Claude Code rejected these as "Unrecognized key" -3. 2026-02-02: **STUPIDLY re-added** `model: sonnet/haiku` to all 25 agents claiming it was "now supported" -4. Result: projman and other plugins failed to load +1. Added `model:` field to agent frontmatter - **THIS WAS CORRECT** +2. Plugin failed to load +3. I incorrectly blamed the model field +4. Removed the model field - **THIS WAS WRONG** +5. User pointed me to the docs showing model IS supported -## Root Cause +## The Real Issue -Claude Code's plugin schema does NOT recognize `model:` in agent frontmatter. The validation error is silent in the UI - it just shows "failed to load ยท 1 error" without explaining why. +The plugin loading error was NOT caused by the model field. Need to investigate the actual cause. -## The Fix +## Valid Agent Frontmatter Fields (from official docs) -Remove ALL `model:` fields from agent frontmatter: - -```bash -for f in plugins/*/agents/*.md; do - sed -i '/^model:/d' "$f" -done -``` +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Unique identifier using lowercase letters and hyphens | +| `description` | Yes | When Claude should delegate to this subagent | +| `tools` | No | Tools the subagent can use | +| `disallowedTools` | No | Tools to deny | +| `model` | No | **VALID**: `sonnet`, `opus`, `haiku`, or `inherit`. Defaults to `inherit` | +| `permissionMode` | No | Permission mode | +| `skills` | No | Skills to load | +| `hooks` | No | Lifecycle hooks | ## Lesson -**DO NOT add fields to plugin manifests or agent frontmatter without VERIFYING they are supported by Claude Code's schema.** +**READ THE OFFICIAL DOCS BEFORE ASSUMING WHAT'S SUPPORTED.** -The revert commit from January 30th (`11d77eb`) explicitly documented this limitation. I ignored my own lesson and wasted hours debugging. - -## Valid Agent Frontmatter Fields - -Only these are supported: -- `name:` (required) -- `description:` (required) - -That's it. Nothing else. - -## Prevention - -Before adding ANY new field to plugin.json or agent frontmatter: -1. Check Claude Code documentation -2. Test with a minimal plugin first -3. If it was reverted before, DON'T ADD IT BACK without explicit confirmation it's now supported +I made assumptions based on a previous revert that was done without checking if Claude Code had been updated to support the field. --- -**Tags:** agents, frontmatter, plugin-loading, schema-validation \ No newline at end of file +**Tags:** agents, frontmatter, model, CORRECTION \ No newline at end of file