1use std::collections::BTreeMap;
6use std::fs;
7use std::path::{Path, PathBuf};
8use std::sync::Arc;
9
10use byob_tools::{Access, Tool, ToolContext, ToolOutput, ToolSpec, parse_args};
11use serde::{Deserialize, Serialize};
12use serde_json::{Value, json};
13
14use crate::LoadError;
15
16const MAX_SKILL_BYTES: u64 = 256 * 1024;
18const MAX_LISTED_FILES: usize = 30;
20pub const MAX_SKILL_FILES: usize = 10;
22pub const MAX_SKILL_FILE_BYTES: usize = 100_000;
23
24#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
26pub struct Skill {
27 pub name: String,
29 pub description: String,
30 pub body: String,
32 pub dir: PathBuf,
34 pub network: bool,
36 pub packages: Vec<String>,
38 pub meta: BTreeMap<String, String>,
40}
41
42pub fn skill_name_ok(n: &str) -> bool {
44 let b = n.as_bytes();
45 !b.is_empty()
46 && b.len() <= 64
47 && (b[0].is_ascii_lowercase() || b[0].is_ascii_digit())
48 && b.iter().all(|&c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == b'-')
49}
50
51pub fn slug(s: &str) -> String {
53 let mut out = String::new();
54 let mut dash = false;
55 for c in s.chars().flat_map(char::to_lowercase) {
56 if c.is_ascii_lowercase() || c.is_ascii_digit() {
57 if dash && !out.is_empty() {
58 out.push('-');
59 }
60 dash = false;
61 out.push(c);
62 } else {
63 dash = true;
64 }
65 }
66 out.truncate(64);
67 out.trim_end_matches('-').to_string()
68}
69
70pub fn skill_name(n: &str) -> String {
72 let n = n.trim().trim_start_matches('/');
73 if skill_name_ok(n) { n.to_string() } else { slug(n) }
74}
75
76fn unquote(v: &str) -> &str {
77 let b = v.as_bytes();
78 if b.len() >= 2 && (b[0] == b'"' || b[0] == b'\'') && b[b.len() - 1] == b[0] { &v[1..v.len() - 1] } else { v }
79}
80
81pub fn frontmatter(text: &str) -> (BTreeMap<String, String>, &str) {
85 let mut meta = BTreeMap::new();
86 let text = text.strip_prefix('\u{feff}').unwrap_or(text);
87 let Some(rest) = text.strip_prefix("---\n").or_else(|| text.strip_prefix("---\r\n")) else { return (meta, text) };
88 let mut end = None;
90 let mut pos = 0;
91 for line in rest.split_inclusive('\n') {
92 if line.trim_end_matches(['\r', '\n']) == "---" {
93 end = Some((pos, pos + line.len()));
94 break;
95 }
96 pos += line.len();
97 }
98 let Some((head_end, body_start)) = end else { return (meta, text) };
99 let lines: Vec<&str> = rest[..head_end].lines().collect();
100 let mut i = 0;
101 while i < lines.len() {
102 let line = lines[i];
103 i += 1;
104 let Some((key, value)) = key_value(line) else { continue };
105 let mut v = value.trim().to_string();
106 let continues = |l: &str| l.trim().is_empty() || l.starts_with([' ', '\t']);
107 if matches!(v.as_str(), ">" | "|" | ">-" | "|-" | ">+" | "|+") {
108 let mut block = Vec::new();
109 while i < lines.len() && continues(lines[i]) {
110 block.push(lines[i].trim());
111 i += 1;
112 }
113 v = block.join(if v.starts_with('>') { " " } else { "\n" }).trim().to_string();
114 } else if v.is_empty() {
115 let mut items = Vec::new();
116 while i < lines.len() && (continues(lines[i]) || lines[i].starts_with('-')) {
117 if let Some(item) = lines[i].trim().strip_prefix('-') {
118 items.push(unquote(item.trim()).to_string());
119 }
120 i += 1;
121 }
122 v = items.join(", ");
123 } else if let Some(inner) = v.strip_prefix('[').and_then(|s| s.strip_suffix(']')) {
124 v = inner.split(',').map(|s| unquote(s.trim())).filter(|s| !s.is_empty()).collect::<Vec<_>>().join(", ");
125 }
126 meta.insert(key.to_string(), unquote(&v).to_string());
127 }
128 (meta, &rest[body_start..])
129}
130
131fn key_value(line: &str) -> Option<(&str, &str)> {
133 let (k, v) = line.split_once(':')?;
134 let mut chars = k.chars();
135 let ok = chars.next().is_some_and(|c| c.is_ascii_alphabetic()) && chars.all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-');
136 ok.then_some((k, v))
137}
138
139pub fn parse_skill(text: &str, dir: &Path) -> Result<Skill, String> {
141 let folder = dir.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_default();
142 let (mut meta, body) = frontmatter(text);
143 let name = meta.remove("name").filter(|n| !n.is_empty()).unwrap_or_else(|| folder.clone());
144 if !skill_name_ok(&name) {
145 return Err(format!("{folder}/SKILL.md: name must be lowercase words with dashes, like \"plan-trip\""));
146 }
147 let description = meta.remove("description").unwrap_or_default();
148 if description.trim().is_empty() {
149 return Err(format!("{folder}/SKILL.md: add a description in the frontmatter so the assistant knows when to use it"));
150 }
151 let network = meta.remove("network").is_some_and(|n| n == "true");
152 let packages = meta.remove("packages").map(|p| p.split([',', ' ', '\t', '\n']).filter(|s| !s.is_empty()).map(str::to_string).collect()).unwrap_or_default();
153 Ok(Skill { name, description, body: body.trim().to_string(), dir: dir.to_path_buf(), network, packages, meta })
154}
155
156pub fn load_skill(dir: &Path) -> Result<Skill, String> {
158 let file = dir.join("SKILL.md");
159 let text = read_capped(&file, MAX_SKILL_BYTES)?;
160 parse_skill(&text, dir)
161}
162
163pub(crate) fn read_capped(file: &Path, max: u64) -> Result<String, String> {
164 let len = fs::metadata(file).map_err(|e| format!("{}: {e}", file.display()))?.len();
165 if len > max {
166 return Err(format!("{}: too big ({len} bytes, at most {max})", file.display()));
167 }
168 fs::read_to_string(file).map_err(|e| format!("{}: {e}", file.display()))
169}
170
171pub fn load_skills_dir(root: &Path) -> (Vec<Skill>, Vec<LoadError>) {
174 let mut skills = Vec::new();
175 let mut errors = Vec::new();
176 for dir in crate::discover::subdirs(root) {
177 if !dir.join("SKILL.md").is_file() {
178 continue;
179 }
180 match load_skill(&dir) {
181 Ok(s) => skills.push(s),
182 Err(message) => errors.push(LoadError { path: dir, message }),
183 }
184 }
185 (skills, errors)
186}
187
188pub fn skills_prompt(skills: &[Skill]) -> String {
190 if skills.is_empty() {
191 return String::new();
192 }
193 let lines: Vec<String> = skills
194 .iter()
195 .map(|s| {
196 let d: String = s.description.split_whitespace().collect::<Vec<_>>().join(" ").chars().take(160).collect();
197 format!("- {}: {d}", s.name)
198 })
199 .collect();
200 format!(
201 "Skills (step-by-step know-how for certain tasks). When a request matches one, call use_skill with its name first and follow it:\n{}",
202 lines.join("\n")
203 )
204}
205
206fn files_in(dir: &Path, max: usize) -> Vec<String> {
208 let mut out = Vec::new();
209 let mut stack = vec![(dir.to_path_buf(), String::new(), 0usize)];
210 while let Some((d, prefix, depth)) = stack.pop() {
211 let Ok(rd) = fs::read_dir(&d) else { continue };
212 let mut entries: Vec<_> = rd.flatten().collect();
213 entries.sort_by_key(|e| e.file_name());
214 for e in entries.into_iter().rev() {
215 let name = e.file_name().to_string_lossy().into_owned();
216 if name.starts_with('.') || (depth == 0 && name == "SKILL.md") {
217 continue;
218 }
219 let rel = if prefix.is_empty() { name } else { format!("{prefix}/{name}") };
220 if e.file_type().is_ok_and(|t| t.is_dir()) {
221 if depth < 4 {
222 stack.push((e.path(), rel, depth + 1));
223 }
224 } else {
225 out.push(rel);
226 }
227 }
228 }
229 out.sort();
230 out.truncate(max);
231 out
232}
233
234#[derive(Debug, Clone, Default)]
236pub struct UseSkillTool {
237 skills: Arc<Vec<Skill>>,
238}
239
240impl UseSkillTool {
241 pub fn new(skills: Vec<Skill>) -> Self {
242 Self { skills: Arc::new(skills) }
243 }
244
245 pub fn find(&self, name: &str) -> Option<&Skill> {
246 let name = name.trim().trim_start_matches('/');
247 self.skills.iter().find(|s| s.name == name)
248 }
249}
250
251impl Tool for UseSkillTool {
252 fn spec(&self) -> ToolSpec {
253 ToolSpec {
254 name: "use_skill".into(),
255 description: "Get the step-by-step instructions of one of your skills (listed in your instructions) before doing that kind of task.".into(),
256 parameters: json!({"type": "object", "properties": {"name": {"type": "string", "description": "The skill name, e.g. plan-trip"}}, "required": ["name"]}),
257 }
258 }
259
260 fn title(&self, args: &Value) -> String {
261 let n: String = args.get("name").and_then(Value::as_str).unwrap_or("").replace('-', " ").chars().take(64).collect();
262 format!("Used the {n} skill")
263 }
264
265 fn access(&self, _args: &Value) -> Access {
266 Access::Read
267 }
268
269 fn run(&self, args: &Value, _ctx: &ToolContext<'_>) -> ToolOutput {
270 let asked = args.get("name").and_then(Value::as_str).unwrap_or("");
271 let Some(s) = self.find(asked) else {
272 let have: Vec<&str> = self.skills.iter().map(|s| s.name.as_str()).collect();
273 let have = if have.is_empty() { "none".to_string() } else { have.join(", ") };
274 let asked: String = asked.chars().take(64).collect();
275 return ToolOutput::err(format!("There's no skill called “{asked}”. Skills you have: {have}."));
276 };
277 let files = files_in(&s.dir, MAX_LISTED_FILES);
278 let files = if files.is_empty() { String::new() } else { format!("; files: {}", files.join(", ")) };
279 ToolOutput::ok(format!("{}\n\n(Skill folder: {}{files})", s.body, s.dir.display()))
280 }
281}
282
283#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
285pub struct NewSkill {
286 pub name: String,
287 pub description: String,
288 pub instructions: String,
289 #[serde(default)]
290 pub files: BTreeMap<String, String>,
291 #[serde(default)]
292 pub packages: Vec<String>,
293 #[serde(default)]
294 pub network: bool,
295 #[serde(default)]
296 pub replace: bool,
297}
298
299pub fn skill_file(name: &str, s: &NewSkill) -> String {
301 let desc = s.description.split_whitespace().collect::<Vec<_>>().join(" ");
302 let desc = serde_json::to_string(&desc).unwrap_or_else(|_| "\"\"".into());
303 let network = if s.network { "network: true\n" } else { "" };
304 let packages = if s.packages.is_empty() { String::new() } else { format!("packages: {}\n", s.packages.join(", ")) };
305 format!("---\nname: {name}\ndescription: {desc}\n{network}{packages}---\n{}\n", s.instructions.trim())
306}
307
308pub fn skill_files_problem(files: &BTreeMap<String, String>) -> Option<String> {
310 if files.len() > MAX_SKILL_FILES {
311 return Some(format!("A skill can keep up to {MAX_SKILL_FILES} files."));
312 }
313 for (n, text) in files {
314 if n == "SKILL.md" || !skill_file_name_ok(n) {
315 return Some(format!("“{n}” can't be saved with a skill: use a plain file name ending in .py, .md, .txt, .json or .csv."));
316 }
317 if text.len() > MAX_SKILL_FILE_BYTES {
318 return Some(format!("“{n}” is too big to keep with a skill (100 KB at most)."));
319 }
320 }
321 None
322}
323
324fn skill_file_name_ok(n: &str) -> bool {
326 let Some((stem, ext)) = n.rsplit_once('.') else { return false };
327 let b = stem.as_bytes();
328 matches!(ext, "py" | "md" | "txt" | "json" | "csv")
329 && !b.is_empty()
330 && b.len() <= 64
331 && (b[0].is_ascii_alphanumeric() || b[0] == b'_')
332 && b.iter().all(|&c| c.is_ascii_alphanumeric() || matches!(c, b'_' | b'.' | b'-'))
333}
334
335fn package_ok(p: &str) -> bool {
337 !p.is_empty()
338 && p.len() <= 100
339 && p.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.' | '=' | '[' | ']' | ',' | '<' | '>' | '~' | '!'))
340}
341
342pub fn save_skill(skills_root: &Path, s: &NewSkill) -> Result<String, String> {
344 let name = skill_name(&s.name);
345 if name.is_empty() {
346 return Err("Give the skill a name with letters or numbers.".into());
347 }
348 let own = skills_root.join(&name);
349 if !s.replace && own.join("SKILL.md").exists() {
350 return Err(format!("There's already a skill called /{name}. Pick another name."));
351 }
352 if s.description.trim().is_empty() {
353 return Err("Say when to use this skill.".into());
354 }
355 if s.instructions.trim().is_empty() {
356 return Err("Write the instructions for this skill.".into());
357 }
358 if let Some(p) = skill_files_problem(&s.files) {
359 return Err(p);
360 }
361 if let Some(p) = s.packages.iter().find(|p| !package_ok(p)) {
362 return Err(format!("“{p}” isn't a package name like pandas or yfinance==0.2.54."));
363 }
364 fs::create_dir_all(&own).map_err(|e| format!("Couldn't save the skill: {e}"))?;
365 for (f, text) in &s.files {
366 fs::write(own.join(f), text).map_err(|e| format!("Couldn't save {f}: {e}"))?;
367 }
368 let instructions = with_run_line(&name, &s.instructions, &s.files);
369 fs::write(own.join("SKILL.md"), skill_file(&name, &NewSkill { instructions, ..s.clone() })).map_err(|e| format!("Couldn't save the skill: {e}"))?;
370 Ok(name)
371}
372
373fn with_run_line(name: &str, instructions: &str, files: &BTreeMap<String, String>) -> String {
375 let missing: Vec<String> =
376 files.keys().filter(|f| f.ends_with(".py") && !instructions.contains(&format!("{name}/{f}"))).map(|f| format!("script \"{name}/{f}\"")).collect();
377 if missing.is_empty() {
378 return instructions.to_string();
379 }
380 format!("{}\n\nScripts in this skill: run them with run_python, passing {} and the inputs as args.", instructions.trim(), missing.join(" or "))
381}
382
383#[derive(Debug, Clone)]
387pub struct SaveSkillTool {
388 skills_root: PathBuf,
389}
390
391impl SaveSkillTool {
392 pub fn new(skills_root: PathBuf) -> Self {
394 Self { skills_root }
395 }
396}
397
398impl Tool for SaveSkillTool {
399 fn spec(&self) -> ToolSpec {
400 ToolSpec {
401 name: "save_skill".into(),
402 description:
403 "Save how to do a task as a skill the user can run later with /name: steps, plus the code that worked as script files. Only when the user asks."
404 .into(),
405 parameters: json!({
406 "type": "object",
407 "properties": {
408 "name": {"type": "string", "description": "Short name, lowercase words with dashes, e.g. weekly-report"},
409 "description": {"type": "string", "description": "One sentence: when to use this skill"},
410 "instructions": {"type": "string", "description": "Clear step-by-step instructions in Markdown. Say which script to run and what to pass it."},
411 "files": {"type": "object", "description": "Scripts and data to keep with the skill: file name → contents, e.g. {\"make_report.py\": \"...\"}. Use code that already worked in this chat. Scripts get their inputs from sys.argv and save results in the current folder.", "additionalProperties": {"type": "string"}},
412 "packages": {"type": "array", "items": {"type": "string"}, "description": "PyPI packages the scripts need that you installed with install_packages"},
413 "network": {"type": "boolean", "description": "true only if the scripts need the internet"},
414 "replace": {"type": "boolean", "description": "true to update an existing skill with this name"}
415 },
416 "required": ["name", "description", "instructions"]
417 }),
418 }
419 }
420
421 fn title(&self, args: &Value) -> String {
422 format!("Saved the “{}” skill", skill_name(args.get("name").and_then(Value::as_str).unwrap_or("")))
423 }
424
425 fn access(&self, _args: &Value) -> Access {
427 Access::Write
428 }
429
430 fn run(&self, args: &Value, _ctx: &ToolContext<'_>) -> ToolOutput {
431 let s: NewSkill = match parse_args(args) {
432 Ok(s) => s,
433 Err(e) => return ToolOutput::err(e),
434 };
435 match save_skill(&self.skills_root, &s) {
436 Ok(name) => ToolOutput::ok(format!("Saved. The user can run it with /{name}, and you'll see it in your skills list.")),
437 Err(e) => ToolOutput::err(e),
438 }
439 }
440}
441
442#[cfg(test)]
443mod tests {
444 use super::*;
445 use std::sync::atomic::AtomicBool;
446
447 #[test]
448 fn frontmatter_subset() {
449 let text = "---\nname: fridge\ndescription: >\n Suggest recipes\n from the fridge.\nnetwork: true\npackages:\n - yfinance==0.2.54\n - 'ta'\nallowed-tools: [a, \"b\"]\nquoted: \"x: y\"\n---\nSteps here.\n";
450 let (meta, body) = frontmatter(text);
451 assert_eq!(meta["name"], "fridge");
452 assert_eq!(meta["description"], "Suggest recipes from the fridge.");
453 assert_eq!(meta["packages"], "yfinance==0.2.54, ta");
454 assert_eq!(meta["allowed-tools"], "a, b");
455 assert_eq!(meta["quoted"], "x: y");
456 assert_eq!(body, "Steps here.\n");
457 let (meta, body) = frontmatter("no frontmatter");
458 assert!(meta.is_empty());
459 assert_eq!(body, "no frontmatter");
460 assert_eq!(frontmatter("---\nname: x\n").1, "---\nname: x\n");
462 let (meta, _) = frontmatter("---\r\ndescription: |\r\n a\r\n b\r\n---\r\nbody");
464 assert_eq!(meta["description"], "a\nb");
465 }
466
467 #[test]
468 fn parse_skill_rules() {
469 let dir = Path::new("/p/skills/fridge");
470 let s = parse_skill("---\ndescription: Recipes.\npackages: a==1, b\nlicense: MIT\n---\n\n1. Do.\n", dir).unwrap();
471 assert_eq!(s.name, "fridge");
472 assert_eq!(s.packages, ["a==1", "b"]);
473 assert_eq!(s.body, "1. Do.");
474 assert_eq!(s.meta["license"], "MIT");
475 assert!(!s.network);
476 assert_eq!(
477 parse_skill("---\nname: Bad Name\ndescription: d\n---\n", dir).unwrap_err(),
478 "fridge/SKILL.md: name must be lowercase words with dashes, like \"plan-trip\""
479 );
480 assert!(parse_skill("---\nname: ok\n---\n", dir).unwrap_err().contains("add a description"));
481 }
482
483 #[test]
484 fn slugs() {
485 assert_eq!(slug("Weekly report!"), "weekly-report");
486 assert_eq!(slug(" --Hi__there-- "), "hi-there");
487 assert_eq!(skill_name("/plan-trip"), "plan-trip");
488 assert_eq!(slug(&"a".repeat(100)).len(), 64);
489 }
490
491 #[test]
492 fn prompt_lists_skills() {
493 assert_eq!(skills_prompt(&[]), "");
494 let s = Skill {
495 name: "fridge".into(),
496 description: "Recipes\n from fridge.".into(),
497 body: String::new(),
498 dir: PathBuf::new(),
499 network: false,
500 packages: vec![],
501 meta: BTreeMap::new(),
502 };
503 let p = skills_prompt(&[s]);
504 assert!(p.starts_with("Skills (step-by-step"));
505 assert!(p.ends_with("\n- fridge: Recipes from fridge."));
506 }
507
508 #[test]
509 fn save_then_use() {
510 let root = std::env::temp_dir().join(format!("byob-plugins-save-{}", std::process::id()));
511 let _ = fs::remove_dir_all(&root);
512 let new = NewSkill {
513 name: "Weekly Report".into(),
514 description: "Make the weekly report.".into(),
515 instructions: "1. Run it.".into(),
516 files: BTreeMap::from([("make.py".to_string(), "print(1)".to_string())]),
517 packages: vec!["pandas".into()],
518 ..Default::default()
519 };
520 assert_eq!(save_skill(&root, &new).unwrap(), "weekly-report");
521 assert!(save_skill(&root, &new).unwrap_err().contains("already a skill"));
522 assert!(save_skill(&root, &NewSkill { replace: true, ..new.clone() }).is_ok());
523 let bad = NewSkill { files: BTreeMap::from([("../x.py".to_string(), String::new())]), replace: true, ..new.clone() };
524 assert!(save_skill(&root, &bad).unwrap_err().contains("can't be saved"));
525
526 let (skills, errors) = load_skills_dir(&root);
527 assert!(errors.is_empty(), "{errors:?}");
528 assert_eq!(skills[0].packages, ["pandas"]);
529 assert!(skills[0].body.contains("script \"weekly-report/make.py\""));
530
531 let tool = UseSkillTool::new(skills);
532 let cancel = AtomicBool::new(false);
533 let ctx = ToolContext::new(&root, &cancel);
534 let out = tool.run(&json!({"name": "/weekly-report"}), &ctx);
535 assert!(!out.failed);
536 assert!(out.text.starts_with("1. Run it.") && out.text.contains("files: make.py"), "{}", out.text);
537 let miss = tool.run(&json!({"name": 5}), &ctx);
538 assert!(miss.failed && miss.text.contains("Skills you have: weekly-report"));
539 assert_eq!(tool.access(&json!({})), Access::Read);
540 assert_eq!(tool.title(&json!({"name": "plan-trip"})), "Used the plan trip skill");
541 let _ = fs::remove_dir_all(&root);
542 }
543}