From 25b039dbe964cde3b498ac04d9594711aabfe33f Mon Sep 17 00:00:00 2001 From: Goon Date: Fri, 12 Jun 2026 22:17:41 +0700 Subject: [PATCH] feat(skills): add bundled goclaw gateway skill --- docs/14-skills-runtime.md | 4 +- docs/15-core-skills-system.md | 26 ++- docs/project-changelog.md | 15 ++ internal/skills/bundled_smoke_test.go | 73 +++++++ skills/goclaw/SKILL.md | 281 ++++++++++++++++++++++++++ 5 files changed, 389 insertions(+), 10 deletions(-) create mode 100644 skills/goclaw/SKILL.md diff --git a/docs/14-skills-runtime.md b/docs/14-skills-runtime.md index 512a459d..21e705f7 100644 --- a/docs/14-skills-runtime.md +++ b/docs/14-skills-runtime.md @@ -189,13 +189,15 @@ Skills shipped with the Docker image at `/app/bundled-skills/`. Lowest priority | `docx` | Read, create, edit Word documents | | `pptx` | Read, create, edit presentations | | `skill-creator` | Create new skills | +| `workspace-organizing` | Organize shared workspaces and generated files | +| `goclaw` | Operate and debug GoClaw gateway CLI/runtime administration | ### How It Works 1. Skills source files live in `skills/` directory in the repo 2. Dockerfile copies them to `/app/bundled-skills/` in the image 3. `gateway.go` passes this path as `builtinSkills` to `skills.NewLoader()` -4. Loader priority: workspace > project-agents > personal-agents > global > **builtin** > managed +4. Loader priority: workspace > project-agents > personal-agents > global > managed > **builtin** When a user uploads a skill with the same name via the UI, the managed version takes precedence. diff --git a/docs/15-core-skills-system.md b/docs/15-core-skills-system.md index 313f7c15..a3e3fabb 100644 --- a/docs/15-core-skills-system.md +++ b/docs/15-core-skills-system.md @@ -6,7 +6,7 @@ How bundled (system) skills are loaded, stored, injected into agents, and manage ## 1. Overview -GoClaw ships with a set of **core skills** — SKILL.md-based modules bundled inside the binary's embedded filesystem. Unlike custom skills uploaded by users, core skills are: +GoClaw ships with a set of **core skills** — SKILL.md-based modules bundled with the release under `/app/bundled-skills/` in Docker images, or `skills/` in local development and binary release archives. Unlike custom skills uploaded by users, core skills are: - Seeded automatically on every gateway startup - Tracked by content hash (no re-import if file unchanged) @@ -23,6 +23,8 @@ Current bundled core skills: | `pptx` | Read, create, edit PowerPoint presentations via python-pptx | | `xlsx` | Read, create, edit Excel spreadsheets via openpyxl | | `skill-creator` | Meta-skill for creating new skills | +| `workspace-organizing` | Workspace layout and file organization guidance | +| `goclaw` | Gateway CLI/runtime administration and troubleshooting | Shared helper modules live in `skills/_shared/` and are copied alongside each skill but not registered as standalone skills. @@ -31,25 +33,25 @@ Shared helper modules live in `skills/_shared/` and are copied alongside each sk ## 2. Startup Flow ``` -cmd/gateway.go NewSkillLoader() +cmd/gateway_setup.go setupSkillsSystem() │ ▼ -internal/skills/loader.go NewLoader(baseDir, db) +internal/skills/loader.go NewLoader(workspace, globalSkillsDir, builtinSkillsDir) │ ── scans filesystem skill dirs - │ ── wires managed DB directory - │ ── calls BumpVersion() → invalidates list cache + │ ── wires managed skills-store directory + │ ── calls BumpVersion() -> invalidates list cache │ ▼ -internal/skills/seeder.go Seed(ctx, db, embedFS, baseDir) +internal/skills/seeder.go NewSeeder(bundledSkillsDir, managedDir, store).Seed(ctx) │ - ├─ For each bundled skill in embed.FS (skills/*/SKILL.md): + ├─ For each bundled skill from os.ReadDir(bundledSkillsDir): │ 1. Read SKILL.md → parse YAML frontmatter (name, slug, description, author, ...) │ 2. Compute SHA-256 of content → FileHash │ 3. Call GetNextVersion(slug) → next DB version number │ 4. UpsertSystemSkill(ctx, params) ──► see §4 │ 5. Copy skill files to baseDir/// │ - ├─ CheckDepsAsync(ctx, seededSlugs, baseDir, skillStore, broadcaster) + ├─ CheckDepsAsync(seededSkills, msgBus) │ └─ goroutine (non-blocking): │ for each slug: │ broadcast EventSkillDepsChecking {slug} @@ -86,7 +88,11 @@ skills/ │ └── ... ├── xlsx/ │ └── ... -└── skill-creator/ +├── skill-creator/ +│ └── SKILL.md +├── workspace-organizing/ +│ └── SKILL.md +└── goclaw/ └── SKILL.md ``` @@ -293,6 +299,8 @@ Count ≤ 40 AND tokens ≤ 5000: Read, create, edit PowerPoint presentations Read, create, edit Excel spreadsheets Create new skills + Organize shared workspaces + Gateway CLI/runtime administration ``` diff --git a/docs/project-changelog.md b/docs/project-changelog.md index 2279ce37..d81e98b2 100644 --- a/docs/project-changelog.md +++ b/docs/project-changelog.md @@ -6,6 +6,21 @@ Significant changes, features, and fixes in reverse chronological order. ## 2026-06-12 +### Bundled GoClaw gateway administration skill (issue #175) + +**Changes** + +- Added a bundled `goclaw` system skill for version-aware GoClaw CLI/runtime + discovery, read-only-first diagnostics, gateway administration workflows, and + troubleshooting playbooks. +- Documented safety guidance for credentials, destructive actions, + permissions, tenant scope, and trace redaction. + +**Tests** + +- Added bundled-skill regression coverage to keep the default core skill set + discoverable in fresh runtimes. + ### Bailian Coding qwen3.7-plus catalog (issue #169) **Changes** diff --git a/internal/skills/bundled_smoke_test.go b/internal/skills/bundled_smoke_test.go index 25d49f62..a9298dbb 100644 --- a/internal/skills/bundled_smoke_test.go +++ b/internal/skills/bundled_smoke_test.go @@ -1,8 +1,10 @@ package skills import ( + "context" "os" "path/filepath" + "strings" "testing" ) @@ -41,3 +43,74 @@ func TestBundledSkills_NoRegression(t *testing.T) { }) } } + +func TestBundledSkills_ExpectedCoreSkillSlugs(t *testing.T) { + bundled := "../../skills" + expected := map[string]bool{ + "docx": false, + "goclaw": false, + "pdf": false, + "pptx": false, + "skill-creator": false, + "workspace-organizing": false, + "xlsx": false, + } + + entries, err := os.ReadDir(bundled) + if err != nil { + t.Skip("bundled skills dir not found:", err) + return + } + + for _, e := range entries { + if !e.IsDir() || e.Name() == "_shared" { + continue + } + name := e.Name() + if _, ok := expected[name]; !ok { + continue + } + expected[name] = true + + meta := parseMetadata(filepath.Join(bundled, name, "SKILL.md")) + if meta == nil { + t.Fatalf("%s: missing SKILL.md metadata", name) + } + if meta.Name == "" { + t.Errorf("%s: metadata name is empty", name) + } + if meta.Description == "" { + t.Errorf("%s: metadata description is empty", name) + } + } + + for name, found := range expected { + if !found { + t.Errorf("expected bundled skill %q to exist", name) + } + } + + loader := NewLoader("", "", bundled) + var foundGoclaw bool + for _, info := range loader.ListSkills(context.Background()) { + if info.Slug == "goclaw" { + foundGoclaw = true + if info.Source != "builtin" { + t.Errorf("goclaw source = %q, want builtin", info.Source) + } + if info.Description == "" { + t.Error("goclaw description is empty in loader metadata") + } + } + } + if !foundGoclaw { + t.Fatal("goclaw was not discoverable by the bundled skills loader") + } + content, ok := loader.LoadSkill(context.Background(), "goclaw") + if !ok { + t.Fatal("goclaw was not loadable by the bundled skills loader") + } + if !strings.Contains(content, "GoClaw Gateway CLI Administration") { + t.Error("goclaw loaded content does not include the expected guide heading") + } +} diff --git a/skills/goclaw/SKILL.md b/skills/goclaw/SKILL.md new file mode 100644 index 00000000..a1641770 --- /dev/null +++ b/skills/goclaw/SKILL.md @@ -0,0 +1,281 @@ +--- +name: goclaw +description: Use this skill when administering, operating, or debugging a GoClaw gateway through the GoClaw CLI/runtime package. It covers CLI discovery, safe command inspection, gateway health/config diagnostics, agents, skills, MCP/tools, runtime packages, credentials, traces, sessions, channels, providers, cron/jobs, and troubleshooting. Always inspect the live `goclaw --help` output first because command availability is version-dependent. +license: Proprietary. Part of GoClaw bundled skills. +--- + +# GoClaw Gateway CLI Administration + +Use this skill when the user asks you to operate, inspect, administer, or debug a +GoClaw gateway through the `goclaw` CLI/runtime package. + +## Operating Rules + +1. Identify the exact binary before running commands. +2. Prefer read-only inspection before mutating actions. +3. Never print, paste, or store API keys, bearer tokens, OAuth tokens, database + credentials, private keys, cookies, or `.env` contents in chat, issues, + comments, or logs. +4. Scope every action to the requested gateway, tenant, org, agent, team, + session, channel, or provider. +5. Ask for explicit confirmation before destructive or security-sensitive + actions. +6. If command help disagrees with this skill, trust the live `--help` output. + +Do not run bare `goclaw` unless the user explicitly wants to start the gateway +server. Use `goclaw --help`, `goclaw version`, or a subcommand for inspection. + +## CLI Discovery + +Start with read-only discovery: + +```bash +command -v goclaw +type -a goclaw +goclaw version +goclaw --help +goclaw --help +``` + +If `command -v goclaw` is empty on a managed server, also check deployment +runtime paths before concluding the CLI is absent: + +```bash +ls -l /var/lib/goclaw/data/.runtime/bin/goclaw +ls -l /app/data/.runtime/bin/goclaw +``` + +Distinguish the command surface you found: + +- Gateway server binary: running `goclaw` with no subcommand starts the gateway. +- Operator/admin CLI: subcommands such as `agent`, `skills`, `traces`, + `sessions`, `providers`, `channels`, `cron`, `config`, `doctor`, `auth`, + `backup`, `restore`, `migrate`, and `upgrade`. +- Remote operator mode: many admin commands can read `GOCLAW_SERVER`, + `GOCLAW_GATEWAY_URL`, and `GOCLAW_GATEWAY_TOKEN` from the environment. + Configure tokens through the shell/session secret manager, not CLI argv or + pasted text. + +Use placeholders in examples: + +```bash +goclaw traces list +``` + +## Read-Only Diagnostics + +Run safe checks first: + +```bash +goclaw doctor +goclaw config path +goclaw config validate +goclaw agent list +goclaw skills list +goclaw sessions list +goclaw providers list +goclaw channels list +goclaw cron list +goclaw traces list +``` + +If a command requires a running gateway, retry with the correct remote target: + +```bash +goclaw agent list +``` + +Use `goclaw config show` only in a private local terminal when necessary. Treat +the output as sensitive even though the CLI redacts known secret fields; do not +paste it into chats, issues, PRs, or shared logs. + +For HTTP-only surfaces, inspect the current API/docs before guessing endpoint +shape. Useful areas include `/health`, `/v1/skills`, `/v1/traces`, +`/v1/packages/runtimes`, `/v1/mcp`, and `/v1/providers` when available. + +## Common Workflows + +### Agents + +Read first: + +```bash +goclaw agent --help +goclaw agent list +``` + +Before create, update, chat, or delete operations, verify target tenant/org and +agent ID/key. Treat `agent delete` as destructive. + +### Skills + +Read first: + +```bash +goclaw skills --help +goclaw skills list +goclaw skills show +goclaw skills deps status +goclaw skills access get +``` + +Use dependency scan/check before install: + +```bash +goclaw skills deps scan +goclaw skills deps check +``` + +Mutating skill commands need clear intent and scope: + +```bash +goclaw skills deps install +goclaw skills access set --help +goclaw skills grant agent +goclaw skills revoke agent +``` + +System skills are bundled and should not be edited in place. Prefer uploading or +publishing a tenant/custom skill override when customization is required. + +### MCP Servers And Tools + +First inspect whether this CLI version exposes MCP commands: + +```bash +goclaw mcp --help +``` + +If no MCP CLI exists, use the current gateway API/UI/docs for MCP discovery and +permission changes. Do not invent command names. For tool access issues, verify: + +- the MCP server is configured and enabled; +- the tool is visible to the requested agent/team; +- permissions or approval rules allow the action; +- gateway logs/traces show the actual failure. + +### Runtime Packages + +Inspect current runtime/package support before acting: + +```bash +goclaw packages --help +goclaw skills deps status +``` + +If there is no packages CLI, use the Packages UI or `/v1/packages/*` API when +available. Install/update/remove package operations are admin-level and may need +approval. Prefer the smallest dependency needed by the selected skill. + +### Credentials And Auth + +Use read-only status commands first: + +```bash +goclaw auth status +goclaw auth status +``` + +For gateway bearer tokens, provider keys, OAuth refresh tokens, and CLI +credentials: + +- never echo values; +- do not add them to issues, PRs, chat, or logs; +- prefer environment variables, OS keychain, or gateway credential UI; +- rotate credentials if they were exposed; +- confirm before logout, delete, or replace operations. + +### Traces And Failed Runs + +Use traces to debug provider errors, tool failures, channel delivery, and stuck +sessions: + +```bash +goclaw traces --help +goclaw traces list --status error +goclaw traces get -o json +goclaw traces timeline +goclaw traces follow --session +goclaw traces export +``` + +Redact prompts, tokens, URLs with secrets, headers, and customer data before +posting trace excerpts anywhere public. + +### Sessions, Channels, Providers, Cron + +Inspect help and list commands: + +```bash +goclaw sessions --help +goclaw channels --help +goclaw providers --help +goclaw cron --help +``` + +Treat these as sensitive: + +- `sessions delete` and `sessions reset`; +- channel add/delete or credential changes; +- provider add/update/delete and model verification with live credentials; +- cron delete/toggle/run. + +## Troubleshooting Playbooks + +### Agent Cannot Access A Tool Or MCP + +1. Confirm the request is in the intended tenant/org and agent/team. +2. List available skills/tools for that agent context. +3. Check MCP server status/config and permission grants. +4. Inspect the relevant trace for permission, approval, or transport errors. +5. Apply the smallest grant or config change after confirmation. + +### Package Install Or Update Failed + +1. Check skill dependency status. +2. Inspect runtime availability for Python, Node, system packages, or GitHub + release installers. +3. Look for pending approval, network, permission, disk, or checksum errors. +4. Retry only after the root cause is clear. + +### CLI Credentials Missing Or Expired + +1. Run `goclaw auth status` or the relevant credential status command. +2. Verify required env vars exist without printing values. +3. Re-authenticate through the approved UI/CLI flow. +4. Re-run the original read-only command before mutating anything. + +### Provider Or Model Error + +1. Use traces to find the provider, model, status code, and error class. +2. Check `goclaw providers list` and provider verification help. +3. Confirm model availability from the current provider config. +4. Avoid changing provider priority or credentials without user approval. + +### Skill Not Visible Or Not Granted + +1. Run `goclaw skills list` and `goclaw skills show `. +2. Inspect access mode and effective access for the target agent/user. +3. Check whether the skill is archived due to missing dependencies. +4. Grant or enable only the requested skill and scope. + +### Channel Delivery Failure + +1. Identify channel, session, sender, and trace ID. +2. Inspect `goclaw channels list` and the failed trace. +3. Check provider/tool errors before blaming the channel. +4. Redact external message IDs and user data when reporting. + +## Mutating Command Confirmation + +Ask for confirmation before running commands that: + +- delete, reset, revoke, restore, force, drop, or migrate down; +- change provider/channel credentials; +- install/update/remove runtime packages; +- grant broad skill/tool access; +- modify tenant/global config; +- trigger cron jobs with external side effects. + +Confirmation should include the target, command category, expected effect, and +rollback path if one exists.