feat: add skill install CLI command

Install a SKILL.md file that teaches AI agents how to use the ascend-tools
CLI. The skill template is embedded in the binary via include_str!() and
written to <target>/ascend-tools/SKILL.md.

Usage: ascend-tools skill install --target ./.claude/skills

No authentication required. Runs before config/client initialization.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: lostmygithubaccount

CLAUDE.md

@@ -32,7 +32,8 @@ src/ascend_tools/
 │   └── src/
 │       ├── lib.rs           # pub fn run(args) — testable entry point
 │       ├── main.rs          # binary entry point
-│       └── cli.rs           # clap commands, table/json output, print_table helper
+│       ├── cli.rs           # clap commands, table/json output, print_table helper
+│       └── skill.md         # SKILL.md template (embedded via include_str!, installed by `skill install`)
 │
 └── ascend-tools-py/           # PyO3 binding crate (cdylib, built by maturin)
     └── src/
@@ -103,6 +104,8 @@ ascend-tools [-o text|json] [-V]
   flow list-runs -r/--runtime <UUID> [--status, -f/--flow-name]
   flow get-run <RUN_NAME> -r/--runtime <UUID>
 
+  skill install --target <PATH>
+
   mcp [--http] [--bind <ADDR>]
 ```
 
@@ -208,6 +211,7 @@ The SDK/CLI calls the Instance API's `/api/v1/` endpoints, defined in `ascend-ba
 - MCP tool parameters use `schemars` `JsonSchema` derive for automatic JSON Schema generation; doc comments on fields become schema descriptions
 - MCP `FlowRunSpec` uses `#[serde(flatten)]` with a catch-all map for forward compatibility with new backend fields
 - PyO3 `run()` uses `py.detach()` to release the GIL during long-running Rust calls (MCP server)
+- When adding or changing CLI commands, update `src/ascend_tools/ascend-tools-cli/src/skill.md` to keep the skill in sync
 
 ## related repos
 

src/ascend_tools/ascend-tools-cli/src/cli.rs

@@ -1,9 +1,10 @@
-use anyhow::Result;
+use anyhow::{Context, Result};
 use ascend_tools::client::AscendClient;
 use ascend_tools::config::Config;
 use ascend_tools::models::*;
 use clap::{CommandFactory, Parser, Subcommand, ValueEnum};
 use std::ffi::OsString;
+use std::path::PathBuf;
 
 #[derive(Parser)]
 #[command(name = "ascend-tools", version, about = "CLI for the Ascend REST API")]
@@ -54,6 +55,11 @@ enum Commands {
         #[arg(long, default_value = "127.0.0.1:8000")]
         bind: String,
     },
+    /// Manage skills
+    Skill {
+        #[command(subcommand)]
+        command: Option<SkillCommands>,
+    },
 }
 
 #[derive(Subcommand)]
@@ -132,6 +138,19 @@ enum FlowCommands {
     },
 }
 
+#[derive(Subcommand)]
+enum SkillCommands {
+    /// Install the ascend-tools skill
+    #[command(arg_required_else_help = true)]
+    Install {
+        /// Target directory
+        ///
+        /// Examples: ./.claude/skills, ~/.claude/skills, ./.agents/skills
+        #[arg(long, required = true)]
+        target: String,
+    },
+}
+
 pub fn run<I, T>(args: I) -> Result<()>
 where
     I: IntoIterator<Item = T>,
@@ -144,6 +163,11 @@ where
         return Ok(());
     };
 
+    // Commands that don't require authentication
+    if let Commands::Skill { command } = command {
+        return handle_skill(command);
+    }
+
     let config = Config::with_overrides(
         cli.service_account_id.as_deref(),
         cli.service_account_key.as_deref(),
@@ -164,7 +188,7 @@ where
     match command {
         Commands::Runtime { command } => handle_runtime(&client, command, &cli.output),
         Commands::Flow { command } => handle_flow(&client, command, &cli.output),
-        Commands::Mcp { .. } => unreachable!(),
+        Commands::Mcp { .. } | Commands::Skill { .. } => unreachable!(),
     }
 }
 
@@ -350,6 +374,39 @@ fn handle_flow(
     Ok(())
 }
 
