agentskill-valid

SKILL.md must have valid frontmatter with name and description

Severity	error (auto)
Autofix	auto
Since	v0.1.0
Repo Types	agentskills, dot-claude, marketplace, single-plugin
Category	agentskills.io

Why

A SKILL.md file is the entry point for skill discovery. Without valid YAML frontmatter containing name and description, the skill cannot be found or loaded by the host application — the body content is effectively dead.

Examples

Bad:

Deploy the application to staging.

Good:

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

Deploy the application to staging.

How to fix

Add a YAML frontmatter block between --- delimiters at the top of SKILL.md with at least name and description fields. If the frontmatter exists but is malformed, fix the YAML syntax errors reported in the violation message. skillsaw fix can add missing fields automatically.

Configuration

rules:
  agentskill-valid:
    enabled: auto  # true | false | auto
    severity: error

Parameter	Description	Default
required-fields	Additional frontmatter fields to require (name and description are always required)	[]
required-metadata	Keys that must be present inside the metadata mapping	[]

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