agent_skills/lib.rs
1//! Parse, validate, and work with Agent Skills.
2//!
3//! This crate provides types and functions for working with Agent Skills
4//! as defined by the [Agent Skills specification](https://agentskills.io).
5//!
6//! # Overview
7//!
8//! Agent Skills are directories containing a `SKILL.md` file with YAML frontmatter
9//! and markdown instructions. This crate handles:
10//!
11//! - Parsing `SKILL.md` files (frontmatter + markdown body)
12//! - Validating skills against the specification
13//! - Loading skills from directories
14//! - Accessing skill metadata, instructions, and referenced files
15//!
16//! # Quick Start
17//!
18//! ## Parsing a SKILL.md file
19//!
20//! ```
21//! use agent_skills::Skill;
22//!
23//! let content = r#"---
24//! name: my-skill
25//! description: Does something useful.
26//! ---
27//! # Instructions
28//!
29//! Follow these steps...
30//! "#;
31//!
32//! let skill = Skill::parse(content).unwrap();
33//! assert_eq!(skill.name().as_str(), "my-skill");
34//! assert!(skill.body().contains("# Instructions"));
35//! ```
36//!
37//! ## Loading a skill from a directory
38//!
39//! ```no_run
40//! use agent_skills::SkillDirectory;
41//! use std::path::Path;
42//!
43//! let dir = SkillDirectory::load(Path::new("./my-skill")).unwrap();
44//! println!("Loaded skill: {}", dir.skill().name());
45//!
46//! // Access optional directories
47//! if dir.has_scripts() {
48//! for script in dir.scripts().unwrap() {
49//! println!("Script: {}", script.display());
50//! }
51//! }
52//! ```
53//!
54//! ## Creating skills programmatically
55//!
56//! ```
57//! use agent_skills::{Skill, Frontmatter, SkillName, SkillDescription, Metadata};
58//!
59//! let name = SkillName::new("my-skill").unwrap();
60//! let desc = SkillDescription::new("Does something useful.").unwrap();
61//!
62//! let frontmatter = Frontmatter::builder(name, desc)
63//! .license("MIT")
64//! .metadata(Metadata::from_pairs([("author", "example")]))
65//! .build();
66//!
67//! let skill = Skill::new(frontmatter, "# Instructions\n\nDo this.");
68//! ```
69//!
70//! # Types
71//!
72//! - [`Skill`] - A complete skill with frontmatter and body
73//! - [`Frontmatter`] - The YAML frontmatter header
74//! - [`SkillName`] - A validated skill name
75//! - [`SkillDescription`] - A validated skill description
76//! - [`Compatibility`] - Environment compatibility requirements
77//! - [`Metadata`] - Arbitrary key-value metadata
78//! - [`AllowedTools`] - Pre-approved tool list (experimental)
79//! - [`SkillDirectory`] - A loaded skill directory with file access
80//!
81//! # Errors
82//!
83//! - [`ParseError`] - Errors when parsing SKILL.md content
84//! - [`LoadError`] - Errors when loading skill directories
85//! - [`SkillNameError`] - Invalid skill name
86//! - [`SkillDescriptionError`] - Invalid skill description
87//! - [`CompatibilityError`] - Invalid compatibility string
88
89mod allowed_tools;
90mod compatibility;
91mod description;
92mod error;
93mod frontmatter;
94mod loader;
95mod metadata;
96mod name;
97mod skill;
98
99// Re-export main types
100pub use allowed_tools::AllowedTools;
101pub use compatibility::{Compatibility, CompatibilityError};
102pub use description::{SkillDescription, SkillDescriptionError};
103pub use error::{LoadError, ParseError};
104pub use frontmatter::{Frontmatter, FrontmatterBuilder};
105pub use loader::SkillDirectory;
106pub use metadata::Metadata;
107pub use name::{SkillName, SkillNameError};
108pub use skill::Skill;