CLI Tooling (agentskills-tools)

Scaffold, validate, lint, inspect, evaluate, and serve skills.

pip install agentskills-tools

agentskills_tools

Command line tools for authoring and validating Agent Skills.

The console script is agentskills. Every command is also reachable in-process through :func:~agentskills_tools.cli.main, which takes an argument list and returns an exit code rather than calling :func:sys.exit — that is what makes it testable.

CliError

Bases: Exception

A problem with the invocation itself, not with a skill.

Raised for a missing path or an empty directory — conditions that mean the command could not run, as opposed to running and finding fault with a skill.

Finding dataclass

A single problem found in a skill.

Attributes:

Name	Type	Description
severity	str	Either "error" or "warning".
code	str	Stable machine-readable identifier, e.g. "frontmatter-invalid-yaml". Callers may key off this; message is free to be reworded.
message	str	Human-readable explanation.
line	int | None	1-based line in the file the finding is about, when the problem can be attributed to one. None otherwise.
file	str | None	Path the finding is about, relative to the working directory, when it is not the skill's SKILL.md.

SkillLocation dataclass

One skill directory and the ID it will be registered under.

SkillReport dataclass

Every finding for one skill.

errors property

errors: list[Finding]

Findings with error severity.

ok property

ok: bool

True when the skill produced no error-severity findings.

warnings property

warnings: list[Finding]

Findings with warning severity.

discover

discover(target: Path) -> tuple[Path, list[SkillLocation]]

Resolve target into a provider root and the skills beneath it.

A directory containing SKILL.md is a single skill, and its parent becomes the provider root because :class:~agentskills_fs.LocalFileSystemSkillProvider addresses skills by directory name below a root. Any other directory is treated as a collection, and each immediate subdirectory holding a SKILL.md is one skill.

Parameters:

Name	Type	Description	Default
target	Path	Path to a skill folder or a folder of skill folders.	required

Returns:

Type	Description
Path	A (root, locations) tuple. locations is sorted by skill
list[SkillLocation]	ID and is never empty.

Raises:

Type	Description
CliError	If target is not a directory, or is a directory with no skills in it.

main

main(argv: list[str] | None = None, out: TextIO | None = None) -> int

Run the agentskills command line.

Parameters:

Name	Type	Description	Default
argv	list[str] | None	Arguments to parse. Defaults to sys.argv[1:].	None
out	TextIO | None	Stream to write reports to. Defaults to stdout.	None

Returns:

Type	Description
int	A process exit code.