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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ValidateFile ¶
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 ¶
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.
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 ¶
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.
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
skillcheck
command
Command skillcheck validates a tree of Dockyard agent skills against the SKILL.md format (agentskills.io specification).
|
Command skillcheck validates a tree of Dockyard agent skills against the SKILL.md format (agentskills.io specification). |