skillcheck

Documentation

Overview

Package skillcheck validates SKILL.md files against the agentskills.io Agent Skills specification (https://agentskills.io/specification).

Dockyard ships an agent-skill set under skills/ that teaches an AI coding agent how to build MCP Apps with Dockyard end to end (Phase 29, AGENTS.md §19). A malformed SKILL.md would silently break agent discovery, so the format is enforced mechanically: this package powers the drift-audit hook and the phase-29 smoke check, both of which fail CI when a SKILL.md does not conform.

The validator is read-only and pure: it parses the YAML frontmatter and the Markdown body, applies the spec's constraints (name shape, length limits, required-fields, body non-empty), and returns a typed Report. It does NOT load files outside the skill directory and does NOT execute any code referenced by the skill.

Validation rules implemented (spec sections cross-referenced):

• frontmatter: YAML, opens and closes with `---`, parses as a map.
• `name`: required; 1..64 chars; only lowercase a-z, 0-9 and `-`; no leading/trailing hyphen; no consecutive hyphens; matches the parent directory name (the "skill slug" invariant).
• `description`: required; 1..1024 chars; non-empty.
• `license`, `compatibility`, `metadata`, `allowed-tools`: optional; when present, validated for shape per the spec.
• body: non-empty Markdown content after the frontmatter — a SKILL.md with empty body is not a skill, it is a stub.

The cmd/skillcheck binary walks a directory and runs Validate over every skill it finds; drift-audit invokes it via `go run`.

Index

• func ValidateFile(path string) (*Skill, Report)
• type Issue
  • func (i Issue) String() string
• type Report
  • func Validate(root string) (Report, error)
  • func (r *Report) Ok() bool
• type Skill

Functions

func ValidateFile

func ValidateFile(path string) (*Skill, Report)

ValidateFile parses and validates a single SKILL.md path. It returns the parsed Skill (always non-nil so a caller can print partial diagnostics) and a Report carrying every spec violation found.

The skill's slug is derived from the parent directory's basename — the spec's `name` must match it.

Types

type Issue

type Issue struct {
	Path    string
	Field   string
	Message string
}

Issue is one spec violation. Path is the SKILL.md the violation belongs to (or the directory, for missing-file diagnostics); Field is the spec-named field; Message is the diagnostic.

func (Issue) String

func (i Issue) String() string

type Report

type Report struct {
	Skills []Skill
	// Issues lists every spec violation found. A clean report has Issues
	// empty. Each Issue carries the skill path so a caller can print
	// actionable diagnostics with no extra plumbing.
	Issues []Issue
}

Report is the validator's output: the parsed skills + the diagnostics.

func Validate

func Validate(root string) (Report, error)

Validate walks a directory tree and validates every SKILL.md file under it. Discovery is one level deep by spec convention — a skill is one directory containing a SKILL.md. The walk is recursive so nested collections (e.g. skills/category/<slug>/SKILL.md) work, but each found SKILL.md is validated against its own immediate parent directory.

Validate returns a combined Report and, separately, a wrapped error when the walk itself failed (a missing root, an unreadable directory). A skill-level violation populates Report.Issues; the error is nil.

func (*Report) Ok

func (r *Report) Ok() bool

Ok returns true when no issues were found.

type Skill

type Skill struct {
	// Dir is the absolute path of the skill directory (the one whose name
	// must equal the frontmatter `name`).
	Dir string
	// Path is the absolute path to the SKILL.md file itself.
	Path string
	// Slug is the directory's basename, the spec's required match against
	// the frontmatter `name`.
	Slug string

	Name          string
	Description   string
	License       string
	Compatibility string
	AllowedTools  string
	Metadata      map[string]string
	Body          string
}

Skill is one parsed SKILL.md file.