feat(skill): add Claude Code skill for GoClaw CLI

README.md

@@ -179,6 +179,26 @@ Switch profiles:
 goclaw auth use-context staging
 ```
 
+## Claude Code Skill
+
+A Claude Code skill wrapping this CLI lives in [`claude-skill/`](./claude-skill/).
+It lets Claude Code autonomously invoke `goclaw` to manage your GoClaw server —
+list agents, run `exec`-style shell commands on the server, inspect traces, etc.
+
+Install (once the binary is in `PATH`):
+
+```bash
+RELEASE_URL="https://github.com/nextlevelbuilder/goclaw-cli/releases/download/skill-v0.1.0"
+curl -fsSL "$RELEASE_URL/goclaw-skill.tar.gz" -o /tmp/goclaw-skill.tar.gz
+curl -fsSL "$RELEASE_URL/goclaw-skill.sha256" -o /tmp/goclaw-skill.sha256
+(cd /tmp && shasum -a 256 -c goclaw-skill.sha256)
+tar xzf /tmp/goclaw-skill.tar.gz -C /tmp
+/tmp/claude-skill/install.sh
+```
+
+See [`claude-skill/README.md`](./claude-skill/README.md) for permission modes,
+example prompts, and uninstall instructions.
+
 ## Development
 
 ```bash

claude-skill/.verified-commands.txt

@@ -0,0 +1,60 @@
+A production-ready CLI for managing GoClaw AI agent gateway servers.
+Supports interactive (human) and automation (AI agent / CI) modes.
+
+Usage:
+  goclaw [command]
+
+Available Commands:
+  activity         View audit log
+  agents           Manage agents
+  api-docs         View API documentation
+  api-keys         Manage API keys for scoped access
+  approvals        Manage execution approvals
+  auth             Manage authentication
+  channels         Manage messaging channels
+  chat             Chat with an agent
+  completion       Generate the autocompletion script for the specified shell
+  config           Manage server configuration
+  contacts         Manage contacts
+  credentials      Manage CLI credentials store
+  cron             Manage scheduled jobs
+  delegations      View delegation history
+  devices          Manage paired devices
+  export           Export resources (agents, teams, skills, mcp)
+  health           Check server health
+  heartbeat        Manage heartbeat configuration and monitoring
+  help             Help about any command
+  import           Import resources (agents, teams, skills, mcp)
+  knowledge-graph  Knowledge graph operations
+  logs             View server logs
+  mcp              Manage MCP servers and grants
+  media            Upload and download media
+  memory           Manage agent memory
+  packages         Manage runtime packages
+  pending-messages Manage pending messages
+  providers        Manage LLM providers
+  sessions         Manage chat sessions
+  skills           Manage skills
+  status           Show server status and metadata
+  storage          Browse workspace files
+  system-config    Per-tenant key-value configuration
+  teams            Manage agent teams
+  tenants          Manage tenants (admin)
+  tools            Manage built-in tools
+  traces           View LLM traces
+  tts              Text-to-speech operations
+  usage            View usage and cost analytics
+  version          Print CLI version information
+
+Flags:
+  -h, --help               help for goclaw
+      --insecure           Skip TLS certificate verification
+  -o, --output string      Output format: table, json, yaml (default "table")
+      --profile string     Config profile to use (default: active profile)
+      --server string      GoClaw server URL (env: GOCLAW_SERVER)
+      --tenant-id string   Tenant ID for multi-tenant operations (env: GOCLAW_TENANT_ID)
+      --token string       Auth token or API key (env: GOCLAW_TOKEN)
+  -v, --verbose            Enable verbose/debug output
+  -y, --yes                Skip confirmation prompts (automation mode)
+
+Use "goclaw [command] --help" for more information about a command.

claude-skill/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextLevelBuilder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude-skill/README.md

