claude-agent-frontmatter

Agent files must have valid frontmatter with name and description

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

Agent .md files need YAML frontmatter with name and description so that the host application can discover and register them. Without frontmatter, the agent file is invisible to the runtime — its instructions will never be loaded.

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 name (matching the filename stem) and description (imperative, stating what the agent does and when to invoke it). skillsaw fix can add missing frontmatter fields automatically.

Codex plugins

This is a Claude-format convention. A directory claimed only by OpenAI Codex — a .codex-plugin/plugin.json, or a local-source listing in a Codex catalog, with no .claude-plugin marker or Claude marketplace listing — is exempt: Claude never loads it, so Claude agent frontmatter requirements do not apply to its agents/. A dual-manifest directory keeps this check, and the ecosystem-neutral content and security rules read every plugin's files regardless of provenance.

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.