Skip to content
AgentAtlas

Factory Droid Custom Droids (Subagents): .factory/droids Markdown Files

How do I create a custom droid (subagent) in Factory Droid?

Add a Markdown file with YAML frontmatter to .factory/droids/ in your repo or ~/.factory/droids/ for personal use. The name field sets the subagent_type, and the body is the system prompt. You can also run /droids and pick Create a new Droid.

What custom droids are

Custom droids are reusable subagents defined as Markdown files. The Task tool runs them with their own prompt, tools and model. They are enabled by default, and you can turn them off in /settings under Experimental.

File locations

  • Project: <repo>/.factory/droids/. Shared through version control.
  • Personal: ~/.factory/droids/. Available in all your workspaces.
  • Only top level files in these folders are scanned.
  • A project droid overrides a personal droid with the same name.

Frontmatter fields

  • name (required): lowercase letters, digits, - or _. It becomes the subagent_type.
  • description (optional): shown in the /droids list. Over 500 characters triggers a validation warning.
  • model: inherit (the default, uses the parent session model) or a model ID. Custom BYOK models use the custom: prefix.
  • reasoningEffort (optional): low, medium or high. Ignored when model is inherit.
  • tools (optional): leave it out for all tools, use a category such as read-only, edit, execute, web or mcp, or list tool IDs like ["Read", "Grep"]. Names are case sensitive.
  • mcpServers (optional): names of configured MCP servers the droid may use.

Example droid

.factory/droids/code-reviewer.md

---
name: code-reviewer
description: Reviews a diff for correctness and test risks
model: inherit
tools: read-only
---
Summarize the change, then flag correctness and test risks.
Reply in this format:
Summary: ...
Findings: ...

Create and run droids

  • Run /droids, choose Create a new Droid, and follow the wizard.
  • Or ask the assistant to use the GenerateDroid tool to draft one from a description.
  • The parent agent runs a droid by calling the Task tool with subagent_type set to the droid name. You can also just ask for it by name, for example: Use the subagent security-sweeper on the files I changed.

Sources

More Factory Droid guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →