# Create Subagent

> Scaffolds a new subagent in a local marketplace repository: creates the agent directory and AGENTS.md file directly inside the chosen plugin. Use when the user asks to add a subagent, create an agent, or scaffold a subagent in the marketplace.

- Skill: `lichens-innovation/create-subagent` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add lichens-innovation/create-subagent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lichens-innovation/create-subagent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Lichens-Innovation (https://skillmd.com/u/lichens-innovation)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lichens-innovation/create-subagent

---


# Create Subagent

Scaffold a new subagent directly inside the chosen plugin of a local marketplace. The root `agents/` folder is auto-generated by CI — do not create files there manually.

For Claude Code, subagents are distributed via plugins. The AGENTS.md format is also compatible with other coding tools (Cursor, Copilot, Codex, Gemini, VS Code, Zed).

## User's intention

$ARGUMENTS

## References

Consult the relevant doc(s) before generating subagent content in auto mode or before making structural decisions in manual mode:

- [`docs/subagents.md`](${CLAUDE_SKILL_DIR}/../../../../docs/subagents.md) — subagent usage, AGENTS.md format, coordination tips
- [`docs/plugins.md`](${CLAUDE_SKILL_DIR}/../../../../docs/plugins.md) — plugin structure, manifest, hooks and relative paths
- [`docs/hooks.md`](${CLAUDE_SKILL_DIR}/../../../../docs/hooks.md) — hook lifecycle, PreToolUse / PostToolUse, hook scripts
- [`docs/skills.md`](${CLAUDE_SKILL_DIR}/../../../../docs/skills.md) — skill format, popular repositories, skills CLI
- [`docs/marketplace.md`](${CLAUDE_SKILL_DIR}/../../../../docs/marketplace.md) — marketplace structure, registration, publishing, versioning, auto-updates
- [`docs/rules.md`](${CLAUDE_SKILL_DIR}/../../../../docs/rules.md) — rules format and scope
- [`docs/mcp.md`](${CLAUDE_SKILL_DIR}/../../../../docs/mcp.md) — MCP server configuration
- [`docs/memory.md`](${CLAUDE_SKILL_DIR}/../../../../docs/memory.md) — memory system, persistent memory for subagents
- [`docs/skills-cli.md`](${CLAUDE_SKILL_DIR}/../../../../docs/skills-cli.md) — skills CLI commands
- [`docs/claude-code.md`](${CLAUDE_SKILL_DIR}/../../../../docs/claude-code.md) — Claude Code settings, commands, IDE integrations

## Workflow

1. **Create agent file** — the form data submitted by the user was injected into your context as `additionalContext` by the `UserPromptExpansion` hook. It is a JSON object with `mode` and `target` fields.

   **Target dispatch** — the JSON includes a `target` field that determines where the subagent lives:
   - `target: "marketplace"` — the JSON has `marketplacePath` and `plugin`. Write to `<marketplacePath>/plugins/<plugin>/agents/<name>/AGENTS.md`.
   - `target: "project"` — the JSON has `projectPath` (the user's cwd). Write to `<projectPath>/.claude/agents/<name>.md` as a single file (no enclosing directory). This is a project-local subagent, not registered in any marketplace.

   Behaviour also depends on `mode`:

   **Auto mode** (`mode: "auto"`) — the JSON contains `{ mode, target, name?, idea, triggers, tools, ...destination }` where `destination` is either `{ marketplacePath, plugin }` or `{ projectPath }`, and `triggers`/`tools` are string arrays:
   - Use `name` if provided, otherwise derive a concise kebab-case name from the idea.
   - Build the `description` frontmatter value:
     - Take the first sentence of `idea` as the "what" clause.
     - If `triggers` is non-empty, append `Use when ` + the chips joined naturally (Oxford-style with "or" before the last item). If empty, append `Use when <trigger condition>.` as a placeholder.
     - Clip the full description to 140 characters.
   - Set the `tools` frontmatter to the comma-joined `tools` array (or omit the line if empty).
   - Generate complete, ready-to-use AGENTS.md content: a clear role description, when-to-apply conditions, full step-by-step workflow, and expected output format — as if a domain expert wrote it. Do not leave placeholder text.

   **Manual mode** (`mode: "manual"`) — the JSON contains `{ mode, target, name, description, triggers, tools, ...destination }` where `triggers` and `tools` are string arrays:
   - Use all provided values as-is.
   - Build the `description` frontmatter: `"<description>. Use when <triggers joined with ', ' and 'or' before the last>."` If `triggers` is empty, use the raw description only.
   - Set the `tools` frontmatter to the comma-joined `tools` array (or omit if empty).
   - Create a minimal skeleton the user will fill in:

   ```markdown
   ---
   name: <name>
   description: "<built description>"
   tools: <comma-joined tools>
   ---

   # <Title Case of name>

   Instructions for AI coding agents acting as <name>. See [agents.md](https://agents.md/) for the format.

   ## Role — workflow

   ### When to apply

   <triggers joined as a sentence, or a placeholder if empty>

   ### Workflow

   1. Step one
   2. Step two

   ### Output

   Describe the expected output format here.
   ```

2. **Hooks**
   If the subagent needs event hooks, add them to the plugin rather than user settings so they're distributed automatically. See [Hooks and Relative Paths](${CLAUDE_SKILL_DIR}/../../../../docs/plugins.md#hooks-and-relative-paths).

3. **Report to user**
   - Report the path where the subagent was created:
     - Marketplace target: `<marketplacePath>/plugins/<plugin>/agents/<name>/AGENTS.md`
     - Project target: `<projectPath>/.claude/agents/<name>.md`
   - Next steps:
     - Fill in the file with the full workflow (manual mode)
     - For marketplace targets only: update the marketplace so the agent becomes visible: `claude plugin marketplace update`
     - Project subagents are picked up automatically by Claude Code running in that project.