feat: project scope as first-class extension dimension

.gitignore

@@ -8,6 +8,7 @@
 docs/
 .superpowers/
 .claude/
+.worktrees/
 branding/
 .impeccable.md
 .env*

crates/hk-core/src/adapter/antigravity.rs

@@ -54,6 +54,12 @@ impl AgentAdapter for AntigravityAdapter {
             self.home.join(".gemini").join("antigravity").join("skills"),
         ]
     }
+    fn project_skill_dirs(&self) -> Vec<String> {
+        // Antigravity workspace skills.
+        // SINGULAR ".agent/skills" (Antigravity convention) — NOT ".agents/skills".
+        // Source: https://codelabs.developers.google.com/getting-started-with-antigravity-skills
+        vec![".agent/skills".into()]
+    }
     fn mcp_config_path(&self) -> PathBuf {
         self.home
             .join(".gemini")

crates/hk-core/src/adapter/codex.rs

@@ -101,6 +101,12 @@ impl AgentAdapter for CodexAdapter {
         vec![".codex/config.toml".into()]
     }
 
+    fn project_skill_dirs(&self) -> Vec<String> {
+        // Codex CLI scans .agents/skills from cwd up to the repo root.
+        // Source: https://developers.openai.com/codex/skills
+        vec![".agents/skills".into()]
+    }
+
     fn read_mcp_servers(&self) -> Vec<McpServerEntry> {
         self.read_mcp_servers_from(&self.mcp_config_path())
     }

crates/hk-core/src/adapter/copilot.rs

@@ -117,6 +117,14 @@ impl AgentAdapter for CopilotAdapter {
             self.home.join(".agents").join("skills"),
         ]
     }
+    fn project_skill_dirs(&self) -> Vec<String> {
+        // GitHub Copilot Agent Skills (canonical path .github/skills; also accepts
+        // .claude/skills and .agents/skills aliases — declaring only the canonical
+        // here keeps scanner output deduplicated when other adapters declare those
+        // alias paths).
+        // Source: https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills
+        vec![".github/skills".into()]
+    }
     fn mcp_config_path(&self) -> PathBuf {
         self.vscode_user_dir().join("mcp.json")
     }

crates/hk-core/src/adapter/cursor.rs

@@ -59,6 +59,12 @@ impl AgentAdapter for CursorAdapter {
         ]
     }
 
+    fn project_skill_dirs(&self) -> Vec<String> {
+        // Cursor 2.4+ project skills.
+        // Source: https://cursor.com/docs/skills
+        vec![".cursor/skills".into()]
+    }
+
     fn mcp_config_path(&self) -> PathBuf {
         self.base_dir().join("mcp.json")
     }

crates/hk-core/src/adapter/gemini.rs

@@ -91,6 +91,13 @@ impl AgentAdapter for GeminiAdapter {
             self.home.join(".agents").join("skills"),
         ]
     }
+    fn project_skill_dirs(&self) -> Vec<String> {
+        // Gemini CLI workspace skills (also accepts .agents/skills as an alias —
+        // declaring only the canonical path here; cross-agent shared skills via
+        // .agents/skills are picked up by the Codex adapter naturally).
+        // Source: https://geminicli.com/docs/cli/skills/
+        vec![".gemini/skills".into()]
+    }
     fn mcp_config_path(&self) -> PathBuf {
         self.base_dir().join("settings.json")
     }

crates/hk-core/src/adapter/mod.rs

@@ -225,6 +225,21 @@ pub trait AgentAdapter: Send + Sync {
                 .map(|rel| std::path::Path::new(path).join(rel)),
         }
     }
+
+    /// Resolve the skill directory for a given scope.
+    /// - `Global` → first entry of `skill_dirs()` (today's behavior).
+    /// - `Project` → `<project>/<project_skill_dirs()[0]>`, or `None` if
+    ///   the adapter has no project-level skill support.
+    fn skill_dir_for(&self, scope: &ConfigScope) -> Option<std::path::PathBuf> {
+        match scope {
+            ConfigScope::Global => self.skill_dirs().into_iter().next(),
+            ConfigScope::Project { path, .. } => self
+                .project_skill_dirs()
+                .into_iter()
+                .next()
+                .map(|rel| std::path::Path::new(path).join(rel)),
+        }
+    }
 }
 
 /// Returns all agent adapters in canonical display order.
