skills

package
v0.0.0-...-a5e03af Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

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

View Source
const SkillFile = "SKILL.md"

SkillFile is the canonical filename inside an Agent Skills directory. The Agent Skills specification mandates this exact name.

Variables

View Source
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.

View Source
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

func FindSkillFile(dir string) (name string, exact bool, err error)

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

func WarningLines(findings map[string]Findings) []string

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.

func WithSkipped

func WithSkipped(found map[string]Findings, skipped map[string]string) map[string]Findings

WithSkipped adds a skipped entry carrying the reason for every directory LoadAll did not load. It returns a new map and leaves found untouched.

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

func WithMaxProblems(n int) Option

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.

func (Problem) String

func (p Problem) String() string

String returns Details.

type Severity

type Severity int

Severity ranks how serious a problem is. The zero value is SeverityError.

const (
	SeverityError   Severity = iota // The skill violates the specification
	SeverityWarning                 // Worth fixing, but does not break the skill
)

func (Severity) String

func (s Severity) String() string

String returns "error" or "warning".

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

func Load(dir string) (*Skill, error)

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

func LoadAll(root string) (loaded []*Skill, skipped map[string]string, err error)

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).

func (*Skill) Name

func (s *Skill) Name() string

Name returns the skill's directory basename.

The Agent Skills spec requires this to equal Meta.Name; callers that want the on-disk identifier should prefer this method.

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

func NewValidator(opts ...Option) *Validator

NewValidator returns a Validator with the given options applied.

func (*Validator) Validate

func (v *Validator) Validate(s *Skill) ([]Problem, error)

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.

func (*Validator) ValidateAll

func (v *Validator) ValidateAll(loaded []*Skill) (map[string]Findings, error)

ValidateAll runs Validate on every skill and returns the findings by skill directory name. A skill without findings has no entry.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址