Skip to content

agent-frontmatter

Agent files must have valid frontmatter with name and description
Severity error
Autofix auto
Since v0.1.0
Category Skills, Agents, Hooks

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.

Configuration

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

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