feat: add skill CLI command and .opencode/tools/ auto-discovery

docs/docs/configure/skills.md

@@ -34,7 +34,8 @@ Focus on the query: $ARGUMENTS
 
 Skills are loaded from these locations (in priority order):
 
-1. **altimate-code directories** (project-scoped, highest priority):
+1. **Project directories** (project-scoped, highest priority):
+ - `.opencode/skills/`
  - `.altimate-code/skill/`
  - `.altimate-code/skills/`
 
@@ -88,9 +89,96 @@ altimate ships with built-in skills for common data engineering tasks. Type `/`
 | `/train` | Learn standards from documents/style guides |
 | `/training-status` | Dashboard of all learned knowledge |
 
+## CLI Commands
+
+Manage skills from the command line:
+
+```bash
+# Browse skills
+altimate-code skill list # table view
+altimate-code skill list --json # JSON (for scripting)
+altimate-code skill show dbt-develop # view full skill content
+
+# Create
+altimate-code skill create my-tool # scaffold skill + bash tool
+altimate-code skill create my-tool --language python # python tool stub
+altimate-code skill create my-tool --language node # node tool stub
+altimate-code skill create my-tool --skill-only # skill only, no CLI tool
+
+# Validate
+altimate-code skill test my-tool # check frontmatter + tool --help
+
+# Install from GitHub
+altimate-code skill install owner/repo # GitHub shorthand
+altimate-code skill install https://github.com/... # full URL (web URLs work too)
+altimate-code skill install ./local-path # local directory
+altimate-code skill install owner/repo --global # install globally
+
+# Remove
+altimate-code skill remove my-tool # remove skill + paired tool
+```
+
+### TUI
+
+Type `/skills` in the TUI prompt to open the skill browser. From there:
+
+| Key | Action |
+|-----|--------|
+| Enter | Use — inserts `/<skill-name>` into the prompt |
+| `ctrl+a` | Actions — show, edit, test, or remove the selected skill |
+| `ctrl+n` | New — scaffold a new skill + CLI tool |
+| `ctrl+i` | Install — install skills from a GitHub repo or URL |
+| Esc | Back — returns to previous screen |
+
 ## Adding Custom Skills
 