+// -- skill --
+
+const SKILL_CONTENT: &str = include_str!("skill.md");
+
+fn handle_skill(cmd: Option<SkillCommands>) -> Result<()> {
+    let Some(cmd) = cmd else {
+        Cli::command()
+            .find_subcommand_mut("skill")
+            .expect("skill subcommand exists")
+            .print_help()?;
+        return Ok(());
+    };
+    match cmd {
+        SkillCommands::Install { target } => {
+            let target = if target.starts_with('~') {
+                let home = std::env::var("HOME").context("HOME environment variable not set")?;
+                PathBuf::from(target.replacen('~', &home, 1))
+            } else {
+                PathBuf::from(&target)
+            };
+            let dir = target.join("ascend-tools");
+            std::fs::create_dir_all(&dir)
+                .with_context(|| format!("failed to create directory {}", dir.display()))?;
+            let path = dir.join("SKILL.md");
+            std::fs::write(&path, SKILL_CONTENT)
+                .with_context(|| format!("failed to write {}", path.display()))?;
+            let abs = std::fs::canonicalize(&path).unwrap_or(path);
+            println!("Installed ascend-tools skill to {}", abs.display());
+            Ok(())
+        }
+    }
+}
+
 // -- output helpers --
 
 fn print_json<T: serde::Serialize>(value: &T) -> Result<()> {
@@ -543,6 +600,23 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_cli_parses_skill_install() {
+        let cli = Cli::parse_from([
+            "ascend-tools",
+            "skill",
+            "install",
+            "--target",
+            "./.claude/skills",
+        ]);
+        assert!(matches!(
+            cli.command,
+            Some(Commands::Skill {
+                command: Some(SkillCommands::Install { .. })
+            })
+        ));
+    }
+
     #[test]
     fn test_cli_parses_mcp_stdio() {
         let cli = Cli::parse_from(["ascend-tools", "mcp"]);

src/ascend_tools/ascend-tools-cli/src/skill.md

@@ -0,0 +1,58 @@
+---
+name: ascend-tools
+description: Use the ascend-tools CLI to manage Ascend runtimes, flows, and flow runs.
+---
+
+# ascend-tools
+
+Manage Ascend runtimes, flows, and flow runs via the `ascend-tools` CLI.
+
+## Authentication
+
+Set three environment variables (from Ascend UI > Settings > Users > Create Service Account):
+
+```bash
+export ASCEND_SERVICE_ACCOUNT_ID="asc-sa-..."
+export ASCEND_SERVICE_ACCOUNT_KEY="..."
+export ASCEND_INSTANCE_API_URL="https://api.instance.ascend.io"
+```
+
+## Commands
+
+### Runtimes
+
+```bash
+ascend-tools runtime list [--id <ID>] [--kind <KIND>] [--project-uuid <UUID>] [--environment-uuid <UUID>]
+ascend-tools runtime get <UUID>
+ascend-tools runtime resume <UUID>
+ascend-tools runtime pause <UUID>
+```
+
+### Flows
+
+```bash
+ascend-tools flow list --runtime <UUID>
+ascend-tools flow run <FLOW_NAME> --runtime <UUID> [--spec '<JSON>'] [--resume]
+ascend-tools flow list-runs --runtime <UUID> [--status <STATUS>] [--flow-name <NAME>]
+ascend-tools flow get-run <RUN_NAME> --runtime <UUID>
+```
+
+### Flow run spec
+
+Pass `--spec` as JSON to control flow run behavior:
+
+```bash
+ascend-tools flow run my-flow --runtime <UUID> --spec '{"full_refresh": true}'
+ascend-tools flow run my-flow --runtime <UUID> --spec '{"components": ["component_a", "component_b"]}'
+ascend-tools flow run my-flow --runtime <UUID> --spec '{"run_tests": false}'
+```
+
+Available spec fields: `full_refresh`, `components`, `component_categories`, `parameters`, `run_tests`, `halt_flow_on_error`, `disable_optimizers`, `runner_overrides`.
+
+## Output
+
+Default output is a human-readable table. Use `-o json` for machine-readable output:
+
+```bash
+ascend-tools -o json runtime list
+```