mirror of
https://github.com/tiennm99/goclaw.git
synced 2026-10-11 03:13:24 +00:00
feat(skills): add bundled goclaw gateway skill
This commit is contained in:
Goon committed
1 parent
c32d6b3279
commit
25b039dbe9
5 files changed
+389
-10
No files matched your search
@@ -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.
|
||||
|
||||
|
||||
@@ -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/<slug>/<version>/
|
||||
│
|
||||
├─ 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:
|
||||
<skill name="pptx" slug="pptx">Read, create, edit PowerPoint presentations</skill>
|
||||
<skill name="xlsx" slug="xlsx">Read, create, edit Excel spreadsheets</skill>
|
||||
<skill name="skill-creator" slug="skill-creator">Create new skills</skill>
|
||||
<skill name="workspace-organizing" slug="workspace-organizing">Organize shared workspaces</skill>
|
||||
<skill name="goclaw" slug="goclaw">Gateway CLI/runtime administration</skill>
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
|
||||
@@ -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**
|
||||
|
||||
@@ -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")
|
||||
}
|
||||
}
|
||||
@@ -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 <command> --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 <skill>
|
||||
goclaw skills deps status <skill-id-or-path>
|
||||
goclaw skills access get <skill-id>
|
||||
```
|
||||
|
||||
Use dependency scan/check before install:
|
||||
|
||||
```bash
|
||||
goclaw skills deps scan <skill-id-or-path>
|
||||
goclaw skills deps check <skill-id-or-path>
|
||||
```
|
||||
|
||||
Mutating skill commands need clear intent and scope:
|
||||
|
||||
```bash
|
||||
goclaw skills deps install <skill-id>
|
||||
goclaw skills access set <skill-id> --help
|
||||
goclaw skills grant agent <skill-id> <agent-id>
|
||||
goclaw skills revoke agent <skill-id> <agent-id>
|
||||
```
|
||||
|
||||
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 <skill-id-or-path>
|
||||
```
|
||||
|
||||
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 <provider>
|
||||
```
|
||||
|
||||
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 <trace-id> -o json
|
||||
goclaw traces timeline <trace-id>
|
||||
goclaw traces follow --session <session-key>
|
||||
goclaw traces export <trace-id>
|
||||
```
|
||||
|
||||
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 <skill>`.
|
||||
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.
|
||||
Reference in new issue
Block a user