skill-frontmatter

Deprecated

Deprecated since v0.18.0 and will be removed in a future release. This rule no longer runs under enabled: auto; set enabled: true explicitly to keep it during the transition.

Superseded by agentskill-valid, which validates the same name and description frontmatter against the agentskills.io specification and carries the same missing-frontmatter autofix — running both reported every problem twice.

Use agentskill-valid instead.

SKILL.md files should have frontmatter with name and description

Severity	warning (deprecated)
Autofix	auto
Since	v0.1.0
Category	Deprecated

Why

A skill's YAML frontmatter is its public interface: the name and description fields are what an agent reads when deciding whether to load the skill. A SKILL.md without frontmatter — or without those two fields — is invisible to skill discovery, so the content below it never gets used no matter how good it is.

Examples

Bad:

# My deployment skill

Use this when deploying to staging...

Good:

---
name: deploy-staging
description: Deploy the application to the staging environment. Use when
  the user asks to deploy, ship, or release to staging.
---

# My deployment skill
...

How to fix

Add a frontmatter block with name (lowercase, hyphenated, matching the skill's directory name) and description (third person, stating both what the skill does and when to use it). Related rules validate the details: agentskill-name checks the name format and agentskill-description checks description quality.

Configuration

rules:
  skill-frontmatter:
    enabled: true  # true | false | auto
    severity: warning

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