fix(agents): fix YAML frontmatter in 14 agent definitions + validation script#1795
fix(agents): fix YAML frontmatter in 14 agent definitions + validation script#1795nick-inkeep merged 2 commits intomainfrom
Conversation
…ation 14 of 18 agent files had broken YAML frontmatter that silently prevented Claude Code from discovering them at runtime. The agents existed on disk but Claude Code's YAML parser failed on them, reporting "Agent type not found" with no further diagnostic. Root cause: <example> and <commentary> blocks inside `description: |` block scalars were at column 0 instead of indented by 2+ spaces. YAML treats unindented lines as the end of the block scalar, then fails to parse the remaining content as valid YAML keys. Fixed agents (12 pr-review + 1 git-rebase-coordinator + 1 pr-review-docs): - pr-review-architecture, pr-review-breaking-changes, pr-review-comments - pr-review-consistency, pr-review-devops, pr-review-docs - pr-review-errors, pr-review-frontend, pr-review-product - pr-review-security-iam, pr-review-standards, pr-review-tests - pr-review-types, git-rebase-coordinator Already valid (no changes): pr-review, pr-review-llm, pr-review-sre, code-simplifier Added: - scripts/validate-agents.sh: validates YAML frontmatter for all agent files, checks required name/description fields, warns on name/filename mismatch - lint-staged hook: runs validate-agents.sh when .claude/agents/*.md files are committed Co-authored-by: Cursor <cursoragent@cursor.com>
- Replace scripts/validate-agents.sh (Python/bash) with scripts/validate-ai-artifacts.ts (TypeScript using yaml package) - Validates both agent files (.claude/agents/*.md) and skill files (.agents/skills/**/SKILL.md, .claude/skills/**/SKILL.md, etc.) - Checks: YAML parse, required name+description, name/filename match - Added yaml as root devDep, pnpm validate:ai-artifacts script - lint-staged hooks for both .claude/agents/*.md and .agents/skills/**/SKILL.md Co-authored-by: Cursor <cursoragent@cursor.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
PR Review Summary
1 Key Finding | Risk: Low
This PR correctly addresses a critical bug where 14 agent definitions had broken YAML frontmatter that silently prevented Claude Code from discovering them at runtime. The fix (indenting <example> blocks by 2 spaces inside description: | block scalars) is the correct solution.
🟡 Minor (1) 🟡
🟡 1) package.json:40 Script naming convention inconsistency
Issue: The new npm script uses validate:ai-artifacts while the established pattern for validation scripts is check:* (e.g., check:env-descriptions, check:husky, check:prepush).
Why: Inconsistent naming makes script discovery harder. Developers familiar with pnpm check:* may not find pnpm validate:*.
Fix: Rename to check:ai-artifacts to match the established convention.
Refs: package.json:81 shows the existing pattern
📌 Inline Comments (1)
- 🟡
package.json:40Script naming inconsistency with suggested fix
✅ APPROVE
Summary: The core fix is correct and well-executed. The validation script is reasonable quality for a developer tool. All 14 agent files now have properly indented frontmatter that will parse correctly. The one minor suggestion (script naming) is non-blocking and can be addressed at your discretion. Nice work catching this silent failure mode and adding automated validation to prevent recurrence! 🎉
Other Findings (6)
Potentially valid
(these are minor or info critically and not confident)
| Location | Issue | Reason Excluded |
|---|---|---|
scripts/validate-ai-artifacts.ts |
No unit tests for validation script | Existing scripts in scripts/*.mjs also lack tests; manual testing confirmed; developer tooling with low risk |
package.json:106-111 |
lint-staged runs full validation on single file change | Currently 66 files is fast enough; optimization is a follow-up |
scripts/validate-ai-artifacts.ts:73-77 |
Doesn't check for <example> blocks in descriptions |
Nice-to-have validation; not blocking |
.claude/agents/git-rebase-coordinator.md |
Uses single-line format unlike other fixed files | YAML is valid; formatting preference |
Discarded as invalid or not applicable
| Location | Issue | Reason Excluded |
|---|---|---|
package.json:109 |
lint-staged only hooks .agents/skills, not .claude/skills |
Works correctly via symlinks |
scripts/validate-ai-artifacts.ts |
yaml package is new dependency |
Correctly scoped as devDependency, ISC licensed |
Reviewer Stats
| Reviewer | Returned | Inline Comments | Main Findings | Pending Recs | Other Findings |
|---|---|---|---|---|---|
pr-review-tests |
5 | 0 | 0 | 0 | 1 |
pr-review-devops |
5 | 0 | 0 | 0 | 3 |
pr-review-consistency |
3 | 1 | 1 | 0 | 2 |
pr-review-standards |
0 | 0 | 0 | 0 | 0 |
| Total | 13 | 1 | 1 | 0 | 6 |
| "check:husky": "turbo check:husky --filter='!agents-cookbook-templates' --filter='!@inkeep/agents-docs'", | ||
| "check:prepush": "turbo check:prepush --filter='!agents-cookbook-templates' --filter='!@inkeep/agents-docs'", | ||
| "check:fix": "biome check --write", | ||
| "validate:ai-artifacts": "tsx scripts/validate-ai-artifacts.ts", |
There was a problem hiding this comment.
MINOR Script naming inconsistency
The new script uses validate: prefix while existing validation scripts use check:* (e.g., check:env-descriptions, check:husky, check:prepush). Consider aligning for discoverability.
package.json L81 shows the existing pattern.
| "validate:ai-artifacts": "tsx scripts/validate-ai-artifacts.ts", | |
| "check:ai-artifacts": "tsx scripts/validate-ai-artifacts.ts", |
|
No docs changes detected. This PR fixes internal YAML frontmatter in Claude agent definition files and adds a validation script for developer tooling. These changes don't affect user-facing documentation. |
1 participant
Summary
14 of 18 agent files had broken YAML frontmatter that silently prevented Claude Code from discovering them at runtime. Only
pr-review,pr-review-llm, andpr-review-srewere discoverable — all other reviewers silently failed to load, causing the orchestrator to fall back to a singlegeneral-purposeagent.Root Cause
<example>and<commentary>blocks insidedescription: |block scalars were at column 0 instead of indented by 2+ spaces. YAML treats unindented lines as the end of the block scalar, then fails to parse the remaining content. Claude Code reports "Agent type not found" with no diagnostic about the parse failure.This is a known issue with Claude Code's stricter YAML parsing in v2.1+ (anthropics/claude-code#11205).
Changes
Frontmatter fixes (14 files)
Indented all description block scalar content by 2 spaces:
pr-review-architecture,pr-review-breaking-changes,pr-review-commentspr-review-consistency,pr-review-devops,pr-review-docspr-review-errors,pr-review-frontend,pr-review-productpr-review-security-iam,pr-review-standards,pr-review-testspr-review-types,git-rebase-coordinatorAlready valid (no changes):
pr-review,pr-review-llm,pr-review-sre,code-simplifierValidation script (new)
scripts/validate-ai-artifacts.ts— TypeScript validation using theyamlpackage. Validates:.claude/agents/*.md): YAML parse, requiredname+description, name/filename match.agents/skills/**/SKILL.md,.claude/skills/**/SKILL.md,.cursor/skills/**/SKILL.md): YAML parse, requiredname+description, name/directory matchRun manually:
Runs automatically via lint-staged when agent or skill files are committed.
lint-staged integration
Added hooks in
package.jsonfor:.claude/agents/*.md— triggerspnpm validate:ai-artifacts.agents/skills/**/SKILL.md— triggerspnpm validate:ai-artifactsTest plan
pnpm validate:ai-artifactspasses for all 66 files (18 agents + 48 skills)retry-triggersonto main, verify all 15 reviewers are discovered in PR Retry triggers in trace ui #1789 reviewMade with Cursor