1use std::path::{Path, PathBuf};
7
8use anyhow::{Context, Result};
9
10#[derive(Debug, Clone, PartialEq)]
11pub struct Skill {
12 pub name: String,
13 pub description: String,
14 pub file_path: PathBuf,
15 pub disable_model_invocation: bool,
16}
17
18#[derive(Debug, Clone, PartialEq, Eq)]
19pub struct SkillInvocation {
20 pub skill_names: Vec<String>,
21 pub request: String,
22}
23
24pub fn parse_invocation(input: &str, skills: &[Skill]) -> Option<SkillInvocation> {
26 let mut rest = input.trim_start();
27 let mut skill_names = Vec::new();
28
29 loop {
30 let token_end = rest.find(char::is_whitespace).unwrap_or(rest.len());
31 let token = &rest[..token_end];
32 let candidate = token
33 .strip_prefix('$')
34 .or_else(|| token.strip_prefix("/skill:"))
35 .or_else(|| token.strip_prefix('/'));
36 let Some(skill) = candidate
37 .filter(|name| !name.is_empty())
38 .and_then(|name| skills.iter().find(|skill| skill.name == name))
39 else {
40 break;
41 };
42 if !skill_names.contains(&skill.name) {
43 skill_names.push(skill.name.clone());
44 }
45 rest = rest[token_end..].trim_start();
46 }
47
48 for name in rest
49 .split_whitespace()
50 .filter_map(|token| token.strip_prefix('$'))
51 {
52 if let Some(skill) = skills.iter().find(|skill| skill.name == name)
53 && !skill_names.contains(&skill.name)
54 {
55 skill_names.push(skill.name.clone());
56 }
57 }
58
59 (!skill_names.is_empty()).then(|| SkillInvocation {
60 skill_names,
61 request: rest.trim().to_string(),
62 })
63}
64
65pub fn expand_invocation(invocation: &SkillInvocation, skills: &[Skill]) -> Result<String> {
67 let mut output = String::from(
68 "The user explicitly invoked the following skills. Follow each skill for this turn.\n\n",
69 );
70 for name in &invocation.skill_names {
71 let skill = skills
72 .iter()
73 .find(|skill| &skill.name == name)
74 .with_context(|| format!("invoked skill `{name}` is not available"))?;
75 let content = std::fs::read_to_string(&skill.file_path).with_context(|| {
76 format!(
77 "could not read invoked skill `{name}` at {}",
78 skill.file_path.display()
79 )
80 })?;
81 output.push_str(&format!(
82 "<invoked_skill name=\"{}\" path=\"{}\">\n{}\n</invoked_skill>\n\n",
83 escape_xml(&skill.name),
84 escape_xml(&skill.file_path.display().to_string()),
85 content
86 ));
87 }
88 output.push_str("<user_request>\n");
89 output.push_str(&invocation.request);
90 output.push_str("\n</user_request>");
91 Ok(output)
92}
93
94pub fn split_frontmatter(text: &str) -> (Option<&str>, &str) {
96 let Some(rest) = text.strip_prefix("---") else {
97 return (None, text);
98 };
99 let rest = rest
100 .strip_prefix('\n')
101 .or_else(|| rest.strip_prefix("\r\n"))
102 .unwrap_or(rest);
103 for end in ["\n---\n", "\n---\r\n", "\r\n---\r\n", "\r\n---\n"] {
104 if let Some(pos) = rest.find(end) {
105 return (Some(&rest[..pos]), &rest[pos + end.len()..]);
106 }
107 }
108 if let Some(stripped) = rest
109 .strip_suffix("\n---")
110 .or_else(|| rest.strip_suffix("\r\n---"))
111 {
112 return (Some(stripped), "");
113 }
114 (None, text)
115}
116
117fn parse_skill(path: &Path) -> Option<Skill> {
118 let text = std::fs::read_to_string(path).ok()?;
119 let (frontmatter, _body) = split_frontmatter(&text);
120 let mut name = None;
121 let mut description = None;
122 let mut disable_model_invocation = false;
123 if let Some(fm) = frontmatter
124 && let Ok(value) = serde_yaml::from_str::<serde_yaml::Value>(fm)
125 {
126 name = value["name"].as_str().map(String::from);
127 description = value["description"].as_str().map(String::from);
128 disable_model_invocation = value["disable-model-invocation"].as_bool().unwrap_or(false);
129 }
130 let fallback_name = || {
131 if path.file_name().and_then(|f| f.to_str()) == Some("SKILL.md") {
132 path.parent()?.file_name()?.to_str().map(String::from)
133 } else {
134 path.file_stem()?.to_str().map(String::from)
135 }
136 };
137 let name = name.or_else(fallback_name)?;
138 Some(Skill {
139 description: description.unwrap_or_else(|| format!("Skill {name}")),
140 name,
141 file_path: path.to_path_buf(),
142 disable_model_invocation,
143 })
144}
145
146fn scan_dir(dir: &Path, include_root_md: bool, out: &mut Vec<Skill>) {
149 let Ok(entries) = std::fs::read_dir(dir) else {
150 return;
151 };
152 let skill_md = dir.join("SKILL.md");
153 if skill_md.is_file()
154 && let Some(skill) = parse_skill(&skill_md)
155 {
156 out.push(skill);
157 }
158 for entry in entries.flatten() {
159 let path = entry.path();
160 if path.is_dir() {
161 scan_dir(&path, false, out);
162 } else if include_root_md
163 && path.extension().and_then(|e| e.to_str()) == Some("md")
164 && path.file_name().and_then(|f| f.to_str()) != Some("SKILL.md")
165 && let Some(skill) = parse_skill(&path)
166 {
167 out.push(skill);
168 }
169 }
170}
171
172pub fn project_agents_skill_dirs(cwd: &Path) -> Vec<PathBuf> {
175 let home = dirs::home_dir();
176 let mut found = Vec::new();
177 for dir in cwd.ancestors() {
178 if home.as_deref() == Some(dir) {
179 break;
180 }
181 found.push(dir.join(".agents/skills"));
182 if dir.join(".git").exists() {
183 break;
184 }
185 }
186 found
187}
188
189pub fn discover(cwd: &Path, project_trusted: bool, extra_paths: &[PathBuf]) -> Vec<Skill> {
191 let mut out: Vec<Skill> = Vec::new();
192 if let Some(agent_dir) = kiss_ai::paths::agent_dir() {
193 scan_dir(&agent_dir.join("skills"), true, &mut out);
194 }
195 if let Some(home) = dirs::home_dir() {
196 scan_dir(&home.join(".agents/skills"), false, &mut out);
197 }
198 if project_trusted {
199 scan_dir(&cwd.join(".kiss/skills"), true, &mut out);
200 for dir in project_agents_skill_dirs(cwd) {
201 scan_dir(&dir, false, &mut out);
202 }
203 }
204 for path in extra_paths {
205 if path.is_dir() {
206 scan_dir(path, true, &mut out);
207 } else if let Some(skill) = parse_skill(path) {
208 out.push(skill);
209 }
210 }
211 let mut seen = std::collections::HashSet::new();
213 out.retain(|s| seen.insert(s.name.clone()));
214 out
215}
216
217fn escape_xml(value: &str) -> String {
218 value
219 .replace('&', "&")
220 .replace('<', "<")
221 .replace('>', ">")
222 .replace('"', """)
223 .replace('\'', "'")
224}
225
226pub fn format_skills_for_prompt(skills: &[Skill]) -> String {
227 format_skills_for_prompt_with_tool(skills, "read")
228}
229
230pub fn format_skills_for_prompt_with_tool(skills: &[Skill], tool: &str) -> String {
231 let visible: Vec<&Skill> = skills
232 .iter()
233 .filter(|s| !s.disable_model_invocation)
234 .collect();
235 if visible.is_empty() {
236 return String::new();
237 }
238 let mut out = format!(
239 "The following skills provide specialized instructions for specific tasks.\nUse {tool} to load a skill's file when the task matches its description.\nWhen a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.\n\n<available_skills>\n",
240 );
241 for skill in visible {
242 out.push_str(" <skill>\n");
243 out.push_str(&format!(" <name>{}</name>\n", escape_xml(&skill.name)));
244 out.push_str(&format!(
245 " <description>{}</description>\n",
246 escape_xml(&skill.description)
247 ));
248 out.push_str(&format!(
249 " <location>{}</location>\n",
250 escape_xml(&skill.file_path.display().to_string())
251 ));
252 out.push_str(" </skill>\n");
253 }
254 out.push_str("</available_skills>");
255 out
256}
257
258#[cfg(test)]
259mod tests {
260 use super::*;
261
262 #[test]
263 fn frontmatter_split() {
264 let (fm, body) = split_frontmatter("---\nname: x\n---\nbody here");
265 assert_eq!(fm, Some("name: x"));
266 assert_eq!(body, "body here");
267 let (fm, body) = split_frontmatter("no frontmatter");
268 assert!(fm.is_none());
269 assert_eq!(body, "no frontmatter");
270 }
271
272 #[test]
273 fn discovers_skill_dirs_and_root_md() {
274 let dir = tempfile::tempdir().unwrap();
275 let root = dir.path();
276 std::fs::create_dir_all(root.join("pdf-tools")).unwrap();
277 std::fs::write(
278 root.join("pdf-tools/SKILL.md"),
279 "---\nname: pdf-tools\ndescription: Work with PDFs\n---\nInstructions",
280 )
281 .unwrap();
282 std::fs::write(
283 root.join("quick.md"),
284 "---\ndescription: Quick one\n---\nGo",
285 )
286 .unwrap();
287 let mut out = Vec::new();
288 scan_dir(root, true, &mut out);
289 let names: Vec<&str> = out.iter().map(|s| s.name.as_str()).collect();
290 assert!(names.contains(&"pdf-tools"));
291 assert!(names.contains(&"quick"));
292
293 let direct = discover(root, false, &[root.join("pdf-tools")]);
294 let loaded = direct
295 .iter()
296 .find(|skill| skill.name == "pdf-tools")
297 .unwrap();
298 assert_eq!(loaded.file_path, root.join("pdf-tools/SKILL.md"));
299 }
300
301 #[test]
302 fn prompt_xml_escapes() {
303 let skills = vec![Skill {
304 name: "a<b".into(),
305 description: "uses & things".into(),
306 file_path: "/s/SKILL.md".into(),
307 disable_model_invocation: false,
308 }];
309 let xml = format_skills_for_prompt(&skills);
310 assert!(xml.contains("<name>a<b</name>"));
311 assert!(xml.contains("uses & things"));
312 }
313
314 fn skill(name: &str, path: PathBuf) -> Skill {
315 Skill {
316 name: name.into(),
317 description: format!("Use {name}"),
318 file_path: path,
319 disable_model_invocation: false,
320 }
321 }
322
323 #[test]
324 fn parses_chained_dollar_slash_and_compatible_skill_tokens() {
325 let skills = vec![
326 skill("review", "review/SKILL.md".into()),
327 skill("tests", "tests/SKILL.md".into()),
328 skill("docs", "docs/SKILL.md".into()),
329 ];
330 assert_eq!(
331 parse_invocation(" $review /tests /skill:docs check this", &skills),
332 Some(SkillInvocation {
333 skill_names: vec!["review".into(), "tests".into(), "docs".into()],
334 request: "check this".into(),
335 })
336 );
337 assert_eq!(
338 parse_invocation("please use $review and $tests", &skills),
339 Some(SkillInvocation {
340 skill_names: vec!["review".into(), "tests".into()],
341 request: "please use $review and $tests".into(),
342 })
343 );
344 assert_eq!(parse_invocation("$unknown request", &skills), None);
345 }
346
347 #[test]
348 fn expansion_reads_each_skill_once_and_keeps_the_request_last() {
349 let dir = tempfile::tempdir().unwrap();
350 let review = dir.path().join("review.md");
351 let tests = dir.path().join("tests.md");
352 std::fs::write(&review, "Review instructions").unwrap();
353 std::fs::write(&tests, "Test instructions").unwrap();
354 let skills = vec![skill("review", review), skill("tests", tests)];
355 let invocation = parse_invocation("$review /tests inspect it", &skills).unwrap();
356
357 let expanded = expand_invocation(&invocation, &skills).unwrap();
358
359 assert_eq!(expanded.matches("Review instructions").count(), 1);
360 assert_eq!(expanded.matches("Test instructions").count(), 1);
361 assert!(expanded.ends_with("<user_request>\ninspect it\n</user_request>"));
362 }
363
364 #[test]
365 fn expansion_error_names_an_unreadable_skill() {
366 let skills = vec![skill("missing", "/no/such/skill/SKILL.md".into())];
367 let invocation = parse_invocation("$missing run", &skills).unwrap();
368 let error = expand_invocation(&invocation, &skills).unwrap_err();
369 assert!(format!("{error:#}").contains("invoked skill `missing`"));
370 }
371}