Skip to content

feat(skills): add capability-reference skill for runtime self-discovery #217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Aaronontheweb merged 1 commit into from
Mar 13, 2026
Merged

feat(skills): add capability-reference skill for runtime self-discovery #217

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,7 @@ feature area, the corresponding skill **must** be updated in the same PR.
| Memorizer MCP server, workspaces/projects/relationships, subagent memory | `memorizer-usage` |
| Config format, daemon health, logs, MCP wiring, diagnostics CLI, doctor | `self-diagnostics` |
| Skill file format, discovery, authoring workflow | `skill-authoring` |
| Tool definitions, CLI commands, grant categories, search_tools, scheduling tools | `capability-reference` |

**Workflow:**
1. Edit the skill source at `feeds/skills/.system/files/{name}/{version}.md`
Expand Down
176 changes: 176 additions & 0 deletions feeds/skills/.system/files/capability-reference/1.0.0/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
---
name: capability-reference
description: "Quick-lookup catalog of all built-in tools, CLI commands, tool grant categories, scheduling syntax, and MCP discovery. Read when unsure what tools or commands are available."
metadata:
author: netclaw
version: "1.0.0"
triggers: what can I do | available tools | CLI commands | how to schedule | tool grants | MCP discovery | list capabilities
---

## Session Context

Each turn injects the current session ID and channel info into the system
prompt. Use the session ID to:

- reference yourself in scheduled reminders
- correlate with `netclaw sessions` output for diagnostics
- identify which session is running during troubleshooting

## Built-in Tools by Grant Category

### builtin (always granted)

| Tool | Purpose |
|------|---------|
| `search_tools` | Discover and load MCP tools by keyword or server |
| `store_memory` | Save knowledge to cross-session memory |
| `find_memories` | Search memory (returns IDs, titles, snippets) |
| `get_memories` | Load full memory content by ID |
| `update_memory` | Edit or delete a memory by ID |
| `lookup_slack_user` | Find Slack user by name/email, returns user ID |
| `send_slack_message` | Send message to Slack channel or DM |

### web

| Tool | Purpose |
|------|---------|
| `web_search` | Search the web, returns titles/URLs/snippets |
| `web_fetch` | Fetch URL, save text to local file, return preview |

### file

| Tool | Purpose |
|------|---------|
| `file_read` | Read file contents as text |
| `file_write` | Write content to file, creates parent dirs |
| `attach_file` | Attach a file to send to the user |

### shell

| Tool | Purpose |
|------|---------|
| `shell_execute` | Run shell command with timeout, returns stdout/stderr |

### scheduling

| Tool | Purpose |
|------|---------|
| `set_reminder` | Schedule one-shot, interval, or cron reminders |
| `list_reminders` | List reminders with IDs, status, next fire times |
| `cancel_reminder` | Delete a reminder by ID |

## Tool Grant System

Sessions receive a set of granted tool categories. Tools outside the grant set
are unavailable for that session. `builtin` is always granted. Other categories
(`web`, `file`, `shell`, `scheduling`) are granted per ACL configuration in
`netclaw.json`.

## MCP Discovery (search_tools)

MCP tools are not loaded into the prompt by default. Use `search_tools` to
discover and load them:

```
search_tools(query: "servers") # list all MCP servers
search_tools(query: "all", server: "memorizer") # browse all tools in one server
search_tools(query: "email") # keyword search across all servers
```

After a search returns matching tools, those tools become callable. If no exact
match is found, `search_tools` suggests similar tools.

Generated MCP catalogs are cached at `identity/tooling/shadow/mcp/<server>.md`.

## Scheduling Quick Reference

`set_reminder` accepts three schedule types:

| Type | Schedule value examples |
|------|----------------------|
| `once` | `"30m"`, `"2h"`, `"2026-03-15T14:30:00Z"` |
| `interval` | `"30m"`, `"6h"`, `"1d"` |
| `cron` | `"0 */6 * * *"`, `"0 9 * * MON-FRI"` |

Key parameters: `name` (human-readable ID), `prompt` (instructions to execute),
`schedule_type`, `schedule`, `report_to_channel` (optional Slack channel for
results), `notify_instructions` (optional output formatting guidance).