-Add your own skills as Markdown files in `.altimate-code/skill/`:
+The fastest way to create a custom skill is with the scaffolder:
+
+```bash
+altimate-code skill create freshness-check
+```
+
+This creates two files:
+
+- `.opencode/skills/freshness-check/SKILL.md` — teaches the agent when and how to use your tool
+- `.opencode/tools/freshness-check` — executable CLI tool stub
+
+### Pairing Skills with CLI Tools
+
+Skills become powerful when paired with CLI tools. Drop any executable into `.opencode/tools/` and it's automatically available on the agent's PATH:
+
+```
+.opencode/tools/ # Project-level tools (auto-discovered)
+~/.config/altimate-code/tools/ # Global tools (shared across projects)
+```
+
+A skill references its paired CLI tool through bash code blocks:
+
+```markdown
+---
+name: freshness-check
+description: Check data freshness across tables
+---
+
+# Freshness Check
+
+## CLI Reference
+\`\`\`bash
+freshness-check --table users --threshold 24h
+freshness-check --all --report
+\`\`\`
+
+## Workflow
+1. Ask the user which tables to check
+2. Run `freshness-check` with appropriate flags
+3. Interpret the output and suggest fixes
+```
+
+The tool can be written in any language (bash, Python, Node.js, etc.) — as long as it's executable.
+
+### Skill-Only (No CLI Tool)
+
+You can also create skills as plain prompt templates:
 
 ```markdown
 ---
@@ -104,9 +192,11 @@ Focus on: $ARGUMENTS
 
 `$ARGUMENTS` is replaced with whatever the user types after the skill name (e.g., `/cost-review SELECT * FROM orders` passes `SELECT * FROM orders`).
 
+### Skill Paths
+
 Skills are loaded from these paths (highest priority first):
 
-1. `.altimate-code/skill/` (project)
+1. `.opencode/skills/` and `.altimate-code/skill/` (project)
 2. `~/.altimate-code/skills/` (global)
 3. Custom paths via config:
 

docs/docs/configure/tools/custom.md

@@ -1,8 +1,90 @@
 # Custom Tools
 
-Create custom tools using TypeScript and the altimate plugin system.
+There are two ways to extend altimate-code with custom tools:
 
-## Quick Start
+1. **CLI tools** (recommended) — simple executables paired with skills
+2. **Plugin tools** — TypeScript-based tools using the plugin API
+
+## CLI Tools (Recommended)
+
+The simplest way to add custom functionality. Drop any executable into `.opencode/tools/` and it's automatically available to the agent via bash.
+
+### Quick Start
+
+```bash
+# Scaffold a skill + CLI tool pair
+altimate-code skill create my-tool
+
+# Or create manually:
+mkdir -p .opencode/tools
+cat > .opencode/tools/my-tool << 'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+echo "Hello from my-tool!"
+EOF
+chmod +x .opencode/tools/my-tool
+```
+
+Tools in `.opencode/tools/` are automatically prepended to PATH when the agent runs bash commands. No configuration needed.
+
+### Tool Locations
+
+| Location | Scope | Auto-discovered |
+|----------|-------|-----------------|
+| `.opencode/tools/` | Project | Yes |
+| `~/.config/altimate-code/tools/` | Global (all projects) | Yes |
+
+### Pairing with Skills
+
+Create a `SKILL.md` that teaches the agent when and how to use your tool:
+
+```bash
+altimate-code skill create my-tool --language python
+```
+
+This creates both `.opencode/skills/my-tool/SKILL.md` and `.opencode/tools/my-tool`. Edit both files to implement your tool.
+
+### Validating
+
+```bash
+altimate-code skill test my-tool
+```
+
+This checks that the SKILL.md is valid and the paired tool is executable.
+
+### Installing Community Skills
+
+Install skills (with their paired tools) from GitHub:
+
+```bash
+# From a GitHub repo
+altimate-code skill install anthropics/skills
+altimate-code skill install dagster-io/skills
+
+# From a GitHub web URL (pasted from browser)
+altimate-code skill install https://github.com/owner/repo/tree/main/skills/my-skill
+
+# Remove an installed skill
+altimate-code skill remove my-skill
+```
+
+Or use the TUI: type `/skills`, then `ctrl+i` to install or `ctrl+a` → Remove to delete.
+
+### Output Conventions
+
+For best results with the AI agent:
+
+- **Default output:** Human-readable text (the agent reads this well)
+- **`--json` flag:** Structured JSON for scripting
+- **Summary first:** "Found 12 matches:" or "3 issues detected:"
+- **Errors to stderr**, results to stdout
+- **Exit code 0** = success, **1** = error
+
+## Plugin Tools (Advanced)
+
+For more complex tools that need access to the altimate-code runtime, use the TypeScript plugin system.
+
+### Quick Start
 
 1. Create a tools directory:
 

packages/opencode/src/altimate/telemetry/index.ts

@@ -350,6 +350,32 @@ export namespace Telemetry {
  skill_source: "builtin" | "global" | "project"
  duration_ms: number
  }
+ // altimate_change start — telemetry for skill management operations
+ | {
+ type: "skill_created"
+ timestamp: number
+ session_id: string
+ skill_name: string
+ language: string
+ source: "cli" | "tui"
+ }
+ | {
+ type: "skill_installed"
+ timestamp: number
+ session_id: string
+ install_source: string
+ skill_count: number
+ skill_names: string[]
+ source: "cli" | "tui"
+ }
+ | {
+ type: "skill_removed"
+ timestamp: number
+ session_id: string
+ skill_name: string
+ source: "cli" | "tui"
+ }
+ // altimate_change end
  | {
  type: "sql_execute_failure"
  timestamp: number

packages/opencode/src/cli/cmd/skill-helpers.ts

@@ -0,0 +1,108 @@
+// altimate_change start — shared helpers for skill CLI commands
+import path from "path"
+import fs from "fs/promises"
+import { Global } from "@/global"
+import { Instance } from "../../project/instance"
+
+/** Shell builtins, common utilities, and agent tool names to filter when detecting CLI tool references. */
+export const SHELL_BUILTINS = new Set([
+ // Shell builtins
+ "echo", "cd", "export", "set", "if", "then", "else", "fi", "for", "do", "done",
+ "case", "esac", "printf", "source", "alias", "read", "local", "return", "exit",
+ "break", "continue", "shift", "trap", "type", "command", "builtin", "eval", "exec",
+ "test", "true", "false",
+ // Common CLI utilities (not user tools)
+ "cat", "grep", "awk", "sed", "rm", "cp", "mv", "mkdir", "ls", "chmod", "which",
+ "curl", "wget", "pwd", "touch", "head", "tail", "sort", "uniq", "wc", "tee",
+ "xargs", "find", "tar", "gzip", "unzip", "git", "npm", "yarn", "bun", "pip",
+ "python", "python3", "node", "bash", "sh", "zsh", "docker", "make",
+ // System utilities unlikely to be user tools
+ "sudo", "kill", "ps", "env", "whoami", "id", "date", "sleep", "diff", "less", "more",
+ // Agent tool names that appear in skill content but aren't CLI tools
+ "glob", "write", "edit",
+])
+
+/** Detect CLI tool references inside a skill's content (bash code blocks mentioning executables). */
+export function detectToolReferences(content: string): string[] {
+ const tools = new Set<string>()
+
+ // Match "Tools used: bash (runs `altimate-dbt` commands), ..."
+ const toolsUsedMatch = content.match(/Tools used:\s*(.+)/i)
+ if (toolsUsedMatch) {
+ const refs = toolsUsedMatch[1].matchAll(/`([a-z][\w-]*)`/gi)
+ for (const m of refs) {
+ if (!SHELL_BUILTINS.has(m[1])) tools.add(m[1])
+ }
+ }
+
+ // Match executable names in bash code blocks: lines starting with an executable name
+ const bashBlocks = content.matchAll(/```(?:bash|sh)\r?\n([\s\S]*?)```/g)
+ for (const block of bashBlocks) {
+ const lines = block[1].split("\n")
+ for (const line of lines) {
+ const trimmed = line.trim()
+ if (!trimmed || trimmed.startsWith("#")) continue
+ // Extract the first word (the command)
+ const cmdMatch = trimmed.match(/^(?:\$\s+)?([a-z][\w.-]*(?:-[\w]+)*)/i)
+ if (cmdMatch) {
+ const cmd = cmdMatch[1]
+ if (!SHELL_BUILTINS.has(cmd)) {
+ tools.add(cmd)
+ }
+ }
+ }
+ }
+
+ return Array.from(tools)
+}
+
+/** Determine the source label for a skill based on its location. */
+export function skillSource(location: string): string {
+ if (location.startsWith("builtin:")) return "builtin"
+ const home = Global.Path.home
+ // Builtin skills shipped with altimate-code
+ if (location.startsWith(path.join(home, ".altimate", "builtin"))) return "builtin"
+ // Global user skills (~/.claude/skills/, ~/.agents/skills/, ~/.config/altimate-code/skills/)
+ const globalDirs = [
+ path.join(home, ".claude", "skills"),
+ path.join(home, ".agents", "skills"),
+ path.join(home, ".altimate-code", "skills"),
+ path.join(Global.Path.config, "skills"),
+ ]
+ if (globalDirs.some((dir) => location.startsWith(dir))) return "global"
+ // Everything else is project-level
+ return "project"
+}
+
+/** Check if a tool is available on the current PATH (including .opencode/tools/). */
+export async function isToolOnPath(toolName: string, cwd: string): Promise<boolean> {
+ // Check .opencode/tools/ in both cwd and worktree (they may differ in monorepos)
+ const dirsToCheck = new Set([
+ path.join(cwd, ".opencode", "tools"),
+ path.join(Instance.worktree !== "/" ? Instance.worktree : cwd, ".opencode", "tools"),
+ path.join(Global.Path.config, "tools"),
+ ])
+
+ for (const dir of dirsToCheck) {
+ try {
+ await fs.access(path.join(dir, toolName), fs.constants.X_OK)
+ return true
+ } catch {}
+ }
+
+ // Check system PATH
+ const sep = process.platform === "win32" ? ";" : ":"
+ const binDir = process.env.ALTIMATE_BIN_DIR
+ const pathDirs = (process.env.PATH ?? "").split(sep).filter(Boolean)
+ if (binDir) pathDirs.unshift(binDir)
+
+ for (const dir of pathDirs) {
+ try {
+ await fs.access(path.join(dir, toolName), fs.constants.X_OK)
+ return true
+ } catch {}
+ }
+
+ return false
+}
+// altimate_change end