agentleFS
shadcn-labsshadcn-labs/agentcn/.agents/skills/mastra-file-agents/SKILL.md

mastra-file-agents

Skill506 starsChanged 5 months agoMITView on GitHub

Migrate Mastra code-based agents (agents built with new Agent(...) and registered in a Mastra({ agents }) map) to the file-based convention: one directory per agent under src/mastra/agents. Use when the user wants to convert or refactor Mastra agents to the per-directory convention, mentions Mastra "file-based agents" or agentConfig, or wants to split a big src/mastra/index.ts or agents.ts into one folder per agent — even if they do not name this skill. Requires @mastra/core 1.48+.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 1

    1. shadcn-labs/skills★ 2557% same

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository2 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    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 …

    line 33
  2. Very specific:

    Use agentConfig() so the partial is typed and sibling files fill the rest:

    line 80
  3. Very specific:

    If the original instructions was a function (dynamic instructions that read runtime context), it CANNOT live in instructions.md.

    line 99
  4. Very specific:

    If a tool is shared by multiple agents, don't force it into one agent's tools/.

    line 135
  5. Very specific:

    Keep the shared tool in a common module and reference it from config.tools, or duplicate deliberately.

    line 136
  6. Distinctive:

    Do not drop these during migration — losing an agent's memory or subagent silently changes behavior.

    line 145
  7. Distinctive:

    Leave code-registered any agent that must stay in code: direct-import/library usage, programmatic or dynamic registration, or a shared …

    line 155
  8. Distinctive:

    Run the app through the CLI so the bundler discovers the new directories:

    line 161

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

Step 1: Find the code-based agents

Locate every new Agent({...}) and how it is registered. Usually the registration is in src/mastra/index.ts inside new Mastra({ agents: { ... } }), but agents may be defined in separate files (src/mastra/agents/*.ts, a big agents.ts) and imported. Read the full Agent config for each — you need every option to map it faithfully. Note the key used in the agents map — that key is how the agent is registered and looked up (e.g. mastra.getAgent('weather'), Studio, client SDK), and it becomes the directory name.

Step 2: Create the directory and split the config

For an agent registered as agents: { weather: weatherAgent }, create src/mastra/agents/weather/.

Name the directory after the map key, not the id. The directory name becomes the agent's registration/lookup key, so using the map key preserves every existing getAgent(...) call and client reference. This matters when the map key differs from the id — e.g. agents: { browserAgent } where new Agent({ id: 'browser-agent' }). Name the folder browserAgent (the key), and because id/name would otherwise default to browserAgent, set them explicitly in config.ts to keep the original 'browser-agent' / 'Browser Agent'. If the map key and id already match, id/name default to the folder and you can drop them.

config.ts — everything except instructions and tools that were passed inline. Use agentConfig() so the partial is typed and sibling files fill the rest:

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.5',
  // instructions omitted -> taken from instructions.md
  // tools omitted -> taken from tools/*.ts
})

model is required — a missing model fails the build and names the directory.

instructions.md — if the original instructions was a string (or array of static strings/messages), move the text into instructions.md and omit instructions from config.ts. instructions.md wins over a static instructions string, so leaving both is redundant.

If the original instructions was a function (dynamic instructions that read runtime context), it CANNOT live in instructions.md. Keep it in config.ts — dynamic function instructions win over instructions.md. See references/mapping.md.

Step 3: Split out the tools

Each tool becomes its own file under tools/, default-exporting the createTool() call. The filename becomes the tool key, so name the file after the key used in the original tools map (or the tool's id). If the original was tools: { get_weather: getWeatherTool }, the file must be tools/get_weather.ts.

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export default createTool({
  id: 'get_weather',
  description: 'Get the current weather for a city',
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ context }) => ({ city: context.city, tempC: 21 }),
})

Tools from tools/*.ts merge with any config.tools. On a key collision config.tools wins (with a warning), so don't list a tool in both places. If config.tools is a function, discovered tool files are ignored — in that case keep tools in config.ts and say so. Test files (*.test.ts, *.spec.ts, etc.) are ignored by discovery.

Not every tool is a createTool(). Provider-native tools (e.g. openai.tools.webSearch({})) and other pre-built tool objects don't fit the createTool() shape. Either leave them inline in config.tools, or default-export the tool object from a tools/<key>.ts file — both are discovered. When in doubt, keeping a provider tool in config.tools is the simplest faithful move. Reserve tools/*.ts files for the project's own createTool() definitions.

If a tool is shared by multiple agents, don't force it into one agent's tools/. Keep the shared tool in a common module and reference it from config.tools, or duplicate deliberately. Note the choice for the user.

Step 4: Handle the remaining surfaces

Memory, workspace, skills, and subagents each have their own file/directory and precedence rules. When the agent you're migrating uses any of them, read references/mapping.md for the exact mapping and gotchas (dynamic-config caveats, subagent description requirement, seed files, etc.). Do not drop these during migration — losing an agent's memory or subagent silently changes behavior.

Step 5: Remove the code registration

This is what completes the migration (gotcha 2). Delete the agent's entry from the Mastra({ agents: {...} }) map, then remove imports and definitions that are now unused — if the old new Agent(...) lived in its own file and nothing else imports it, delete that file.

Leave code-registered any agent that must stay in code: direct-import/library usage, programmatic or dynamic registration, or a shared instance imported elsewhere. Both styles coexist fine.

Step 6: Verify

Run the app through the CLI so the bundler discovers the new directories:

npx mastra dev

npx mastra build is a good non-interactive check when you can't start the dev server — it runs the same discovery and fails loudly on missing models, missing subagent descriptions, or unresolved directories. If dependencies aren't installed in your environment, say so and mark verification as structural only rather than claiming it runs.

Confirm each migrated agent still appears (under its original registration key) and responds, and that no "code agent overrides file-based" or "config.X wins" warnings are logged (those signal a leftover collision or a redundant config entry). Fix warnings before calling it done.

Mapping cheat sheet

new Agent({...}) optionFile-based location
agents map keyDirectory name (preserves registration/lookup key)
id / nameDefault to directory name; set explicitly in config.ts when they differ from the folder
modelconfig.ts (required)
instructions (string/array)instructions.md
instructions (function)keep in config.ts
descriptionconfig.ts (required for subagents)
tools: { key: createTool(...) }tools/<key>.ts (default export)
provider/pre-built tools (e.g. openai.tools.*)keep in config.tools, or default-export from tools/<key>.ts
skillsskills/ (see references/mapping.md)
memorymemory.ts (see references/mapping.md)
workspaceworkspace.ts + workspace/ seed files
delegated agents (agents)subagents/<childId>/
everything elseconfig.ts via agentConfig()

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.