The agent can reference its own session ID when creating reminders to tie
scheduled work back to the originating conversation.

## CLI Commands

### Interaction

| Command | Purpose |
|---------|---------|
| `netclaw chat` | Interactive TUI chat session |
| `netclaw chat --resume <id>` | Resume existing session by ID |
| `netclaw sessions` | Browse and resume recent sessions (TUI) |
| `netclaw sessions --once` | List sessions and exit (plain text or `--json`) |
| `netclaw -p "prompt"` | Headless single-prompt mode |

### Daemon

| Command | Purpose |
|---------|---------|
| `netclaw daemon start` | Start daemon as background process |
| `netclaw daemon stop` | Stop daemon gracefully |
| `netclaw daemon status` | Show daemon process status |
| `netclaw daemon install` | Install systemd user service (Linux) |
| `netclaw daemon uninstall` | Remove systemd user service |

### Diagnostics

| Command | Purpose |
|---------|---------|
| `netclaw doctor` | Offline config validation (see `self-diagnostics`) |
| `netclaw status` | Runtime health from daemon endpoint |

### Configuration

| Command | Purpose |
|---------|---------|
| `netclaw init` | First-run setup wizard |
| `netclaw provider` | Manage LLM providers (TUI or subcommands: `add`, `auth`, `list`, `get`, `remove`, `enable`, `disable`) |
| `netclaw model` | Manage model assignments (TUI or subcommands) |
| `netclaw mcp` | Manage MCP servers (`add`, `auth`, `list`, `get`, `remove`, `enable`, `disable`) |
| `netclaw secrets` | Manage encrypted secrets |

### Reminders

| Command | Purpose |
|---------|---------|
| `netclaw reminder list` | List all reminders |
| `netclaw reminder create` | Create a reminder |
| `netclaw reminder show <id>` | Show reminder details |
| `netclaw reminder cancel <id>` | Delete a reminder |
| `netclaw reminder enable <id>` | Enable a disabled reminder |
| `netclaw reminder disable <id>` | Disable a reminder |
| `netclaw reminder import <file>` | Import reminders from file |
| `netclaw reminder validate <file>` | Validate reminder file without importing |
| `netclaw reminder ui` | Reminder creation TUI |

### Maintenance

| Command | Purpose |
|---------|---------|
| `netclaw update` | Check for and install updates |
| `netclaw --version` | Show CLI version |

## Health Endpoints

| Endpoint | Purpose |
|----------|---------|
| `http://127.0.0.1:5199/api/health/ready` | Readiness probe |
| `http://127.0.0.1:5199/api/health/status` | Full runtime status JSON |
| `http://127.0.0.1:5199/api/sessions` | Active session list |

## Cross-References

- Memory tool usage: read `memory-usage`
- Memorizer MCP operations: read `memorizer-usage`
- Troubleshooting and diagnostics: read `self-diagnostics`
- Identity file management: read `identity-management`
- Creating new skills: read `skill-authoring`
100 changes: 100 additions & 0 deletions feeds/skills/.system/files/self-diagnostics/1.2.0/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
---
name: self-diagnostics
description: "Read when sessions timeout, connections fail, tools are missing, or the user reports errors. Covers netclaw doctor, logs, MCP status, and memory health."
metadata:
author: netclaw
version: "1.2.0"
triggers: connection failure | session timeout | missing tools | user reports errors | daemon issues | config change | memory degraded | check logs | view logs
---

## Behavioral Triggers

Read and follow this skill proactively when ANY of these occur:

- Connection failure (provider or MCP errors)
- Session issues (timeouts, unresponsiveness, unexpected endings)
- Missing tools (discovery failures, MCP disconnect)
- User-reported daemon/config errors
- Memory degradation or high checkpoint backlog

## Quick Reference

| What | Command / Path |
|------|---------------|
| Offline config validation | `netclaw doctor` |
| Daemon status (requires daemon) | `netclaw status` |
| Daemon lifecycle | `netclaw daemon start\|stop\|status` |
| Health endpoint | `curl http://127.0.0.1:5199/api/health/ready` |
| Full status JSON | `curl http://127.0.0.1:5199/api/health/status` |
| Active sessions | `curl http://127.0.0.1:5199/api/sessions` |
| MCP server status | `netclaw mcp list` |
| Provider list | `netclaw provider list` |
| Model configuration | `netclaw model list` |
| Memory runbook | `docs/runbooks/memory-health-and-evals.md` |

