M5: skills (SKILL.md and skill tool)

Adds harness-core::config::markdown to parse SKILL.md frontmatter/body, a skill tool in harness-tools to invoke them, and system-prompt wiring so available skills are advertised to the model. Includes the rustfmt pass over the M5 files touched by this and the preceding LSP/rmcp work.

crates/harness-app/src/lib.rs

@@ -159,6 +159,9 @@ struct EngineInner {
     /// LSP diagnostics pool (edit/write surface errors). Shared across sessions; servers spawn
     /// lazily on first touch.
     diagnostics: Option<Arc<dyn DiagnosticsSource>>,
+    /// Pre-rendered "## Skills" system block (name + description), injected into every run.
+    /// `None` when no skills are configured.
+    skills_prompt: Option<String>,
     cwd: PathBuf,
     data_dir: PathBuf,
     runs: Mutex<HashMap<SessionId, RunHandle>>,
@@ -217,6 +220,14 @@ impl EngineHandle {
             tools.register(tool);
         }
 
+        // Skills: layered global + project markdown, advertised in the system prompt and pulled
+        // on demand by the `skill` tool (only registered when at least one skill exists).
+        let global_skill_dir = dirs::config_dir().map(|d| d.join("ai-harness").join("skill"));
+        let project_skill_dir = cwd.join(".harness").join("skill");
+        let skills = config::load_skills(global_skill_dir.as_deref(), Some(&project_skill_dir));
+        harness_tools::register_skill_tool(&mut tools, &skills);
+        let skills_prompt = config::skills_prompt(&skills);
+
         // Layered agent registry: bundled markdown → global dir → project dir → config patches.
         let global_agent_dir = dirs::config_dir().map(|d| d.join("ai-harness").join("agent"));
         let project_agent_dir = cwd.join(".harness").join("agent");
@@ -259,6 +270,7 @@ impl EngineHandle {
             catalog,
             agents,
             diagnostics,
+            skills_prompt,
             cwd,
             data_dir,
             runs: Mutex::new(HashMap::new()),
@@ -395,6 +407,7 @@ impl EngineHandle {
             inject_job_board,
             reminder_turn_start: self.inner.reminder("turn_start"),
             reminder_after_file_tool: self.inner.reminder("after_file_tool"),
+            skills_prompt: self.inner.skills_prompt.clone(),
         };
 
         // Reserve the run slot *before* spawning. If we inserted after spawning, a run that
@@ -807,6 +820,7 @@ impl SubagentSpawner for EngineInner {
             inject_job_board: agent.mode.is_primary(),
             reminder_turn_start: self.reminder("turn_start"),
             reminder_after_file_tool: self.reminder("after_file_tool"),
+            skills_prompt: self.skills_prompt.clone(),
         };
 
         // Register the launch on the parent board (also makes foreground results reusable).
@@ -1321,6 +1335,25 @@ mod tests {
         assert_eq!(app.engine.inner.tools.all().len(), 7);
     }
 
+    #[tokio::test]
+    async fn project_skill_registers_the_skill_tool_and_advertises_it() {
+        let dir = tempfile::tempdir().unwrap();
+        let skill_dir = dir.path().join(".harness").join("skill").join("fmt");
+        std::fs::create_dir_all(&skill_dir).unwrap();
+        std::fs::write(
+            skill_dir.join("SKILL.md"),
+            "---\ndescription: format the code\n---\nRun cargo fmt.",
+        )
+        .unwrap();
+
+        let engine = EngineHandle::init_in_memory(dir.path().to_path_buf()).unwrap();
+        // 6 built-ins + task + skill.
+        assert_eq!(engine.inner.tools.all().len(), 8);
+        assert!(engine.inner.tools.get("skill").is_some());
+        let prompt = engine.inner.skills_prompt.clone().expect("skills advertised");
+        assert!(prompt.contains("**fmt** — format the code"));
+    }
+
     #[tokio::test]
     async fn run_prompt_errors_on_unregistered_provider() {
         let dir = tempfile::tempdir().unwrap();

crates/harness-core/src/config/markdown.rs

@@ -0,0 +1,296 @@
+//! Markdown-defined commands and skills (M5). Both are YAML-frontmatter + body files loaded
+//! from a global dir (`~/.config/ai-harness/<kind>/`) and a project dir (`<project>/.harness/
+//! <kind>/`), project winning by name. See `docs/06-config.md` and `docs/09-integrations.md`.
+//!
+//! - Commands (`command/*.md`) are a pure input-layer concern: `/name args` expands the body
+//!   template (`$ARGUMENTS`, `$1..$9`) into the user message, optionally switching agent/model.
+//! - Skills (`skill/<name>/SKILL.md`) advertise `name + description` in the system prompt; the
+//!   model pulls a skill's body on demand via the built-in `skill` tool.
+
+use std::collections::HashMap;
+use std::path::Path;
+
+use serde::Deserialize;
+
+/// A slash command: a named prompt template with an optional agent/model override.
+#[derive(Debug, Clone, PartialEq)]
+pub struct CommandDef {
+    /// Invocation name (the file stem); used as `/name`.
+    pub name: String,
+    pub description: String,
+    /// Run the expanded prompt under this agent instead of the session's default.
+    pub agent: Option<String>,
+    /// Run under this `provider/model` instead of the session's default.
+    pub model: Option<String>,
+    /// The body, with `$ARGUMENTS` / `$1..$9` placeholders.
+    pub template: String,
+}
+
+impl CommandDef {
+    /// Substitutes `$ARGUMENTS` (the whole argument string) and `$1..$9` (whitespace-split
+    /// positionals; missing ones become empty) into the template.
+    pub fn expand(&self, arguments: &str) -> String {
+        let positionals: Vec<&str> = arguments.split_whitespace().collect();
+        let mut out = self.template.replace("$ARGUMENTS", arguments);
+        for i in 1..=9 {
+            let value = positionals.get(i - 1).copied().unwrap_or("");
+            out = out.replace(&format!("${i}"), value);
+        }
+        out
+    }
+}
+
+/// A skill: advertised by `name + description`, body loaded on demand by the `skill` tool.
+#[derive(Debug, Clone, PartialEq)]
+pub struct SkillDef {
+    /// Skill name (the containing directory name); used as the `skill` tool argument.
+    pub name: String,
+    pub description: String,
+    pub body: String,
+}
+
+/// Frontmatter fields shared by commands (all optional).
+#[derive(Debug, Default, Deserialize)]
+#[serde(default)]
+struct CommandFrontmatter {
+    description: Option<String>,
+    agent: Option<String>,
+    model: Option<String>,
+}
+
+#[derive(Debug, Default, Deserialize)]
+#[serde(default)]
+struct SkillFrontmatter {
+    description: Option<String>,
+}
+
+/// Splits `---\n…\n---\n` frontmatter from the body. A file with no leading fence is all body.
+fn split_frontmatter(content: &str) -> (&str, &str) {
+    let rest = match content
+        .strip_prefix("---\n")
+        .or_else(|| content.strip_prefix("---\r\n"))
+    {
+        Some(r) => r,
+        None => return ("", content),
+    };
+    for delim in ["\n---\n", "\n---\r\n"] {
+        if let Some(idx) = rest.find(delim) {
+            return (&rest[..idx], &rest[idx + delim.len()..]);
+        }
+    }
+    if rest.ends_with("\n---") {
+        return (rest.trim_end_matches("\n---"), "");
+    }
+    ("", content)
+}
+
+fn parse_command(name: &str, content: &str) -> CommandDef {
+    let (fm_raw, body) = split_frontmatter(content);
+    let fm: CommandFrontmatter = if fm_raw.trim().is_empty() {
+        CommandFrontmatter::default()
+    } else {
+        serde_yaml_ng::from_str(fm_raw).unwrap_or_default()
+    };
+    CommandDef {
+        name: name.to_string(),
+        description: fm.description.unwrap_or_default(),
+        agent: fm.agent,
+        model: fm.model,
+        template: body.trim().to_string(),
+    }
+}
+
+fn parse_skill(name: &str, content: &str) -> SkillDef {
+    let (fm_raw, body) = split_frontmatter(content);
+    let fm: SkillFrontmatter = if fm_raw.trim().is_empty() {
+        SkillFrontmatter::default()
+    } else {
+        serde_yaml_ng::from_str(fm_raw).unwrap_or_default()
+    };
+    SkillDef {
+        name: name.to_string(),
+        description: fm.description.unwrap_or_default(),
+        body: body.trim().to_string(),
+    }
+}
+
+/// Loads `command/*.md` from global then project dirs (project wins by name).
+pub fn load_commands(
+    global_dir: Option<&Path>,
+    project_dir: Option<&Path>,
+) -> HashMap<String, CommandDef> {
+    let mut commands = HashMap::new();
+    for dir in [global_dir, project_dir].into_iter().flatten() {
+        let Ok(entries) = std::fs::read_dir(dir) else {
+            continue;
+        };
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.extension().and_then(|e| e.to_str()) != Some("md") {
+                continue;
+            }
+            let Some(name) = path.file_stem().and_then(|s| s.to_str()) else {
+                continue;
+            };
+            if let Ok(content) = std::fs::read_to_string(&path) {
+                commands.insert(name.to_string(), parse_command(name, &content));
+            }
+        }
+    }
+    commands
+}
+
+/// Loads `skill/<name>/SKILL.md` from global then project dirs (project wins by name),
+/// returned name-sorted for a stable system-prompt listing.
+pub fn load_skills(global_dir: Option<&Path>, project_dir: Option<&Path>) -> Vec<SkillDef> {
+    let mut by_name: HashMap<String, SkillDef> = HashMap::new();
+    for dir in [global_dir, project_dir].into_iter().flatten() {
+        let Ok(entries) = std::fs::read_dir(dir) else {
+            continue;
+        };
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if !path.is_dir() {
+                continue;
+            }
+            let Some(name) = path.file_name().and_then(|s| s.to_str()) else {
+                continue;
+            };
+            let skill_file = path.join("SKILL.md");
+            if let Ok(content) = std::fs::read_to_string(&skill_file) {
+                by_name.insert(name.to_string(), parse_skill(name, &content));
+            }
+        }
+    }
+    let mut skills: Vec<SkillDef> = by_name.into_values().collect();
+    skills.sort_by(|a, b| a.name.cmp(&b.name));
+    skills
+}
+
+/// The system-prompt section advertising available skills (name + description). `None` when
+/// there are no skills, so no empty section is injected.
+pub fn skills_prompt(skills: &[SkillDef]) -> Option<String> {
+    if skills.is_empty() {
+        return None;
+    }
+    let mut section = String::from(
+        "## Skills\n\nThese skills are available. Load a skill's full instructions on demand \
+         by calling the `skill` tool with its name before doing the related work:\n",
+    );
+    for skill in skills {
+        section.push_str(&format!("- **{}** — {}\n", skill.name, skill.description));
+    }
+    Some(section.trim_end().to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn expand_substitutes_arguments_and_positionals() {
+        let cmd = CommandDef {
+            name: "greet".into(),
+            description: String::new(),
+            agent: None,
+            model: None,
+            template: "Say $1 to $2. All: $ARGUMENTS".into(),
+        };
+        assert_eq!(cmd.expand("hi there"), "Say hi to there. All: hi there");
+        // Missing positionals collapse to empty.
+        assert_eq!(cmd.expand("solo"), "Say solo to . All: solo");
+    }
+
+    #[test]
+    fn parse_command_reads_frontmatter_and_body() {
+        let md = "---\ndescription: review a PR\nagent: oracle\nmodel: openai/gpt-5\n---\nReview $ARGUMENTS please.\n";
+        let cmd = parse_command("review", md);
+        assert_eq!(cmd.description, "review a PR");
+        assert_eq!(cmd.agent.as_deref(), Some("oracle"));
+        assert_eq!(cmd.model.as_deref(), Some("openai/gpt-5"));
+        assert_eq!(cmd.template, "Review $ARGUMENTS please.");
+    }
+
+    #[test]
+    fn parse_command_without_frontmatter_is_all_template() {
+        let cmd = parse_command("x", "just do $1");
+        assert_eq!(cmd.template, "just do $1");
+        assert!(cmd.agent.is_none());
+    }
+
+    #[test]
+    fn parse_skill_reads_description_and_body() {
+        let md = "---\ndescription: format code\n---\nRun the formatter.\n";
+        let skill = parse_skill("formatter", md);
+        assert_eq!(skill.name, "formatter");
+        assert_eq!(skill.description, "format code");
+        assert_eq!(skill.body, "Run the formatter.");
+    }
+
+    #[test]
+    fn skills_prompt_lists_each_and_is_none_when_empty() {
+        assert!(skills_prompt(&[]).is_none());
+        let skills = vec![
+            SkillDef {
+                name: "a".into(),
+                description: "does a".into(),
+                body: "…".into(),
+            },
+            SkillDef {
+                name: "b".into(),
+                description: "does b".into(),
+                body: "…".into(),
+            },
+        ];
+        let prompt = skills_prompt(&skills).unwrap();
+        assert!(prompt.contains("- **a** — does a"));
+        assert!(prompt.contains("- **b** — does b"));
+    }
+
+    #[test]
+    fn load_skills_reads_skill_dirs_and_project_wins() {
+        let dir = tempfile::tempdir().unwrap();
+        let global = dir.path().join("global");
+        let project = dir.path().join("project");
+        std::fs::create_dir_all(global.join("fmt")).unwrap();
+        std::fs::create_dir_all(project.join("fmt")).unwrap();
+        std::fs::create_dir_all(global.join("lint")).unwrap();
+        std::fs::write(
+            global.join("fmt/SKILL.md"),
+            "---\ndescription: global fmt\n---\nglobal body",
+        )
+        .unwrap();
+        std::fs::write(
+            project.join("fmt/SKILL.md"),
+            "---\ndescription: project fmt\n---\nproject body",
+        )
+        .unwrap();
+        std::fs::write(
+            global.join("lint/SKILL.md"),
+            "---\ndescription: lint\n---\nlint body",
+        )
+        .unwrap();
+
+        let skills = load_skills(Some(&global), Some(&project));
+        assert_eq!(skills.len(), 2);
+        // Sorted by name: fmt, lint.
+        assert_eq!(skills[0].name, "fmt");
+        assert_eq!(skills[0].description, "project fmt"); // project overrode global
+        assert_eq!(skills[0].body, "project body");
+        assert_eq!(skills[1].name, "lint");
+    }
+
+    #[test]
+    fn load_commands_project_overrides_global() {
+        let dir = tempfile::tempdir().unwrap();
+        let global = dir.path().join("g");
+        let project = dir.path().join("p");
+        std::fs::create_dir_all(&global).unwrap();
+        std::fs::create_dir_all(&project).unwrap();
+        std::fs::write(global.join("deploy.md"), "global deploy").unwrap();
+        std::fs::write(project.join("deploy.md"), "project deploy").unwrap();
+        let commands = load_commands(Some(&global), Some(&project));
+        assert_eq!(commands.len(), 1);
+        assert_eq!(commands["deploy"].template, "project deploy");
+    }
+}

crates/harness-core/src/config/mod.rs

@@ -1,7 +1,9 @@
 pub mod load;
+pub mod markdown;
 pub mod schema;
 
 pub use load::{load, ConfigError};
+pub use markdown::{load_commands, load_skills, skills_prompt, CommandDef, SkillDef};
 pub use schema::{
     AgentPatch, Config, LspServerConfig, McpServerConfig, OrchestrationConfig, ProviderConfig,
     TuiConfig,

crates/harness-core/src/engine/loop.rs

@@ -28,6 +28,8 @@ pub struct RunConfig {
     pub reminder_turn_start: Option<String>,
     /// Optional user-provided reminder injected on the turn after a file tool ran.
     pub reminder_after_file_tool: Option<String>,
+    /// Pre-rendered "## Skills" system block advertising loadable skills. `None` = no skills.
+    pub skills_prompt: Option<String>,
 }
 
 /// Adds a step's usage/cost onto the persisted session and republishes it. Cost accounting is
@@ -240,6 +242,7 @@ pub async fn run_session(
         let system_blocks = system::assemble(
             system::env_header(&ctx.cwd),
             &run_config.agent_prompt,
+            run_config.skills_prompt.as_deref(),
             &run_config.instructions,
         );
         let tools: Vec<ToolSchema> = ctx
@@ -519,6 +522,7 @@ mod tests {
             inject_job_board: false,
             reminder_turn_start: None,
             reminder_after_file_tool: None,
+            skills_prompt: None,
         };
 
         let outcome = run_session(Arc::new(provider), ctx, &run_config, || 2).await;
@@ -629,6 +633,7 @@ mod tests {
             inject_job_board: false,
             reminder_turn_start: None,
             reminder_after_file_tool: None,
+            skills_prompt: None,
         };
 
         let outcome = run_session(Arc::new(provider), ctx, &run_config, || 2).await;
@@ -736,6 +741,7 @@ mod tests {
             inject_job_board: true,
             reminder_turn_start: None,
             reminder_after_file_tool: None,
+            skills_prompt: None,
         };
 
         let provider = std::sync::Arc::new(CapturingProvider {
@@ -803,6 +809,7 @@ mod tests {
             inject_job_board: false,
             reminder_turn_start: Some("REMEMBER: stay on task.".into()),
             reminder_after_file_tool: None,
+            skills_prompt: None,
         };
 
         let provider = std::sync::Arc::new(CapturingProvider {

crates/harness-core/src/engine/system.rs

@@ -25,10 +25,18 @@ pub fn env_header(cwd: &Path) -> String {
     header
 }
 
-/// Ordered system prompt blocks: environment header, agent prompt, then project
-/// instructions (e.g. AGENTS.md contents). Order matches `02-engine.md`.
-pub fn assemble(env_header: String, agent_prompt: &str, instructions: &[String]) -> Vec<String> {
+/// Ordered system prompt blocks: environment header, agent prompt, the optional skills
+/// listing, then project instructions (e.g. AGENTS.md contents). Order matches `02-engine.md`.
+pub fn assemble(
+    env_header: String,
+    agent_prompt: &str,
+    skills: Option<&str>,
+    instructions: &[String],
+) -> Vec<String> {
     let mut blocks = vec![env_header, agent_prompt.to_string()];
+    if let Some(skills) = skills {
+        blocks.push(skills.to_string());
+    }
     blocks.extend(instructions.iter().cloned());
     blocks
 }
@@ -49,8 +57,20 @@ mod tests {
         let blocks = assemble(
             "ENV".to_string(),
             "AGENT",
+            None,
             &["AGENTS.md contents".to_string()],
         );
         assert_eq!(blocks, vec!["ENV", "AGENT", "AGENTS.md contents"]);
     }
+
+    #[test]
+    fn assemble_inserts_skills_after_agent_before_instructions() {
+        let blocks = assemble(
+            "ENV".to_string(),
+            "AGENT",
+            Some("SKILLS"),
+            &["INSTR".to_string()],
+        );
+        assert_eq!(blocks, vec!["ENV", "AGENT", "SKILLS", "INSTR"]);
+    }
 }

crates/harness-lsp/src/lib.rs

@@ -162,7 +162,10 @@ impl DiagnosticsSource for LspPool {
         let Some(client) = self.client_for(&server).await else {
             return;
         };
-        let ext = path.extension().and_then(|e| e.to_str()).unwrap_or_default();
+        let ext = path
+            .extension()
+            .and_then(|e| e.to_str())
+            .unwrap_or_default();
         let language_id = language_id_for_ext(ext);
 
         let existing_version = {

crates/harness-lsp/tests/rust_analyzer.rs

@@ -19,7 +19,11 @@ async fn rust_analyzer_reports_a_type_error() {
     .unwrap();
     std::fs::create_dir_all(dir.path().join("src")).unwrap();
     let main_rs = dir.path().join("src/main.rs");
-    std::fs::write(&main_rs, "fn main() {\n    let x: i32 = \"not an integer\";\n    let _ = x;\n}\n").unwrap();
+    std::fs::write(
+        &main_rs,
+        "fn main() {\n    let x: i32 = \"not an integer\";\n    let _ = x;\n}\n",
+    )
+    .unwrap();
 
     let pool = LspPool::new(dir.path().to_path_buf(), vec![]);
     pool.touch(&main_rs).await;

crates/harness-mcp/src/lib.rs

@@ -248,7 +248,10 @@ mod tests {
     #[test]
     fn qualified_name_prefixes_and_sanitizes() {
         assert_eq!(qualified_name("fs", "read_file"), "fs_read_file");
-        assert_eq!(qualified_name("my.server", "do/thing"), "my_server_do_thing");
+        assert_eq!(
+            qualified_name("my.server", "do/thing"),
+            "my_server_do_thing"
+        );
     }
 
     #[test]

crates/harness-tools/src/diagnostics.rs

@@ -14,7 +14,12 @@ const DIAGNOSTICS_WAIT: Duration = Duration::from_millis(1500);
 
 /// Touches `path` in the language server and appends error-severity diagnostics to `output`
 /// (both as a human-readable block in the text and the full set in metadata under `diagnostics`).
-pub async fn append_diagnostics(ctx: &ToolCtx, path: &Path, display_name: &str, output: &mut ToolOutput) {
+pub async fn append_diagnostics(
+    ctx: &ToolCtx,
+    path: &Path,
+    display_name: &str,
+    output: &mut ToolOutput,
+) {
     let Some(source) = &ctx.diagnostics else {
         return;
     };

crates/harness-tools/src/lib.rs

@@ -5,6 +5,7 @@ mod glob;
 mod grep;
 mod paths;
 mod read;
+mod skill;
 mod task;
 mod write;
 
@@ -13,6 +14,7 @@ pub use edit::EditTool;
 pub use glob::GlobTool;
 pub use grep::GrepTool;
 pub use read::ReadTool;
+pub use skill::SkillTool;
 pub use task::TaskTool;
 pub use write::WriteTool;
 
@@ -36,3 +38,11 @@ pub fn register_builtins(registry: &mut ToolRegistry) {
 pub fn register_task_tool(registry: &mut ToolRegistry) {
     registry.register(Arc::new(TaskTool));
 }
+
+/// Registers the `skill` tool (M5) over a loaded skill set. No-op when there are no skills,
+/// so the tool is only advertised when something can be loaded.
+pub fn register_skill_tool(registry: &mut ToolRegistry, skills: &[harness_core::config::SkillDef]) {
+    if !skills.is_empty() {
+        registry.register(Arc::new(SkillTool::new(skills)));
+    }
+}

crates/harness-tools/src/skill.rs

@@ -0,0 +1,154 @@
+//! The `skill` tool (M5): the system prompt advertises each skill's name + description; when
+//! the model decides a skill is relevant it calls this tool with the skill name to pull the
+//! full instructions on demand. See `docs/09-integrations.md`.
+
+use std::collections::HashMap;
+
+use async_trait::async_trait;
+use harness_core::config::SkillDef;
+use harness_core::tool::{Tool, ToolCtx, ToolError, ToolOutput};
+use schemars::JsonSchema;
+use serde::Deserialize;
+
+#[derive(Debug, Deserialize, JsonSchema)]
+struct SkillParams {
+    /// The name of the skill to load, as advertised in the system prompt.
+    name: String,
+}
+
+/// Serves skill bodies by name. Built from the loaded skill set; if there are no skills the
+/// caller simply doesn't register the tool.
+pub struct SkillTool {
+    /// name → (description, body).
+    skills: HashMap<String, (String, String)>,
+    /// Sorted names, for a stable "unknown skill" hint.
+    names: Vec<String>,
+    description: String,
+}
+
+impl SkillTool {
+    pub fn new(skills: &[SkillDef]) -> Self {
+        let mut names: Vec<String> = skills.iter().map(|s| s.name.clone()).collect();
+        names.sort();
+        let map = skills
+            .iter()
+            .map(|s| (s.name.clone(), (s.description.clone(), s.body.clone())))
+            .collect();
+        let description = format!(
+            "Load the full instructions for a named skill before doing the related work. \
+             Available skills: {}.",
+            names.join(", ")
+        );
+        Self {
+            skills: map,
+            names,
+            description,
+        }
+    }
+}
+
+#[async_trait]
+impl Tool for SkillTool {
+    fn name(&self) -> &str {
+        "skill"
+    }
+
+    fn description(&self) -> &str {
+        &self.description
+    }
+
+    fn parameters(&self) -> serde_json::Value {
+        serde_json::to_value(schemars::schema_for!(SkillParams)).unwrap()
+    }
+
+    async fn execute(
+        &self,
+        input: serde_json::Value,
+        _ctx: ToolCtx,
+    ) -> Result<ToolOutput, ToolError> {
+        let params: SkillParams =
+            serde_json::from_value(input).map_err(|e| ToolError::Invalid(e.to_string()))?;
+        match self.skills.get(&params.name) {
+            Some((_description, body)) => Ok(ToolOutput::new(
+                format!("skill: {}", params.name),
+                body.clone(),
+            )),
+            None => Err(ToolError::Invalid(format!(
+                "unknown skill {:?}; available: {}",
+                params.name,
+                self.names.join(", ")
+            ))),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use harness_core::event::EventBus;
+    use harness_core::permission::{spawn_auto_approve, PermissionService};
+    use harness_core::tool::{MetadataSink, PermissionHandle};
+    use harness_core::types::SessionId;
+    use std::sync::{Arc, Mutex};
+    use tokio_util::sync::CancellationToken;
+
+    fn ctx() -> ToolCtx {
+        let bus = EventBus::new();
+        let service = Arc::new(PermissionService::new(bus.clone()));
+        spawn_auto_approve(bus, service.clone());
+        let (metadata, _rx) = MetadataSink::channel();
+        ToolCtx {
+            session_id: SessionId::new(),
+            message_id: harness_core::types::MessageId::new(),
+            call_id: "c1".into(),
+            data_dir: std::env::temp_dir(),
+            cwd: std::env::temp_dir(),
+            cancel: CancellationToken::new(),
+            ask: PermissionHandle::new(
+                service,
+                SessionId::new(),
+                Vec::new(),
+                Arc::new(Mutex::new(Vec::new())),
+                CancellationToken::new(),
+            ),
+            metadata,
+            spawner: None,
+            context_reporter: None,
+            diagnostics: None,
+        }
+    }
+
+    fn sample() -> Vec<SkillDef> {
+        vec![SkillDef {
+            name: "formatter".into(),
+            description: "format code".into(),
+            body: "Run cargo fmt.".into(),
+        }]
+    }
+
+    #[tokio::test]
+    async fn returns_skill_body_by_name() {
+        let tool = SkillTool::new(&sample());
+        let out = tool
+            .execute(serde_json::json!({"name": "formatter"}), ctx())
+            .await
+            .unwrap();
+        assert_eq!(out.output, "Run cargo fmt.");
+    }
+
+    #[tokio::test]
+    async fn unknown_skill_is_an_input_error() {
+        let tool = SkillTool::new(&sample());
+        let err = tool
+            .execute(serde_json::json!({"name": "nope"}), ctx())
+            .await
+            .unwrap_err();
+        assert!(matches!(err, ToolError::Invalid(_)));
+    }
+
+    #[test]
+    fn description_lists_available_skills() {
+        let tool = SkillTool::new(&sample());
+        assert!(tool.description().contains("formatter"));
+    }
+}