use std::collections::HashSet;
use std::path::{Path, PathBuf};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SkillSource {
Project,
User,
}
#[derive(Debug, Clone)]
pub struct Skill {
pub name: String,
pub description: String,
pub body: String,
pub dir: PathBuf,
pub source: SkillSource,
}
#[derive(Debug, Clone, Default)]
pub struct Skills {
pub skills: Vec<Skill>,
}
impl Skills {
pub fn empty() -> Self {
Self::default()
}
pub fn discover(cwd: &Path) -> Self {
let mut roots: Vec<(PathBuf, SkillSource)> =
vec![(cwd.join(".claude").join("skills"), SkillSource::Project)];
if let Some(home) = dirs::home_dir() {
roots.push((home.join(".claude").join("skills"), SkillSource::User));
}
Self::discover_from_roots(&roots)
}
pub fn discover_from_roots(roots: &[(PathBuf, SkillSource)]) -> Self {
let mut skills: Vec<Skill> = Vec::new();
let mut seen: HashSet<String> = HashSet::new();
for (root, source) in roots {
if !root.is_dir() {
continue;
}
let Ok(rd) = std::fs::read_dir(root) else {
continue;
};
let mut entries: Vec<PathBuf> = rd.filter_map(Result::ok).map(|e| e.path()).collect();
entries.sort();
for dir in entries {
if !dir.is_dir() {
continue;
}
let skill_md = dir.join("SKILL.md");
if !skill_md.is_file() {
continue;
}
let Some(skill) = parse_skill_file(&skill_md, &dir, *source) else {
continue;
};
if seen.insert(skill.name.clone()) {
skills.push(skill);
}
}
}
Skills { skills }
}
pub fn find(&self, name: &str) -> Option<&Skill> {
self.skills.iter().find(|s| s.name == name)
}
pub fn names(&self) -> Vec<&str> {
self.skills.iter().map(|s| s.name.as_str()).collect()
}
}
fn parse_skill_file(path: &Path, dir: &Path, source: SkillSource) -> Option<Skill> {
let raw = std::fs::read_to_string(path).ok()?;
let (fm, body) = split_frontmatter(&raw);
let parsed = fm.as_deref().map(parse_frontmatter);
let dir_name = dir.file_name()?.to_string_lossy().to_string();
let name = parsed
.as_ref()
.map(|p| p.name.clone())
.filter(|n| !n.is_empty())
.unwrap_or(dir_name);
let description = parsed
.as_ref()
.map(|p| p.description.clone())
.unwrap_or_default();
Some(Skill {
name,
description,
body,
dir: dir.to_path_buf(),
source,
})
}
#[derive(Debug, Default)]
struct ParsedFrontmatter {
name: String,
description: String,
}
fn split_frontmatter(raw: &str) -> (Option<String>, String) {
let raw = raw.strip_prefix('\u{feff}').unwrap_or(raw);
let lines: Vec<&str> = raw.split('\n').collect();
if lines.first().map(|l| l.trim() == "---").unwrap_or(false) {
if let Some(rel) = lines
.iter()
.skip(1)
.position(|l| l.trim() == "---" || l.trim() == "...")
{
let close = rel + 1;
let fm = lines[1..close].join("\n");
let body = lines
.get(close + 1..)
.map(|s| s.join("\n"))
.unwrap_or_default();
return (Some(fm), body);
}
}
(None, raw.to_string())
}
fn parse_frontmatter(fm: &str) -> ParsedFrontmatter {
let mut out = ParsedFrontmatter::default();
for line in fm.lines() {
if line.starts_with(' ') || line.starts_with('\t') {
continue;
}
if let Some((k, v)) = line.split_once(':') {
match k.trim() {
"name" => out.name = unquote(v.trim()),
"description" => out.description = unquote(v.trim()),
_ => {}
}
}
}
out
}
fn unquote(s: &str) -> String {
let s = s.trim();
if s.len() >= 2
&& ((s.starts_with('"') && s.ends_with('"'))
|| (s.starts_with('\'') && s.ends_with('\'')))
{
s[1..s.len() - 1].to_string()
} else {
s.to_string()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn write_skill(root: &Path, name: &str, body: &str) -> PathBuf {
let dir = root.join(name);
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join("SKILL.md"), body).unwrap();
dir
}
#[test]
fn parses_name_description_and_body() {
let md = "---\nname: my-skill\ndescription: Use when foo\n---\n# Steps\nDo the thing.\n";
let (fm, body) = split_frontmatter(md);
let p = parse_frontmatter(&fm.unwrap());
assert_eq!(p.name, "my-skill");
assert_eq!(p.description, "Use when foo");
assert!(body.contains("# Steps"));
assert!(body.contains("Do the thing."));
}
#[test]
fn ignores_unknown_frontmatter_keys_like_allowed_tools() {
let p = parse_frontmatter("name: a\ndescription: do a thing\nallowed-tools: [bash, read]\n");
assert_eq!(p.name, "a");
assert_eq!(p.description, "do a thing");
}
#[test]
fn strips_quotes_around_values() {
let p = parse_frontmatter("name: \"quoted-name\"\ndescription: 'single quoted'\n");
assert_eq!(p.name, "quoted-name");
assert_eq!(p.description, "single quoted");
}
#[test]
fn no_frontmatter_falls_back_to_dir_name() {
let tmp = std::env::temp_dir().join(format!("pi-skills-nofm-{}", uuid::Uuid::new_v4()));
let dir = write_skill(&tmp, "plain-skill", "Just a body, no frontmatter.\n");
let skill = parse_skill_file(&dir.join("SKILL.md"), &dir, SkillSource::Project).unwrap();
assert_eq!(skill.name, "plain-skill");
assert_eq!(skill.description, "");
assert!(skill.body.contains("Just a body"));
let _ = std::fs::remove_dir_all(&tmp);
}
#[test]
fn discover_finds_project_and_user_skills() {
let project = std::env::temp_dir().join(format!("pi-skills-proj-{}", uuid::Uuid::new_v4()));
let user = std::env::temp_dir().join(format!("pi-skills-user-{}", uuid::Uuid::new_v4()));
write_skill(&project, "alpha", "---\nname: alpha\ndescription: a\n---\nbody-a\n");
write_skill(&user, "beta", "---\nname: beta\ndescription: b\n---\nbody-b\n");
let skills = Skills::discover_from_roots(&[
(project.clone(), SkillSource::Project),
(user.clone(), SkillSource::User),
]);
let names = skills.names();
assert!(names.contains(&"alpha"), "{names:?}");
assert!(names.contains(&"beta"), "{names:?}");
let _ = std::fs::remove_dir_all(&project);
let _ = std::fs::remove_dir_all(&user);
}
#[test]
fn project_skill_shadows_user_skill_of_same_name() {
let project = std::env::temp_dir().join(format!("pi-skills-sp-{}", uuid::Uuid::new_v4()));
let user = std::env::temp_dir().join(format!("pi-skills-su-{}", uuid::Uuid::new_v4()));
write_skill(&project, "shared", "---\nname: shared\ndescription: PROJECT\n---\nproj-body\n");
write_skill(&user, "shared", "---\nname: shared\ndescription: USER\n---\nuser-body\n");
let skills = Skills::discover_from_roots(&[
(project.clone(), SkillSource::Project),
(user.clone(), SkillSource::User),
]);
assert_eq!(skills.skills.iter().filter(|s| s.name == "shared").count(), 1);
assert_eq!(skills.find("shared").unwrap().description, "PROJECT");
assert_eq!(skills.find("shared").unwrap().source, SkillSource::Project);
let _ = std::fs::remove_dir_all(&project);
let _ = std::fs::remove_dir_all(&user);
}
#[test]
fn discover_ignores_files_and_dirs_without_skill_md() {
let root = std::env::temp_dir().join(format!("pi-skills-skip-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(root.join("not-a-skill")).unwrap(); std::fs::write(root.join("loose-file.md"), "x").unwrap(); write_skill(&root, "real", "---\nname: real\ndescription: r\n---\nb\n");
let skills = Skills::discover_from_roots(&[(root.clone(), SkillSource::Project)]);
assert_eq!(skills.names(), vec!["real"]);
let _ = std::fs::remove_dir_all(&root);
}
}