Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

feat: add .well-known/agent-skills/ for web-based skill discovery (#1751)

worktrunk-bot7d663ea97d47
diff --git a/Cargo.lock b/Cargo.lock
index d982bb39c..1a48c083b 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3247,6 +3247,7 @@ dependencies = [
"schemars",
"serde",
"serde_json",
+ "sha2",
"shell-escape",
"shellexpand",
"signal-hook 0.4.3",
diff --git a/Cargo.toml b/Cargo.toml
index a03167baa..90d9766b8 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -148,6 +148,7 @@ vt100 = "0.16"
ansi-to-html = "0.2.2"
wt-perf = { path = "tests/helpers/wt-perf" }
similar = "2.7.0"
+sha2 = "0.10"
[[bench]]
name = "completion"
diff --git a/docs/static/.well-known/agent-skills/index.json b/docs/static/.well-known/agent-skills/index.json
new file mode 100644
index 000000000..8d21b99a8
--- /dev/null
+++ b/docs/static/.well-known/agent-skills/index.json
@@ -0,0 +1,12 @@
+{
+ "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
+ "skills": [
+ {
+ "name": "worktrunk",
+ "type": "skill-md",
+ "description": "Guidance for Worktrunk, a CLI tool for managing git worktrees. Covers configuration (user config at ~/.config/worktrunk/config.toml and project hooks at .config/wt.toml), usage, and troubleshooting. Use for \"setting up commit message generation\", \"configuring hooks\", \"automating tasks\", or general worktrunk questions.",
+ "url": "./worktrunk/SKILL.md",
+ "digest": "sha256:b6a3a35add094d9ae12707b72e581660d58083706aecd00eadb629aae2d41c18"
+ }
+ ]
+}
diff --git a/docs/static/.well-known/agent-skills/worktrunk b/docs/static/.well-known/agent-skills/worktrunk
new file mode 120000
index 000000000..2da0039ed
--- /dev/null
+++ b/docs/static/.well-known/agent-skills/worktrunk
@@ -0,0 +1 @@
+../../../../skills/worktrunk
\ No newline at end of file
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 150c8c162..07c7c2089 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -1820,7 +1820,85 @@ fn sync_skill_files(project_root: &Path) -> (Vec<String>, Vec<String>) {
(errors, updated_files)
}
+/// Sync .well-known/agent-skills/ index.json and verify symlink.
+///
+/// The skill files are served via a symlink:
+/// docs/static/.well-known/agent-skills/worktrunk → ../../../../skills/worktrunk
+///
+/// This function verifies the symlink is correct and generates index.json
+/// with the correct SHA-256 digest per the Cloudflare agent-skills-discovery RFC.
+fn sync_well_known_skills(project_root: &Path) -> Vec<String> {
+ let mut updated_files = Vec::new();
+
+ let well_known_dir = project_root.join("docs/static/.well-known/agent-skills");
+ let symlink_path = well_known_dir.join("worktrunk");
+
+ // Verify the symlink exists and points to the right place
+ let expected_target = Path::new("../../../../skills/worktrunk");
+ match fs::read_link(&symlink_path) {
+ Ok(target) => {
+ assert_eq!(
+ target,
+ expected_target,
+ "Symlink at {} points to {:?}, expected {:?}",
+ symlink_path.display(),
+ target,
+ expected_target
+ );
+ }
+ Err(_) => {
+ panic!(
+ "Expected symlink at {} → {:?}, but it doesn't exist or isn't a symlink",
+ symlink_path.display(),
+ expected_target
+ );
+ }
+ }
+
+ // Read SKILL.md (through the symlink) for digest and description
+ let skill_md_path = symlink_path.join("SKILL.md");
+ let skill_md_content = fs::read_to_string(&skill_md_path)
+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", skill_md_path.display(), e));
+
+ // Generate index.json with SHA-256 digest of SKILL.md
+ let digest = {
+ use sha2::{Digest, Sha256};
+ let file_bytes = fs::read(&skill_md_path)
+ .unwrap_or_else(|e| panic!("Failed to read {}: {}", skill_md_path.display(), e));
+ let hash = Sha256::digest(&file_bytes);
+ format!("sha256:{hash:x}")
+ };
+
+ // Parse the description from SKILL.md frontmatter
+ let description = skill_md_content
+ .strip_prefix("---\n")
+ .and_then(|rest| rest.split_once("\n---"))
+ .and_then(|(frontmatter, _)| {
+ frontmatter
+ .lines()
+ .find(|line| line.starts_with("description:"))
+ .map(|line| line.trim_start_matches("description:").trim().to_string())
+ })
+ .unwrap_or_default();
+
+ let index_json = format!(
+ "{{\n \"$schema\": \"https://schemas.agentskills.io/discovery/0.2.0/schema.json\",\n \"skills\": [\n {{\n \"name\": \"worktrunk\",\n \"type\": \"skill-md\",\n \"description\": {description},\n \"url\": \"./worktrunk/SKILL.md\",\n \"digest\": \"{digest}\"\n }}\n ]\n}}\n",
+ description = serde_json::to_string(&description).unwrap(),
+ );
+
+ let index_dst = well_known_dir.join("index.json");
+ let current_index = fs::read_to_string(&index_dst).unwrap_or_default();
+ if current_index != index_json {
+ fs::write(&index_dst, &index_json)
+ .unwrap_or_else(|e| panic!("Failed to write {}: {}", index_dst.display(), e));
+ updated_files.push("docs/static/.well-known/agent-skills/index.json".to_string());
+ }
+
+ updated_files
+}
+
/// Combined test: sync command pages (mod.rs → docs) then skill files (docs → skills)
+/// then .well-known/agent-skills/ (skills → docs/static).
/// This ensures a single test run handles the full chain when mod.rs changes.
#[test]
fn test_command_pages_and_skill_files_are_in_sync() {
@@ -1833,9 +1911,17 @@ fn test_command_pages_and_skill_files_are_in_sync() {
// This reads the freshly-written docs from step 1
let (skill_errors, skill_files) = sync_skill_files(project_root);
+ // Step 3: Sync .well-known/agent-skills/ (skills/ → docs/static/)
+ // This reads the freshly-written skills from step 2
+ let well_known_files = sync_well_known_skills(project_root);
+
// Aggregate results
let all_errors: Vec<_> = cmd_errors.into_iter().chain(skill_errors).collect();
- let all_files: Vec<_> = cmd_files.into_iter().chain(skill_files).collect();
+ let all_files: Vec<_> = cmd_files
+ .into_iter()
+ .chain(skill_files)
+ .chain(well_known_files)
+ .collect();
if !all_errors.is_empty() {
panic!("Sync errors:\n\n{}\n", all_errors.join("\n"));