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

docs(module-fragments): add instructions for create_agent, interactive, and remaining core tools

Browse Source 
Three MCP tool groups were orphaned from the ambient CLAUDE.md context
because they shipped no `*.instructions.md` alongside their source.
Backfill them so the composer picks them up as fragments on next spawn:

- core.instructions.md: add `send_file` (artifact delivery, path relative
  to /workspace/agent/) and `add_reaction` (by `#N` id with emoji
  shortcode name).
- interactive.instructions.md: `ask_user_question` (blocking
  multiple-choice with selectedLabel/value option objects, 300s default
  timeout) and `send_card` (non-blocking structured render with
  fallbackText). Opens with a one-line framing of the contrast between
  the two.
- agents.instructions.md: `create_agent` with how-it-works, when-to-use
  (companions vs collaborators — persistent memory vs independent
  parallel work), when-NOT-to-use (short tasks should use the SDK `Agent`
  tool instead), and guidance for writing the seed instructions string.

No composer changes — scan in `src/claude-md-compose.ts` already picks up
any file matching `*.instructions.md` in the mcp-tools directory.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
gavrielc
2026-04-22 18:05:50 +03:00
parent 52ebdce9c9
commit d2f53048f2
3 changed files with 56 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
container/agent-runner/src/mcp-tools/agents.instructions.md Normal file
View File

@@ -0,0 +1,26 @@
## Companion and collaborator agents (`create_agent`)
`mcp__nanoclaw__create_agent({ name, instructions })` spins up a new long-lived agent and wires it as a destination — bidirectional, so you can send it tasks and it can message you back.
### How it works
- Creates a new agent with its own container, workspace, and session. Your `instructions` string seeds the agent's `CLAUDE.local.md` — its starting role and personality.
- The agent's `name` becomes a destination on both sides: you address it via `send_message({ to: "<name>", ... })`, and its replies arrive as inbound messages with `from="<name>"`.
- Each agent has its own persistent workspace under `groups/<folder>/` — memory, conversation history, and notes all survive across sessions. This is a full standalone agent, not a stateless sub-query.
- **Fire-and-forget:** the call returns immediately without waiting for the agent to confirm it's ready. Messages you send will queue until it's up.
### When to use
- **Companions** — a long-running presence that accumulates context over time: a `Researcher` tracking an ongoing inquiry, a `Calendar` agent managing scheduling, an assistant that knows your preferences and history.
- **Collaborators** — a parallel specialist that works independently and reports back: a `Builder` handling code edits while you stay in conversation, a `Reviewer` running checks in the background.
The right frame is: does this agent need its own memory and context that builds over time, or does it need to work independently without blocking your turn? Either is a good reason to spawn one.
### When NOT to use
- **One-off lookups or short tasks** — use the SDK `Agent` tool instead. It's stateless, spins up and completes in one shot, and leaves no persistent footprint.
- **Work that finishes before the user's next message** — agents persist indefinitely. Don't create one for something you could do inline.
### Writing good `instructions`
Cover: the agent's role, who it takes tasks from (you, by name), how it should report back (on completion only? with milestones for long work?), and any domain-specific rules. Don't restate NanoClaw base behavior — the shared base is already loaded on the agent's end.