@@ -0,0 +1,74 @@
+# GoClaw CLI Skill for Claude Code
+
+Lets the Claude Code agent drive [goclaw](https://github.com/nextlevelbuilder/goclaw-cli) — the CLI for GoClaw AI agent gateway servers — via natural-language prompts. Execute shell commands on remote servers, manage AI agents, approve execution requests, inspect chat sessions, and administer multi-tenant infrastructure, all without leaving Claude Code.
+
+## Requirements
+
+- `goclaw` binary ≥ 0.3.0 in `$PATH` ([install](https://github.com/nextlevelbuilder/goclaw-cli/releases))
+- Claude Code CLI installed (`~/.claude/` directory)
+- Authenticated: run `goclaw auth login` before using the skill
+- macOS or Linux (Windows via WSL)
+
+## Install
+
+### Recommended: release tarball + SHA256
+
+```bash
+RELEASE_URL="https://github.com/nextlevelbuilder/goclaw-cli/releases/download/skill-v0.1.0"
+curl -fsSL "$RELEASE_URL/goclaw-skill.tar.gz" -o /tmp/goclaw-skill.tar.gz
+curl -fsSL "$RELEASE_URL/goclaw-skill.sha256" -o /tmp/goclaw-skill.sha256
+(cd /tmp && sha256sum -c goclaw-skill.sha256)  # aborts on mismatch
+tar xzf /tmp/goclaw-skill.tar.gz -C /tmp
+/tmp/claude-skill/install.sh
+```
+
+### From git clone
+
+```bash
+git clone https://github.com/nextlevelbuilder/goclaw-cli.git
+cd goclaw-cli/claude-skill
+./install.sh
+```
+
+## Usage examples
+
+Once installed, just ask Claude:
+
+- *"list agents on goclaw"* → runs `goclaw agents list --output json`
+- *"run `uname -a` on goclaw server"* → runs `goclaw tools invoke exec --param command="uname -a"`
+- *"what's my usage this week"* → runs `goclaw usage summary --output json`
+
+Destructive operations always prompt you first. Claude will ask *"Confirm delete agent xyz?"* before running `goclaw agents delete xyz --yes`.
+
+## Permission modes
+
+The installer offers three modes:
+
+| Mode | Rule | When to use |
+|------|------|-------------|
+| 1 | `Bash(goclaw:*)` | Trusted personal machine, full-auto |
+| 2 | ~20 readonly rules | Shared / production machine (default) |
+| 3 | Manual JSON snippet | You want to edit settings.json yourself |
+
+Default in pipe mode (`curl | bash`): Mode 3 (safest).
+
+## What's NOT supported
+
+- Interactive chat REPL (`goclaw chat` without `-m`) — use single-shot
+- `logs tail` streaming — Claude will suggest polling instead
+- `auth pair` device pairing — run manually, skill refuses
+
+## Uninstall
+
+```bash
+rm -rf ~/.claude/skills/goclaw
+# Then manually remove goclaw permissions from ~/.claude/settings.json
+```
+
+## Compatibility
+
+Tested against `goclaw` CLI ≥ 0.3.0. `check-drift.sh` catches flag drift between skill and CLI.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

claude-skill/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: goclaw
+description: Manage GoClaw AI agent gateway servers from Claude Code. Use this skill when the user mentions "goclaw", "gateway server", "AI agent platform", or wants to execute shell commands remotely on a server, manage AI agents, approve agent actions, inspect chat sessions, or administer multi-tenant AI infrastructure. Wraps the `goclaw` CLI to call REST + WebSocket APIs of GoClaw Gateway.
+when_to_use: goclaw CLI operations, remote shell execution via exec tool, AI agent lifecycle, chat session inspection, tenant administration, skill/provider/MCP management, execution approvals
+allowed-tools: Bash(goclaw:*)
+disable-model-invocation: false
+user-invocable: true
+argument-hint: <natural-language-intent>
+---
+
+# GoClaw CLI Skill
+
+Lets Claude invoke the `goclaw` binary via Bash to interact with a GoClaw Gateway server. Single source of truth = the CLI; this skill teaches Claude the ergonomics.
+
+## Conventions (always apply)
+
+1. **Always append `--output json`** to every goclaw call. Rely on JSON parsing, not table output.
+2. **Read auth from `~/.goclaw/config.yaml`** — do NOT accept token via prompt; user must have run `goclaw auth login` beforehand.
+3. **Destructive ops require user confirm.** Any command with `--yes` flag or verbs `delete`, `reset`, `revoke`, `unpublish`, `clear`, `rotate`, `deny`, `execute-merge` → ask user to confirm *before* adding `--yes`.
+4. **Streaming commands are NOT Bash-friendly.** Refuse to run: `chat` interactive mode, `logs tail`, `auth pair`, `approvals watch`. Suggest polling or user-run-manually alternative.
+5. **Exit code 1 after auth error** → suggest `goclaw auth login`, do not retry-loop.
+6. **Never hardcode** server URL, tenant ID, agent ID, user ID — use placeholders in examples, actual values from user context.
+
+## Hero use case — execute shell on server
+
+Tool `exec` registered as builtin on GoClaw Gateway. Claude invokes via:
+
+```bash
+goclaw tools invoke exec --param command="ls -la /workspace" --output json
+# with working directory:
+goclaw tools invoke exec --param command="npm test" --param working_dir="/workspace/app" --output json
+```
+
+Approval flow when server deems command sensitive (package installs, deny-patterns): call hits `approvals` queue. Handle via `references/exec-workflow.md`.
+
+## Navigation — load relevant reference on demand
+
+Claude: when user's intent matches, `Read` the listed reference file before constructing commands.
+
+| Intent signal | Reference |
+|---------------|-----------|
+| exec / run shell / remote command / approvals | [references/exec-workflow.md](references/exec-workflow.md) |
+| login / token / profile / tenant switch / credentials / api-keys | [references/auth-and-config.md](references/auth-and-config.md) |
+| agent list/get/create/delete, agent files, instances, wake | [references/agents-core.md](references/agents-core.md) |
+| agent share, link, delegate, regenerate | [references/agents-advanced.md](references/agents-advanced.md) |
+| chat with agent, session list/preview/delete | [references/chat-sessions.md](references/chat-sessions.md) |
+| health, status, logs, traces, usage, metrics | [references/monitoring-ops.md](references/monitoring-ops.md) |
+| knowledge graph, entity dedup, memory | [references/knowledge-memory.md](references/knowledge-memory.md) |
+| teams, members, team tasks, workspace files | [references/teams-collaboration.md](references/teams-collaboration.md) |
+| channels, contacts, pending messages, writers | [references/channels-messaging.md](references/channels-messaging.md) |
+| export / import / storage (workspace files) | [references/data-movement.md](references/data-movement.md) |
+| providers, skills, built-in tools list/config, packages | [references/providers-skills-tools.md](references/providers-skills-tools.md) |
+| cron, heartbeat, device pairing | [references/automation-scheduling.md](references/automation-scheduling.md) |
+| MCP servers, grants, requests | [references/mcp-integration.md](references/mcp-integration.md) |
+| tenants, system-config, audit activity, TTS | [references/admin-system.md](references/admin-system.md) |
+| media upload/download | [references/media.md](references/media.md) |
+| API documentation browsing | [references/docs-api.md](references/docs-api.md) |
+
+## Compatibility
+
+Tested against `goclaw` CLI ≥ 0.3.0. Run `goclaw version` to check. Schema drift caught by `check-drift.sh` in CI.
+
+## Prerequisites
+
+- `goclaw` binary in PATH (download from https://github.com/nextlevelbuilder/goclaw-cli/releases)
+- Authenticated: `goclaw auth login` or paired via `goclaw auth pair`
+- Permissions granted in `~/.claude/settings.json` (see install.sh)
+
+## Troubleshooting
+
+- Command returns 401 → token expired, run `goclaw auth login`
+- Command returns 403 → user lacks role for resource; check `goclaw whoami --output json`
+- Command hangs → likely streaming op — Claude should refuse, see convention #4

claude-skill/check-drift.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# check-drift.sh — validate that every --flag mentioned in references/*.md
+# exists in goclaw-cli/cmd/*.go source. Exit non-zero on mismatch.
+# Intended for CI: catches skill documentation going stale relative to CLI.
+set -euo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SKILL_DIR}/.." && pwd)"
+CMD_DIR="${REPO_ROOT}/cmd"
+
+if [[ ! -d "$CMD_DIR" ]]; then
+  echo "ERROR: cmd/ not found at $CMD_DIR. Run from goclaw-cli repo or mount it."
+  exit 1
+fi
+
+# Cobra built-ins we never expect to find in goclaw cmd/*.go
+ALLOWLIST=(help verbose output server token insecure yes profile tenant-id version)
+
+is_allowed() {
+  local f="$1"
+  for a in "${ALLOWLIST[@]}"; do
+    [[ "$f" == "$a" ]] && return 0
+  done
+  return 1
+}
+
+TOTAL=0
+MISSING=0
+declare -a MISSING_FLAGS=()
+
+# Extract flag names (--foo, --foo-bar) from reference md files.
+# Match --flag-name (letters/digits/hyphens), excluding trailing punctuation.
+while IFS= read -r line; do
+  [[ -z "$line" ]] && continue
+  flag="$(echo "$line" | sed -E 's/^.*--([a-zA-Z][a-zA-Z0-9-]*).*$/\1/')"
+  [[ -z "$flag" ]] && continue
+  TOTAL=$((TOTAL + 1))
+  if is_allowed "$flag"; then
+    continue
+  fi
+  # Grep the cmd/*.go source for Flags().<Type>("$flag" ...).
+  if ! grep -rEq "Flags\(\)\.(String|Int|Bool|StringSlice|StringP|IntP|BoolP)\([^)]*\"$flag\"" "$CMD_DIR" 2>/dev/null; then
+    MISSING=$((MISSING + 1))
+    MISSING_FLAGS+=("$flag")
+  fi
+done < <(grep -hoE -- '--[a-zA-Z][a-zA-Z0-9-]*' "$SKILL_DIR/references/"*.md 2>/dev/null | sort -u)
+
+echo "Checked $(grep -hoE -- '--[a-zA-Z][a-zA-Z0-9-]*' "$SKILL_DIR/references/"*.md 2>/dev/null | sort -u | wc -l | tr -d ' ') unique flag mentions across references/."
+echo "Unresolved: $MISSING"
+
+if (( MISSING > 0 )); then
+  printf '%s\n' "Missing from cmd/*.go (possible drift or false positive):"
+  for f in "${MISSING_FLAGS[@]}"; do
+    printf '  --%s\n' "$f"
+  done
+  exit 1
+fi
+
+echo "OK — no drift detected."
+exit 0