move skills discovery into GDK (#12935)

This commit is contained in:
Jack Amadeo
2026-10-16 15:42:50 +00:00
committed by GitHub
parent 1b12093f06
commit 435868bf20
8 changed files with 386 additions and 192 deletions
Generated
+3
View File
@@ -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",
+6 -1
View File
@@ -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
+8
View File
@@ -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,
+1
View File
@@ -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;
@@ -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<Vec<String>> {
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<Regex> = LazyLock::new(|| {
Regex::new(
r"\$ARGUMENTS\[(?P<idx>\d+)\]|\$ARGUMENTS\b|\$(?P<pos>\d+)|\$(?P<name>[A-Za-z_][A-Za-z0-9_-]*)",
+247
View File
@@ -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<String>,
#[serde(default)]
description: String,
#[serde(default)]
metadata: HashMap<String, Value>,
}
fn parse_frontmatter<T: for<'de> Deserialize<'de>>(
content: &str,
) -> Result<Option<(T, String)>, 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<SourceEntry> {
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<F, G>(
dir: &Path,
visited_dirs: &mut HashSet<PathBuf>,
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<String>,
) -> Vec<SourceEntry> {
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, &registered_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<Item = SkillRoot>) -> Vec<SourceEntry> {
let mut sources: Vec<SourceEntry> = 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
}
+74
View File
@@ -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<String> {
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<String> {
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
}
+15 -190
View File
@@ -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<String> {
pub fn loaded_skill_context_with_args(skill: &SourceEntry, args: Option<&str>) -> Result<String> {
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<String> {
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<String> {
@@ -178,22 +140,6 @@ pub fn skill_argument_hint(skill: &SourceEntry) -> Option<String> {
.map(str::to_string)
}
pub fn skill_argument_names(skill: &SourceEntry) -> Vec<String> {
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<F, G>(
dir: &Path,
visited_dirs: &mut HashSet<PathBuf>,
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<String>,
) -> Vec<SourceEntry> {
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, &registered_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<SourceEntry> {
}
fn discover_skills_with_config(working_dir: Option<&Path>, config: &Config) -> Vec<SourceEntry> {
let mut sources: Vec<SourceEntry> = 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) {