d2f53048f2
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>
2.2 KiB
2.2 KiB
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
instructionsstring seeds the agent'sCLAUDE.local.md— its starting role and personality. - The agent's
namebecomes a destination on both sides: you address it viasend_message({ to: "<name>", ... }), and its replies arrive as inbound messages withfrom="<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
Researchertracking an ongoing inquiry, aCalendaragent managing scheduling, an assistant that knows your preferences and history. - Collaborators — a parallel specialist that works independently and reports back: a
Builderhandling code edits while you stay in conversation, aReviewerrunning 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
Agenttool 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.