agentcn: Skill for Claude Code

Migrate Mastra agents to file-based

Convert agents built in code with new Agent({...}) and registered in a new Mastra({ agents: {...} }) map into the file-based convention: one directory per agent under src/mastra/agents/<name>/, where sibling files supply what used to be constructor options.

This is a behavior-preserving refactor, not a redesign. Move each option to the file that owns it, keep the same model, instructions, tools, memory, skills, and subagents, and don't invent config the agent didn't have.

Two things that break migrations

1. File-based agents are discovered ONLY by the Mastra bundler (mastra dev / mastra build). If the app imports the mastra instance directly (Mastra used as a library, a custom server, tests that import { mastra }), agents/<name>/ directories are never discovered and the agent silently disappears. Before migrating, confirm how the app runs: through the CLI → migrate freely; imported directly → do not migrate that agent, keep it in code and tell the user why.

2. Code wins on name collisions. If an agent exists in both a config.ts directory and the Mastra({ agents }) map, the code one is kept and the file-based one is ignored (with a warning). The migration is a no-op until you remove the code registration (Step 5). Half-migrating changes nothing.

Workflow

Work one agent at a time. Copy this checklist and track it:

Migration progress for <agent>:
- [ ] Confirmed the app runs via mastra dev/build (not a direct import)
- [ ] Created src/mastra/agents/<name>/
- [ ] config.ts (agentConfig) with model + non-instruction/tool config
- [ ] instructions.md OR dynamic instructions kept in config.ts
- [ ] tools/*.ts (one default export each, filename = tool key)
- [ ] memory.ts / workspace.ts / skills/ / subagents/ if present (see references/mapping.md)
- [ ] Removed the agent from the Mastra({ agents }) map
- [ ] Deleted now-dead imports / the old agent file if nothing else uses it
- [ ] Verified with mastra dev