wangjunxiao/nanoclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add self-customize skill and refine communication guidance

Browse Source 
Self-customize skill lives in container/skills/ so it's loaded into the
agent container at runtime. Documents the builder-agent pattern with
diff size limits for safer self-modification.

CLAUDE.md communication section now has three tiers (short / longer /
long-running) instead of a single blanket rule — agents should
acknowledge upfront on longer work and update before slow operations,
but stay silent on quick tasks.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
gavrielc
2026-04-10 15:02:32 +03:00
parent 6eb81b5737
commit 4004a6b284
2 changed files with 100 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
container/skills/self-customize/SKILL.md Normal file
View File

@@ -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: "<builder prompt>" })` — the returned agent group ID is your builder
3. Call `send_to_agent({ agentGroupId, text: "<task description with specific files and changes>" })`
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: "<builder prompt from above>" })`
- `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

12
groups/global/CLAUDE.md
View File

@@ -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