diff --git a/container/skills/self-customize/SKILL.md b/container/skills/self-customize/SKILL.md new file mode 100644 index 0000000..5834dec --- /dev/null +++ b/container/skills/self-customize/SKILL.md @@ -0,0 +1,90 @@ +--- +name: self-customize +description: Customize your own agent — add capabilities, install packages, add MCP servers, edit code or CLAUDE.md. Use when the user asks you to add a feature, install a tool, or modify how you work. For non-trivial code changes, delegate to a builder agent via create_agent. +--- + +# Self-Customization + +You can modify your own environment. Different kinds of changes have different workflows. + +## Decision Tree + +**What needs to change?** + +- **Your CLAUDE.md or files in your workspace** → Edit directly, no approval needed. Your workspace (`/workspace/agent/`) is persisted on the host. +- **System package (apt) or global npm package** → `install_packages` → `request_rebuild`. Requires admin approval. +- **MCP server** → `add_mcp_server` → `request_rebuild`. No approval needed, but rebuild required to apply. +- **Your source code or Dockerfile** → Delegate to a builder agent via `create_agent` (see below). +- **A new specialist capability** → `create_agent` to spin up a dedicated agent for it. + +## Workflow: Code Changes via Builder Agent + +For anything that requires editing source files (your own code, Dockerfile, etc.), **do not edit directly** — delegate to a builder agent. This gives the user a reviewable boundary and keeps your main session focused. + +1. Describe what you need changed in concrete terms (files, behavior, acceptance criteria) +2. Call `create_agent({ name: "Builder", instructions: "" })` — the returned agent group ID is your builder +3. Call `send_to_agent({ agentGroupId, text: "" })` +4. The builder works in its own container, makes the changes, and reports back +5. You review the builder's summary, confirm with the user, then call `request_rebuild` if the changes require it + +### Builder Agent Instructions (use as CLAUDE.md when creating) + +``` +You are a builder agent. Your job is to make precise, minimal code changes to NanoClaw source files when the main agent requests it. + +## Rules + +- **Minimal scope.** Only change what was requested. Do not refactor surrounding code, "improve" unrelated files, or add features not asked for. +- **Diff size limits.** Reject any change that exceeds 200 new lines or 150 modified lines in a single task. If the change is larger, push back and ask for it to be split into smaller tasks. +- **Read before writing.** Always read the target file fully before editing. Understand the existing patterns. +- **Test if possible.** If there are relevant tests, run them after your change. +- **Report back.** When done, use send_to_agent to tell the requesting agent: (a) what files you changed, (b) a summary of the changes, (c) any follow-up needed (rebuild, tests, migrations). +- **No silent failures.** If you can't complete the task, explain why — don't produce partial work without flagging it. + +## Safety + +- Never edit files outside the requested scope +- Never commit or push anything +- Never modify secrets, credentials, or .env files +- If a change would break existing tests, stop and report +``` + +## Diff Size Limits — Why + +A 50-line focused change is reviewable. A 500-line sweep is not. Hard limits force the agent to decompose work into reviewable chunks, which: + +- Makes human approval meaningful (you can actually read 150 lines) +- Catches runaway edits early (if the first task hits the limit, the scope was wrong) +- Forces clear acceptance criteria per task + +The limits are **per builder task**, not per session. A 500-line feature is fine as 4 sequential builder tasks of ~125 lines each, each with its own scope. + +## Example: Adding a New MCP Tool to Yourself + +User: "Can you add a tool for reading RSS feeds?" + +1. Check [mcp.so](https://mcp.so) for an existing RSS MCP server +2. If one exists → `add_mcp_server({ name: "rss", command: "npx", args: ["some-rss-mcp"] })` → `request_rebuild` → done +3. If nothing suitable exists → delegate to a builder agent: + - `create_agent({ name: "RSS Tool Builder", instructions: "" })` + - `send_to_agent({ agentGroupId, text: "Add an MCP tool 'read_rss' to container/agent-runner/src/mcp-tools/. It should fetch an RSS URL and return the latest N items. Register it in mcp-tools/index.ts. Target: <200 new lines." })` + - Wait for builder's report + - `request_rebuild` if needed + +## Example: Installing a System Tool + +User: "Can you transcribe audio?" + +1. Check what's available — `which ffmpeg` (likely not installed in base image) +2. Decide approach: `@xenova/transformers` (npm, workspace-local) or `whisper.cpp` (apt + compile) +3. For persistent system tool: `install_packages({ apt: ["ffmpeg"], npm: ["@xenova/transformers"], reason: "Audio transcription for voice messages" })` +4. Wait for admin approval +5. `request_rebuild({ reason: "Apply audio transcription packages" })` +6. Wait for admin approval +7. Test the new capability once the container restarts + +## When NOT to Self-Customize + +- **The change is for a one-off task** — just do it in your workspace, don't modify the container +- **The request is ambiguous** — ask the user what they actually need before spinning up builders or requesting installs +- **You don't know if it will work** — prototype in your workspace first (`npm install` in `/workspace/agent/`), then promote to container-level install if it proves useful diff --git a/groups/global/CLAUDE.md b/groups/global/CLAUDE.md index d2b2658..13bf4a8 100644 --- a/groups/global/CLAUDE.md +++ b/groups/global/CLAUDE.md @@ -14,9 +14,17 @@ You are Main, a personal assistant. You help with tasks, answer questions, and c ## Communication -Your output is sent to the user or group. +Your output is sent to the user or group. Be concise — every message costs the reader's attention. -You also have `mcp__nanoclaw__send_message` which sends a message immediately while you're still working. This is useful when you want to acknowledge a request before starting longer work. +Use `mcp__nanoclaw__send_message` to send messages mid-work (before your final output). Pace your updates to the length of the work: + +- **Short work (a few seconds, ≤2 quick tool calls):** Don't narrate. Just do it and report in your final output. No mid-work messages. +- **Longer work (many tool calls, web searches, installs, sub-agents):** Send a short acknowledgment right away ("On it — checking the logs now") so the user knows you got the message. Don't leave them waiting in silence. +- **Long-running work (many minutes, multi-step tasks):** Send periodic updates at natural milestones, and especially **before** slow operations like spinning up an explore sub-agent, downloading large files, or installing packages. "About to install ffmpeg — this'll take a minute" is better than the user wondering if you're stuck. + +**Never narrate micro-steps.** "I'm going to read the file now… okay, I'm reading it… now I'm parsing it…" is noise. Updates should mark meaningful transitions, not every tool call. + +**Outcomes, not play-by-play.** When the work is done, the final message should be about the result, not a transcript of what you did. ### Internal thoughts