claude-agent-frontmatter

Agent files need valid frontmatter and description; project agents also need name

Formerly known as agent-frontmatter. The legacy name still works in configs, --rule/--skip-rule, suppression comments, and baselines.

Severity	error
Autofix	auto
Since	v0.1.0
Category	Claude Code

Why

Project agent .md files need YAML frontmatter with name and description so Claude Code can discover and register them. Plugin agents can omit name: Claude Code uses the filename stem under the plugin's namespace. The same fallback applies to empty or null names.

This rule still checks plugin agents for valid YAML frontmatter and a description so their instructions and routing metadata can be reviewed. See Claude's agent loading rules for the distinction between project and plugin agents.

Examples

Bad:

# Code reviewer

Review pull requests for correctness and style...

Good:

---
name: code-reviewer
description: Review pull requests for correctness and style issues.
  Use when the user asks to review a PR or diff.
---

# Code reviewer

Review pull requests for correctness and style...

How to fix

Add a YAML frontmatter block with description, stating what the agent does and when to invoke it. Project and APM agent files also require name; plugin agents may use the filename instead. skillsaw fix can add missing fields. When frontmatter already exists, the fix preserves a plugin agent's filename fallback.

Configuration

rules:
  claude-agent-frontmatter:
    enabled: true  # true | false | auto
    severity: error

Run skillsaw explain claude-agent-frontmatter to see this documentation and the rule's effective configuration in your terminal.