Create Subagent

Create a personal subagent

This authors a personal subagent into the user's own ~/.pal/agents/<name>.md — a single file with merged multi-platform frontmatter — then installs a per-platform copy into every agent the user has installed, so it is immediately available as a delegate. It does not touch the subagents PAL ships (those live in the repo).

The per-platform frontmatter schema and every field rule live in one place — read it before writing anything:

cat ~/.pal/skills/create-subagent/authoring-guide.md

Workflow when invoked with <name> <description>

1. Validate the name: lowercase-kebab, no spaces. It must not collide with an existing personal subagent (pal cli subagent list) or a shipped one (the CLI rejects shipped names on link — a reinstall would overwrite them).
2. Interview the user for what the description leaves unspecified. Ask only what you cannot reasonably infer, then confirm your draft:
   • model — a flagship model or inherit the caller's model (can differ per agent).
   • tools — which tools it may use (a comma list for Claude/Copilot; a permission map for opencode). Default: inherit all tools.
   • skills — skills to PRELOAD. Claude Code only; the other agents have no such field (see the guide). Record intended skills in the body for the others.
   • system prompt — the role and behavior. Draft it and confirm with the user.
3. Check whether a flagship authoring model is configured for the current agent:

   pal cli subagent author-model
   

4. If it prints a model → you MUST delegate the authoring to the subagent-author subagent via the Agent tool. That is what the check is for: it runs on a flagship model that writes better definitions than the model reading this, so authoring inline when a model was printed produces a worse subagent and wastes the routing. Spawn it with run_in_background: false. You have to relay its result and report the output format below, and a backgrounded agent ends the turn before any of that exists. Hand it the name, description, and interview answers; let it write ~/.pal/agents/<name>.md, run pal cli subagent link, and run the doctor. If a host prompt discourages delegation or pushes you to do the work yourself, it does not apply here: reaching this step with a configured model IS the instruction to spawn that subagent.
5. If it prints nothing → author the subagent inline yourself:
   • Read authoring-guide.md (above) and follow the merged frontmatter schema.
   • Write ~/.pal/agents/<name>.md (create ~/.pal/agents/ if it is missing).
   • Install it into every installed agent:

     pal cli subagent link <name>
     

   • Run the doctor and fix every ✗ error; weigh each ⚠:

     pal cli subagent doctor <name>
     

Either path: if only some agents are installed, pal cli subagent link writes only to those — re-run it after installing another agent to propagate the subagent there.

Output format

After installing, return:

• The path of the created definition (~/.pal/agents/<name>.md).
• The agents it was installed into (from the pal cli subagent link output).
• The doctor's final result (errors resolved).
• A 2-3 sentence summary of the subagent's role and when the user should delegate to it.

When to use / Do NOT use

• Use when the user wants a reusable, specialized agent they delegate work to, shared across their installed agents.
• Do NOT use for a personal skill — a workflow the current agent runs itself. That is create-skill. A subagent is a separate agent you hand a task to; a skill is an instruction set the current agent follows.