AltimateAI
diff --git a/‎docs/docs/configure/skills.md‎
Lines changed: 93 additions & 3 deletions b/‎docs/docs/configure/skills.md‎
Lines changed: 93 additions & 3 deletions
diff --git a/‎docs/docs/configure/tools/custom.md‎
Lines changed: 84 additions & 2 deletions b/‎docs/docs/configure/tools/custom.md‎
Lines changed: 84 additions & 2 deletions
diff --git a/‎packages/opencode/src/altimate/telemetry/index.ts‎
Lines changed: 26 additions & 0 deletions b/‎packages/opencode/src/altimate/telemetry/index.ts‎
Lines changed: 26 additions & 0 deletions
diff --git a/‎packages/opencode/src/cli/cmd/skill-helpers.ts‎
Lines changed: 108 additions & 0 deletions b/‎packages/opencode/src/cli/cmd/skill-helpers.ts‎
Lines changed: 108 additions & 0 deletions
@@ -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:
 
 
@@ -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:
 
 
@@ -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
 
@@ -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