From 435868bf20345dceaad0eccad3b8cc76dc816284 Mon Sep 17 00:00:00 2001 From: Jack Amadeo Date: Fri, 16 Oct 2026 15:42:50 +0000 Subject: [PATCH] move skills discovery into GDK (#12935) --- Cargo.lock | 3 + crates/goose-agent/Cargo.toml | 7 +- crates/goose-agent/README.md | 8 + crates/goose-agent/src/lib.rs | 1 + .../src/skills/arguments.rs | 33 ++- crates/goose-agent/src/skills/discovery.rs | 247 ++++++++++++++++++ crates/goose-agent/src/skills/mod.rs | 74 ++++++ crates/goose/src/skills/mod.rs | 205 ++------------- 8 files changed, 386 insertions(+), 192 deletions(-) rename crates/{goose => goose-agent}/src/skills/arguments.rs (89%) create mode 100644 crates/goose-agent/src/skills/discovery.rs create mode 100644 crates/goose-agent/src/skills/mod.rs diff --git a/Cargo.lock b/Cargo.lock index 7a81d2fff..a5737b87f 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4431,11 +4431,14 @@ dependencies = [ "async-trait", "futures", "goose-provider-types", + "goose-sdk-types", "js-sys", + "regex", "rmcp", "schemars 1.2.2", "serde", "serde_json", + "serde_yaml", "tokio", "tokio-util", "tracing", diff --git a/crates/goose-agent/Cargo.toml b/crates/goose-agent/Cargo.toml index 0a0571073..9692c2b37 100644 --- a/crates/goose-agent/Cargo.toml +++ b/crates/goose-agent/Cargo.toml @@ -23,15 +23,20 @@ serde_json = { workspace = true } futures = { workspace = true } tracing = { workspace = true } tracing-futures = { workspace = true } +serde.workspace = true +regex = { workspace = true, features = ["unicode-perl"] } +goose-sdk-types = { version = "0.1.0-alpha.12", path = "../goose-sdk-types", default-features = false } [target.'cfg(target_arch = "wasm32")'.dependencies] rmcp = { workspace = true, features = ["local"] } [dev-dependencies] schemars.workspace = true -serde = { workspace = true, features = ["derive"] } [target.'cfg(target_arch = "wasm32")'.dev-dependencies] js-sys = "0.3.105" wasm-bindgen-futures = "0.4.78" wasm-bindgen-test = "0.3.78" + +[target.'cfg(not(target_arch = "wasm32"))'.dependencies] +serde_yaml.workspace = true diff --git a/crates/goose-agent/README.md b/crates/goose-agent/README.md index c89e4a43b..e34da55ae 100644 --- a/crates/goose-agent/README.md +++ b/crates/goose-agent/README.md @@ -75,6 +75,14 @@ its tool response message. Use one operation instance per active execution. operation that only builds, emits, and returns holds nothing. Dropping a future cannot undo external actions or stop blocking work that has already started. +## Skills + +`skills` provides argument substitution and loaded-skill formatting. On native +platforms, it also discovers skills from explicit, ordered roots. Configuration +paths, built-in skills, and tool registration remain host responsibilities; +these helpers do not automatically change the agent pipeline. Filesystem +discovery is not a secure file-open API. + ## WebAssembly The crate builds for `wasm32-unknown-unknown` and runs without a tokio runtime, diff --git a/crates/goose-agent/src/lib.rs b/crates/goose-agent/src/lib.rs index 59c031b19..39bc28750 100644 --- a/crates/goose-agent/src/lib.rs +++ b/crates/goose-agent/src/lib.rs @@ -2,5 +2,6 @@ pub mod events; pub mod inference; pub mod machine; pub mod operation; +pub mod skills; pub mod subagent; pub mod tool; diff --git a/crates/goose/src/skills/arguments.rs b/crates/goose-agent/src/skills/arguments.rs similarity index 89% rename from crates/goose/src/skills/arguments.rs rename to crates/goose-agent/src/skills/arguments.rs index beb1306e5..91482e128 100644 --- a/crates/goose/src/skills/arguments.rs +++ b/crates/goose-agent/src/skills/arguments.rs @@ -1,8 +1,39 @@ -use crate::utils::split_command_args; use anyhow::Result; use regex::{Captures, Regex}; use std::sync::LazyLock; +fn split_command_args(input: &str) -> anyhow::Result> { + let mut parts = Vec::new(); + let mut current = String::new(); + let mut in_double_quote = false; + let mut in_single_quote = false; + + for c in input.chars() { + match c { + '"' if !in_single_quote => in_double_quote = !in_double_quote, + '\'' if !in_double_quote && (in_single_quote || current.is_empty()) => { + in_single_quote = !in_single_quote + } + c if c.is_whitespace() && !in_double_quote && !in_single_quote => { + if !current.is_empty() { + parts.push(std::mem::take(&mut current)); + } + } + _ => current.push(c), + } + } + + if in_double_quote || in_single_quote { + return Err(anyhow::anyhow!("Unmatched quote in command")); + } + + if !current.is_empty() { + parts.push(current); + } + + Ok(parts) +} + static PLACEHOLDER_RE: LazyLock = LazyLock::new(|| { Regex::new( r"\$ARGUMENTS\[(?P\d+)\]|\$ARGUMENTS\b|\$(?P\d+)|\$(?P[A-Za-z_][A-Za-z0-9_-]*)", diff --git a/crates/goose-agent/src/skills/discovery.rs b/crates/goose-agent/src/skills/discovery.rs new file mode 100644 index 000000000..3a2e239d7 --- /dev/null +++ b/crates/goose-agent/src/skills/discovery.rs @@ -0,0 +1,247 @@ +//! Native filesystem skill discovery under caller-supplied roots. + +use goose_sdk_types::custom_requests::{SourceEntry, SourceType}; +use serde::Deserialize; +use serde_json::Value; +use std::collections::{HashMap, HashSet}; +use std::path::{Path, PathBuf}; +use tracing::warn; + +/// A host-selected search root; earlier roots take precedence. +#[derive(Debug, Clone)] +pub struct SkillRoot { + /// Directory searched recursively for `SKILL.md`. Returned entry paths identify + /// the containing skill directory, not the Markdown file. + /// Relative roots are resolved against the process working directory. + pub path: PathBuf, + /// Scope metadata copied to each entry, not inferred from its location. + pub global: bool, + /// Writability metadata copied to each entry. Discovery does not check + /// permissions or enforce whether a host may modify the skill. + pub writable: bool, + /// Retain lexical skill-directory and supporting-file paths (e.g. plugin links) + /// instead of canonicalizing the skill directory. Relative roots then produce + /// relative result paths; supply absolute roots when absolute paths are needed. + /// This does not change symlink traversal or confine reads to the root. + pub preserve_path: bool, +} + +#[derive(Debug, Deserialize)] +struct Frontmatter { + #[serde(default)] + name: Option, + #[serde(default)] + description: String, + #[serde(default)] + metadata: HashMap, +} + +fn parse_frontmatter Deserialize<'de>>( + content: &str, +) -> Result, serde_yaml::Error> { + let parts: Vec<&str> = content.split("---").collect(); + if parts.len() < 3 { + return Ok(None); + } + + let yaml_content = parts[1].trim(); + let metadata: T = serde_yaml::from_str(yaml_content)?; + + let body = parts[2..].join("---").trim().to_string(); + Ok(Some((metadata, body))) +} + +fn parse_skill_content( + content: &str, + path: &Path, + global: bool, + writable: bool, +) -> Option { + let (metadata, body): (Frontmatter, String) = match parse_frontmatter(content) { + Ok(Some(parsed)) => parsed, + Ok(None) => return None, + Err(e) => { + warn!("Failed to parse skill frontmatter: {}", e); + return None; + } + }; + + let name = match metadata.name.filter(|n| !n.is_empty()) { + Some(n) => n, + None => { + warn!( + "Skill at '{}' is missing a required 'name' in frontmatter, skipping", + path.display() + ); + return None; + } + }; + + if name.contains('/') { + warn!("Skill name '{}' contains '/', skipping", name); + return None; + } + + Some(SourceEntry { + source_type: SourceType::Skill, + name, + description: metadata.description, + content: body, + path: path.to_string_lossy().into_owned(), + global, + writable, + supporting_files: Vec::new(), + properties: metadata.metadata, + }) +} + +fn should_skip_dir(path: &Path) -> bool { + matches!( + path.file_name().and_then(|name| name.to_str()), + Some(".git") | Some(".hg") | Some(".svn") + ) +} + +fn walk_files_recursively( + dir: &Path, + visited_dirs: &mut HashSet, + should_descend: &mut G, + visit_file: &mut F, +) where + F: FnMut(&Path), + G: FnMut(&Path) -> bool, +{ + let canonical_dir = match std::fs::canonicalize(dir) { + Ok(path) => path, + Err(_) => return, + }; + + if !visited_dirs.insert(canonical_dir) { + return; + } + + let entries = match std::fs::read_dir(dir) { + Ok(e) => e, + Err(_) => return, + }; + + for entry in entries.flatten() { + let path = entry.path(); + if path.is_dir() { + if should_descend(&path) { + walk_files_recursively(&path, visited_dirs, should_descend, visit_file); + } + } else if path.is_file() { + visit_file(&path); + } + } +} + +fn scan_skills_from_dir( + dir: &Path, + global: bool, + writable: bool, + preserve_path: bool, + seen: &mut HashSet, +) -> Vec { + let mut skill_files = Vec::new(); + let mut visited_dirs = HashSet::new(); + + walk_files_recursively( + dir, + &mut visited_dirs, + &mut |path| !should_skip_dir(path), + &mut |path| { + if path.file_name().and_then(|name| name.to_str()) == Some("SKILL.md") { + skill_files.push(path.to_path_buf()); + } + }, + ); + + let mut sources = Vec::new(); + for skill_file in skill_files { + let Some(skill_dir) = skill_file.parent() else { + continue; + }; + let registered_skill_dir = if preserve_path { + skill_dir.to_path_buf() + } else { + let Ok(canonical_dir) = skill_dir.canonicalize() else { + continue; + }; + canonical_dir + }; + let content = match std::fs::read_to_string(&skill_file) { + Ok(c) => c, + Err(e) => { + warn!("Failed to read skill file {}: {}", skill_file.display(), e); + continue; + } + }; + + if let Some(mut source) = + parse_skill_content(&content, ®istered_skill_dir, global, writable) + { + if !seen.contains(&source.name) { + let mut files = Vec::new(); + let mut visited_support_dirs = HashSet::new(); + walk_files_recursively( + skill_dir, + &mut visited_support_dirs, + &mut |path| !should_skip_dir(path) && !path.join("SKILL.md").is_file(), + &mut |path| { + if path.file_name().and_then(|n| n.to_str()) != Some("SKILL.md") { + if let Ok(relative) = path.strip_prefix(skill_dir) { + files.push( + registered_skill_dir + .join(relative) + .to_string_lossy() + .into_owned(), + ); + } + } + }, + ); + source.supporting_files = files; + + seen.insert(source.name.clone()); + sources.push(source); + } + } + } + sources +} + +/// Recursively discovers skills from explicit roots, without consulting host configuration. +/// +/// Roots are visited in input order. The first successfully parsed entry with a +/// given name wins; names are compared exactly and case-sensitively. Traversal +/// within each root is unsorted, so result order, duplicate-name winners within a +/// root, and supporting-file order are unspecified. +/// +/// Discovery is best-effort: missing or unreadable directories and invalid or +/// unreadable skills are skipped. Some failures emit tracing warnings; no errors +/// are returned. An empty result does not distinguish no skills from a failed scan. +/// +/// Traversal follows file and directory symlinks, including targets outside a +/// root. Canonical directory identities prevent cycles. `preserve_path` only +/// affects returned path spelling; discovery is not a confined file-open API. +/// The caller must enforce access policy when opening returned paths. +pub fn discover_skills(roots: impl IntoIterator) -> Vec { + let mut sources: Vec = Vec::new(); + let mut seen = HashSet::new(); + + for dir in roots { + for source in scan_skills_from_dir( + &dir.path, + dir.global, + dir.writable, + dir.preserve_path, + &mut seen, + ) { + sources.push(source); + } + } + + sources +} diff --git a/crates/goose-agent/src/skills/mod.rs b/crates/goose-agent/src/skills/mod.rs new file mode 100644 index 000000000..da1ddffd1 --- /dev/null +++ b/crates/goose-agent/src/skills/mod.rs @@ -0,0 +1,74 @@ +//! Application-independent skill argument substitution and rendering. +//! Native targets also support filesystem discovery under explicit roots. + +mod arguments; +#[cfg(not(target_arch = "wasm32"))] +mod discovery; + +#[cfg(not(target_arch = "wasm32"))] +pub use discovery::{discover_skills, SkillRoot}; + +use anyhow::Result; +use arguments::apply_skill_arguments; +use goose_sdk_types::custom_requests::SourceEntry; +use std::path::Path; + +fn skill_argument_names(skill: &SourceEntry) -> Vec { + skill + .properties + .get("arguments") + .and_then(|value| value.as_array()) + .map(|items| { + items + .iter() + .filter_map(|item| item.as_str()) + .filter(|name| !name.is_empty()) + .map(str::to_string) + .collect() + }) + .unwrap_or_default() +} + +/// Returns skill content with optional argument substitution. +pub fn skill_content_with_args(skill: &SourceEntry, args: Option<&str>) -> Result { + let content = if let Some(args) = args { + apply_skill_arguments(&skill.content, args, &skill_argument_names(skill))? + } else { + skill.content.clone() + }; + + Ok(content) +} + +/// Formats a loaded skill using caller-supplied, postprocessed content. +pub fn loaded_skill_context(skill: &SourceEntry, content: &str) -> String { + let title = format!("{} ({})", skill.name, skill.source_type); + let mut output = format!( + "# Loaded Skill: {title}\n\n{}\n\n## Content\n\n{}\n", + skill.description, content + ); + + if !skill.supporting_files.is_empty() { + let skill_dir = Path::new(&skill.path); + output.push_str(&format!( + "\n## Supporting Files\n\nSkill directory: {}\n\n\ + Relative paths in this skill resolve from the skill directory. \ + The shell tool runs in the session working directory, so use the \ + resolved path below or `cd` into the skill directory before running \ + supporting scripts.\n\n", + skill.path + )); + for file in &skill.supporting_files { + if let Ok(relative) = Path::new(file).strip_prefix(skill_dir) { + let rel_str = relative.to_string_lossy().replace('\\', "/"); + let resolved_path = Path::new(file).to_string_lossy().replace('\\', "/"); + output.push_str(&format!( + "- {} → {} (load_skill(name: \"{}/{}\"))\n", + rel_str, resolved_path, skill.name, rel_str + )); + } + } + } + + output +} diff --git a/crates/goose/src/skills/mod.rs b/crates/goose/src/skills/mod.rs index 3e2a8180c..ee04b9c0e 100644 --- a/crates/goose/src/skills/mod.rs +++ b/crates/goose/src/skills/mod.rs @@ -2,7 +2,6 @@ //! built-ins) and the runtime MCP client (`client` submodule). User-facing //! CRUD lives in `crate::sources`, which generalizes across source types. -mod arguments; mod builtin; pub mod client; mod supporting_files; @@ -21,7 +20,7 @@ use crate::plugins::{ use crate::sources::parse_frontmatter; use agent_client_protocol::Error; use anyhow::Result; -use arguments::apply_skill_arguments; +use goose_agent::skills::SkillRoot; use goose_sdk_types::custom_requests::{SourceEntry, SourceType}; use serde::Deserialize; use serde_json::Value; @@ -122,51 +121,14 @@ fn resolve_docs_root_placeholder(skill: &SourceEntry, content: &str, docs_root: content.replace(GOOSE_DOCS_ROOT_PLACEHOLDER, docs_root) } -fn loaded_skill_context(skill: &SourceEntry, content: &str) -> Result { +pub fn loaded_skill_context_with_args(skill: &SourceEntry, args: Option<&str>) -> Result { + let content = goose_agent::skills::skill_content_with_args(skill, args)?; let docs_root = Config::global() .get_goose_docs_root()? .unwrap_or_else(|| DEFAULT_GOOSE_DOCS_ROOT.to_string()); - let content = resolve_docs_root_placeholder(skill, content, &docs_root); + let content = resolve_docs_root_placeholder(skill, &content, &docs_root); - let title = format!("{} ({})", skill.name, skill.source_type); - let mut output = format!( - "# Loaded Skill: {title}\n\n{}\n\n## Content\n\n{}\n", - skill.description, content - ); - - if !skill.supporting_files.is_empty() { - let skill_dir = Path::new(&skill.path); - output.push_str(&format!( - "\n## Supporting Files\n\nSkill directory: {}\n\n\ - Relative paths in this skill resolve from the skill directory. \ - The shell tool runs in the session working directory, so use the \ - resolved path below or `cd` into the skill directory before running \ - supporting scripts.\n\n", - skill.path - )); - for file in &skill.supporting_files { - if let Ok(relative) = Path::new(file).strip_prefix(skill_dir) { - let rel_str = relative.to_string_lossy().replace('\\', "/"); - let resolved_path = Path::new(file).to_string_lossy().replace('\\', "/"); - output.push_str(&format!( - "- {} → {} (load_skill(name: \"{}/{}\"))\n", - rel_str, resolved_path, skill.name, rel_str - )); - } - } - } - - Ok(output) -} - -pub fn loaded_skill_context_with_args(skill: &SourceEntry, args: Option<&str>) -> Result { - let content = if let Some(args) = args { - apply_skill_arguments(&skill.content, args, &skill_argument_names(skill))? - } else { - skill.content.clone() - }; - - loaded_skill_context(skill, &content) + Ok(goose_agent::skills::loaded_skill_context(skill, &content)) } pub fn skill_argument_hint(skill: &SourceEntry) -> Option { @@ -178,22 +140,6 @@ pub fn skill_argument_hint(skill: &SourceEntry) -> Option { .map(str::to_string) } -pub fn skill_argument_names(skill: &SourceEntry) -> Vec { - skill - .properties - .get("arguments") - .and_then(|value| value.as_array()) - .map(|items| { - items - .iter() - .filter_map(|item| item.as_str()) - .filter(|name| !name.is_empty()) - .map(str::to_string) - .collect() - }) - .unwrap_or_default() -} - fn canonicalize_or_original(path: &Path) -> PathBuf { path.canonicalize().unwrap_or_else(|_| path.to_path_buf()) } @@ -486,123 +432,6 @@ fn parse_skill_content( }) } -fn should_skip_dir(path: &Path) -> bool { - matches!( - path.file_name().and_then(|name| name.to_str()), - Some(".git") | Some(".hg") | Some(".svn") - ) -} - -fn walk_files_recursively( - dir: &Path, - visited_dirs: &mut HashSet, - should_descend: &mut G, - visit_file: &mut F, -) where - F: FnMut(&Path), - G: FnMut(&Path) -> bool, -{ - let canonical_dir = match std::fs::canonicalize(dir) { - Ok(path) => path, - Err(_) => return, - }; - - if !visited_dirs.insert(canonical_dir) { - return; - } - - let entries = match std::fs::read_dir(dir) { - Ok(e) => e, - Err(_) => return, - }; - - for entry in entries.flatten() { - let path = entry.path(); - if path.is_dir() { - if should_descend(&path) { - walk_files_recursively(&path, visited_dirs, should_descend, visit_file); - } - } else if path.is_file() { - visit_file(&path); - } - } -} - -fn scan_skills_from_dir( - dir: &Path, - global: bool, - writable: bool, - preserve_path: bool, - seen: &mut HashSet, -) -> Vec { - let mut skill_files = Vec::new(); - let mut visited_dirs = HashSet::new(); - - walk_files_recursively( - dir, - &mut visited_dirs, - &mut |path| !should_skip_dir(path), - &mut |path| { - if path.file_name().and_then(|name| name.to_str()) == Some("SKILL.md") { - skill_files.push(path.to_path_buf()); - } - }, - ); - - let mut sources = Vec::new(); - for skill_file in skill_files { - let Some(skill_dir) = skill_file.parent() else { - continue; - }; - let registered_skill_dir = if preserve_path { - skill_dir.to_path_buf() - } else { - let Ok(canonical_dir) = skill_dir.canonicalize() else { - continue; - }; - canonical_dir - }; - let content = match std::fs::read_to_string(&skill_file) { - Ok(c) => c, - Err(e) => { - warn!("Failed to read skill file {}: {}", skill_file.display(), e); - continue; - } - }; - - if let Some(mut source) = - parse_skill_content(&content, ®istered_skill_dir, global, writable) - { - if !seen.contains(&source.name) { - let mut files = Vec::new(); - let mut visited_support_dirs = HashSet::new(); - walk_files_recursively( - skill_dir, - &mut visited_support_dirs, - &mut |path| !should_skip_dir(path) && !path.join("SKILL.md").is_file(), - &mut |path| { - if path.file_name().and_then(|n| n.to_str()) != Some("SKILL.md") { - if let Ok(relative) = path.strip_prefix(skill_dir) { - files.push( - registered_skill_dir - .join(relative) - .to_string_lossy() - .into_owned(), - ); - } - } - }, - ); - source.supporting_files = files; - - seen.insert(source.name.clone()); - sources.push(source); - } - } - } - sources -} - /// Discover skills from all configured filesystem locations and built-ins. /// Each returned entry has `global` set according to the directory it was /// found in (or `true` for built-ins). @@ -611,20 +440,16 @@ pub fn discover_skills(working_dir: Option<&Path>) -> Vec { } fn discover_skills_with_config(working_dir: Option<&Path>, config: &Config) -> Vec { - let mut sources: Vec = Vec::new(); - let mut seen = HashSet::new(); - - for dir in all_skill_dirs_with_config(working_dir, config) { - for source in scan_skills_from_dir( - &dir.path, - dir.is_global, - dir.writable, - dir.preserve_path, - &mut seen, - ) { - sources.push(source); - } - } + let roots = all_skill_dirs_with_config(working_dir, config) + .into_iter() + .map(|dir| SkillRoot { + path: dir.path, + global: dir.is_global, + writable: dir.writable, + preserve_path: dir.preserve_path, + }); + let mut sources = goose_agent::skills::discover_skills(roots); + let mut seen: HashSet<_> = sources.iter().map(|source| source.name.clone()).collect(); for content in builtin::get_all() { if let Some(source) = parse_skill_content(content, &PathBuf::new(), true, true) {