For a complete catalog of available tools and CLI commands, read
`capability-reference`.

## Configuration Files

| File | Purpose |
|------|---------|
| `~/.netclaw/config/netclaw.json` | Base configuration |
| `~/.netclaw/config/secrets.json` | Credentials overlay |

Use `file_read` to inspect these files. Never log/display API keys.

## netclaw doctor

Primary offline diagnostic tool. Runs without daemon.

```bash
netclaw doctor
netclaw doctor --format json
netclaw doctor --fix
netclaw doctor --fix --dry-run
```

Important memory checks include:

- SQLite provisioning check
- Memory checkpoint health check (pending checkpoint backlog)

## Daemon Status For Memory

Use `netclaw status` and inspect `memory`:

- `provider` (expected `sqlite` for default memory path)
- `status` (`healthy`, `degraded`, `unavailable`)
- `databasePath`
- `pendingCheckpoints`

If `pendingCheckpoints` grows persistently, inspect daemon logs and curation
worker activity.

## Logs

| Log | Location |
|-----|----------|
| Daemon | `~/.netclaw/logs/daemon-{yyyy-MM-dd}.log` |
| Session | `~/.netclaw/logs/sessions/{yyyyMMdd-HHmmss}_{session-id}.log` |
| Crash | `~/.netclaw/logs/crash-{yyyyMMdd-HHmmss}.log` |

## Common Issues

| Symptom | Check |
|---------|-------|
| No LLM responses | `netclaw doctor`; verify provider credentials |
| Missing tools | `netclaw mcp list`; inspect daemon logs |
| Memory recall degraded | `netclaw status` memory section; run `netclaw doctor` |
| Pending checkpoints keep rising | `Memory Checkpoint Health` warning + daemon logs |
| Daemon won't start | stale PID, crash logs, config JSON validity |

## Reporting Bugs

Include:

- `netclaw --version`
- relevant log excerpts (redacted)
- `netclaw doctor --format json` output
- reproduction steps and expected vs actual behavior
20 changes: 15 additions & 5 deletions feeds/skills/.system/manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,18 @@
{
"schemaVersion": 1,
"feedType": "system",
"updatedAt": "2026-03-13T18:30:59Z",
"updatedAt": "2026-03-13T19:58:13Z",
"skills": [
{
"name": "capability-reference",
"version": "1.0.0",
"minimumDaemonVersion": "0.1.0",
"sha256": "7a0c2e1c40fb9dd5360eb6f8e25643d154bb2775964d906a3add6e5166ac92b6",
"sizeBytes": 6208,
"url": "https://feeds.netclaw.dev/skills/.system/files/capability-reference/1.0.0/SKILL.md",
"category": null,
"description": "Quick-lookup catalog of all built-in tools, CLI commands, tool grant categories, scheduling syntax, and MCP discovery. Read when unsure what tools or commands are available."
},
{
"name": "identity-management",
"version": "1.1.0",
Expand Down Expand Up @@ -35,11 +45,11 @@
},
{
"name": "self-diagnostics",
"version": "1.1.0",
"version": "1.2.0",
"minimumDaemonVersion": "0.1.0",
"sha256": "279d639d36b31c1b88d43bbba3f0e16a0f61efa7abb436aa905477b511a97e9a",
"sizeBytes": 3076,
"url": "https://feeds.netclaw.dev/skills/.system/files/self-diagnostics/1.1.0/SKILL.md",
"sha256": "52d1c01cbdc95f76f6b758d90a659a40bf8d3ba75aaf89c1a87484b187c91e15",
"sizeBytes": 3191,
"url": "https://feeds.netclaw.dev/skills/.system/files/self-diagnostics/1.2.0/SKILL.md",
"category": null,
"description": "Read when sessions timeout, connections fail, tools are missing, or the user reports errors. Covers netclaw doctor, logs, MCP status, and memory health."
},
Expand Down
Loading
Loading