@@ -299,4 +314,81 @@ mod tests {
             let _ = a.project_workflow_patterns();
         }
     }
+
+    #[test]
+    fn test_skill_dir_for_global_matches_skill_dirs_first() {
+        let adapters = all_adapters();
+        for a in &adapters {
+            let global = ConfigScope::Global;
+            let computed = a.skill_dir_for(&global);
+            let expected = a.skill_dirs().into_iter().next();
+            assert_eq!(
+                computed,
+                expected,
+                "{} skill_dir_for(Global) should match skill_dirs()[0]",
+                a.name()
+            );
+        }
+    }
+
+    #[test]
+    fn test_skill_dir_for_project_joins_path_with_project_skill_dirs_first() {
+        let adapters = all_adapters();
+        let scope = ConfigScope::Project {
+            name: "demo".into(),
+            path: "/tmp/demo".into(),
+        };
+        for adapter in &adapters {
+            let computed = adapter.skill_dir_for(&scope);
+            let rel = adapter.project_skill_dirs().into_iter().next();
+            match (&computed, &rel) {
+                (Some(p), Some(r)) => {
+                    assert_eq!(p, &std::path::Path::new("/tmp/demo").join(r));
+                }
+                (None, None) => {} // adapter has no project skill support
+                _ => panic!(
+                    "{}: mismatched some/none: computed={computed:?} vs project_skill_dirs first={rel:?}",
+                    adapter.name()
+                ),
+            }
+        }
+    }
+
+    #[test]
+    fn test_every_adapter_declares_project_skill_dir() {
+        // Universal Agent Skills standard (Dec 2025) — every adapter must declare a
+        // project skill directory. If a future adapter genuinely has no project
+        // skill concept, drop it from this assertion explicitly.
+        let adapters = all_adapters();
+        for a in &adapters {
+            assert!(
+                !a.project_skill_dirs().is_empty(),
+                "{} must declare project_skill_dirs (Universal Agent Skills standard)",
+                a.name()
+            );
+        }
+    }
+
+    #[test]
+    fn test_project_skill_dir_paths_match_upstream_conventions() {
+        // Verify each adapter's first-party documented path. Update when adapter
+        // upstream conventions change.
+        let adapters = all_adapters();
+        let expected: std::collections::HashMap<&str, &str> = [
+            ("claude", ".claude/skills"),
+            ("codex", ".agents/skills"), // Universal alias adopted by OpenAI
+            ("cursor", ".cursor/skills"),
+            ("windsurf", ".windsurf/skills"),
+            ("gemini", ".gemini/skills"),
+            ("antigravity", ".agent/skills"), // Singular — Antigravity convention
+            ("copilot", ".github/skills"),
+        ]
+        .into_iter()
+        .collect();
+        for a in &adapters {
+            let actual = a.project_skill_dirs().into_iter().next().unwrap();
+            let want = expected.get(a.name()).expect("adapter not in expected map");
+            assert_eq!(&actual, want, "{} project skill path mismatch", a.name());
+        }
+    }
 }

crates/hk-core/src/adapter/windsurf.rs

@@ -68,6 +68,12 @@ impl AgentAdapter for WindsurfAdapter {
         ]
     }
 
+    fn project_skill_dirs(&self) -> Vec<String> {
+        // Windsurf Cascade workspace skills.
+        // Source: https://docs.windsurf.com/windsurf/cascade/skills
+        vec![".windsurf/skills".into()]
+    }
+
     fn mcp_config_path(&self) -> PathBuf {
         self.base_dir().join("mcp_config.json")
     }

crates/hk-core/src/error.rs

@@ -107,7 +107,7 @@ mod tests {
 
     #[test]
     fn test_from_io_error_other() {
-        let err = std::io::Error::new(std::io::ErrorKind::Other, "something else");
+        let err = std::io::Error::other("something else");
         let hk: HkError = err.into();
         assert!(matches!(hk, HkError::Internal(_)));
     }