Documentation
¶
Overview ¶
Package skills loads and validates Agent Skills from disk.
Agent Skills is an open standard for packaging procedural knowledge as a directory containing a SKILL.md with YAML frontmatter. The spec is published at https://agentskills.io/specification.
Two read entry points:
- Load(dir): load one skill from its directory. Returns ErrNoSkillFile if the directory does not contain a SKILL.md so that callers walking heterogeneous directories can decide whether that is a hard failure or a soft skip.
- LoadAll(root): load every skill under root by iterating over immediate subdirectories that contain a SKILL.md and calling Load on each, reporting the ones that cannot be loaded. Subdirectories without any SKILL.md are not skills and are ignored. Missing root → (nil, nil, nil).
Validation is a separate step on already loaded skills: Validate for one skill, ValidateAll for many.
Index ¶
- Constants
- Variables
- func FindSkillFile(dir string) (name string, exact bool, err error)
- func WarningLines(findings map[string]Findings) []string
- func WithSkipped(found map[string]Findings, skipped map[string]string) map[string]Findings
- type Findings
- type Meta
- type Option
- type Problem
- type Severity
- type Skill
- type Validator
Constants ¶
const SkillFile = "SKILL.md"
SkillFile is the canonical filename inside an Agent Skills directory. The Agent Skills specification mandates this exact name.
Variables ¶
var ErrNoSkillFile = errors.New("SKILL.md not found")
ErrNoSkillFile is returned by Load when the directory exists but does not contain a SKILL.md. Use errors.Is to detect it.
var ErrSkillFileCase = errors.New("SKILL.md has the wrong case")
ErrSkillFileCase is returned by Load when the directory has a file whose name matches SKILL.md only when case is ignored, such as skill.md. The specification requires the exact name, and case-insensitive file systems would otherwise hide the defect until the skill is used elsewhere.
Functions ¶
func FindSkillFile ¶
FindSkillFile looks in dir for the skill file by listing the directory, so that the answer does not depend on the case sensitivity of the file system. It returns the name of the file with the exact name SKILL.md, or else of a file that differs from it only in case, or else "". exact tells which one.
func WarningLines ¶
WarningLines flattens findings into one "<skill>: <text>" line per problem, ordered by skill name and then by discovery. A skipped skill's texts carry a "skipped: " prefix.
Types ¶
type Findings ¶
type Findings struct {
Problems []Problem // Bounded by the Validator's max problems, if set
Skipped bool // The skill could not be loaded
}
Findings are the problems found in one skill.
type Meta ¶
type Meta struct {
// Name (required). Max 64 chars, lowercase letters/digits/hyphens
// only, must not start or end with `-` or contain `--`, and must
// equal the parent directory's name.
Name string `yaml:"name"`
// Description (required). Max 1024 chars, non-empty.
Description string `yaml:"description"`
// License (optional).
License string `yaml:"license,omitempty"`
// Compatibility (optional). Max 500 chars.
Compatibility string `yaml:"compatibility,omitempty"`
// Metadata (optional). String-to-string map.
Metadata map[string]string `yaml:"metadata,omitempty"`
// AllowedTools (optional, experimental). Space-separated list.
AllowedTools string `yaml:"allowed-tools,omitempty"`
}
Meta is the SKILL.md YAML frontmatter as defined by the Agent Skills specification. See https://agentskills.io/specification for authoritative field definitions and constraints. Unknown keys are ignored on read; Validate reports them from Skill.Fields.
type Option ¶
type Option func(*Validator)
Option configures a Validator.
func WithMaxProblems ¶
WithMaxProblems keeps at most n problems per skill. When there are more, the last of the n entries counts the dropped ones ("... and N more problems"). A value of zero or less means unlimited, which is the default.
func WithStrict ¶
func WithStrict() Option
WithStrict reports every warning as an error, so that a skill with harness-specific frontmatter fields no longer passes. Use it for skills that must stay portable, such as those uploaded to claude.ai.
type Problem ¶
type Problem struct {
Severity Severity
Details string // Human-readable text; does not repeat the skill name
}
Problem is one finding about a skill. Fields may be added in later versions, so build values with keyed literals.
type Severity ¶
type Severity int
Severity ranks how serious a problem is. The zero value is SeverityError.
type Skill ¶
type Skill struct {
Dir string // Absolute path to the skill's directory.
Meta Meta // Parsed SKILL.md frontmatter.
Fields map[string]any // Raw SKILL.md frontmatter, for type and unknown-key checks.
BodyLines int // Lines of SKILL.md after the frontmatter.
}
Skill is one loaded agent skill.
func Load ¶
Load reads the skill rooted at dir.
Parses dir/SKILL.md and returns the resulting *Skill. Returns ErrNoSkillFile (wrapped, detect via errors.Is) when SKILL.md is missing and ErrSkillFileCase when only a differently cased name such as skill.md exists; any other I/O error or YAML parse error is returned wrapped.
Load does not validate spec rules beyond YAML well-formedness. Use Validate for that.
func LoadAll ¶
LoadAll walks root and returns one *Skill per immediate subdirectory that contains a loadable SKILL.md.
A subdirectory with a SKILL.md that cannot be loaded (unparsable frontmatter, or a wrongly cased file name such as skill.md) is not loaded; skipped maps its name to the reason, so one broken skill never hides the others. A subdirectory without any SKILL.md is not a skill and is ignored. Only an I/O failure on root itself is an error.
If root itself does not exist, LoadAll returns (nil, nil, nil).
Entries are followed through symlinks: a symlink pointing at a skill directory is treated as that directory.
Result order matches os.ReadDir (lexicographic).
type Validator ¶
type Validator struct {
// contains filtered or unexported fields
}
Validator checks skills against the Agent Skills specification. Create one with NewValidator; it is safe for concurrent use.
func NewValidator ¶
NewValidator returns a Validator with the given options applied.
func (*Validator) Validate ¶
Validate checks a loaded skill against the Agent Skills specification and the self-contained layout rule: every file a skill references must live inside the skill directory, because only that directory is installed.
The returned details do not repeat the skill name. The error is reserved for I/O failures.