personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update "lessons%2Fpatterns%2Fagent-model-field-not-supported-by-claude-code.-"

Leo Miranda
2026-02-03 03:52:40 +00:00
parent 76eabec238
commit 299f69a06b
1 changed files with 25 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
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
**Tags:** agents, frontmatter, model, CORRECTION