Crate agent_skills 

Parse, validate, and work with Agent Skills.

This crate provides types and functions for working with Agent Skills as defined by the Agent Skills specification.

Overview

Agent Skills are directories containing a SKILL.md file with YAML frontmatter and markdown instructions. This crate handles:

• Parsing SKILL.md files (frontmatter + markdown body)
• Validating skills against the specification
• Loading skills from directories
• Accessing skill metadata, instructions, and referenced files

Quick Start

Parsing a SKILL.md file

use agent_skills::Skill;

let content = r#"---
name: my-skill
description: Does something useful.
---

Follow these steps...
"#;

let skill = Skill::parse(content).unwrap();
assert_eq!(skill.name().as_str(), "my-skill");
assert!(skill.body().contains("# Instructions"));

Loading a skill from a directory

use agent_skills::SkillDirectory;
use std::path::Path;

let dir = SkillDirectory::load(Path::new("./my-skill")).unwrap();
println!("Loaded skill: {}", dir.skill().name());

// Access optional directories
if dir.has_scripts() {
    for script in dir.scripts().unwrap() {
        println!("Script: {}", script.display());
    }
}

Creating skills programmatically

use agent_skills::{Skill, Frontmatter, SkillName, SkillDescription, Metadata};

let name = SkillName::new("my-skill").unwrap();
let desc = SkillDescription::new("Does something useful.").unwrap();

let frontmatter = Frontmatter::builder(name, desc)
    .license("MIT")
    .metadata(Metadata::from_pairs([("author", "example")]))
    .build();

let skill = Skill::new(frontmatter, "# Instructions\n\nDo this.");

Types

• Skill - A complete skill with frontmatter and body
• Frontmatter - The YAML frontmatter header
• SkillName - A validated skill name
• SkillDescription - A validated skill description
• Compatibility - Environment compatibility requirements
• Metadata - Arbitrary key-value metadata
• AllowedTools - Pre-approved tool list (experimental)
• SkillDirectory - A loaded skill directory with file access

Errors

• ParseError - Errors when parsing SKILL.md content
• LoadError - Errors when loading skill directories
• SkillNameError - Invalid skill name
• SkillDescriptionError - Invalid skill description
• CompatibilityError - Invalid compatibility string

Structs

AllowedTools

A space-delimited list of pre-approved tools.

Compatibility

An optional compatibility string describing environment requirements.

Frontmatter

The YAML frontmatter of a SKILL.md file.

FrontmatterBuilder

Builder for constructing Frontmatter with optional fields.

Metadata

Arbitrary key-value metadata for additional properties.

Skill

A complete Agent Skill, combining frontmatter and markdown body.

SkillDescription

A validated skill description.

SkillDirectory

A loaded skill directory containing the skill and its files.

SkillName

A validated skill name.

Enums

CompatibilityError

Error returned when a compatibility string is invalid.

LoadError

Error returned when loading a skill from a directory fails.

ParseError

Error returned when parsing a SKILL.md file fails.

SkillDescriptionError

Error returned when a skill description is invalid.

SkillNameError

Error returned when a skill name is invalid.