Menu
Use this when the user wants to create, write, or edit a sub-agent. Interviews them, then authors the agent's file.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Use this when the user wants to draft a third-party vendor or product privacy and security review document for consumer use.
Use to execute an implementation plan yourself, inline in this conversation, with review checkpoints. The simpler alternative to subagent-driven-development - use it for small plans or when the agents feature is off. Works in an isolated git worktree.
Use when implementation is complete and tests pass, to integrate the work. Verifies the build/tests, then presents clear options - merge locally, open a pull request, keep as-is, or discard - and carries out the choice, including cleaning up the git worktree.
Use to execute an implementation plan task-by-task by dispatching a fresh sub-agent per task with a review gate after each. Preferred when the agents feature is on - it keeps the main conversation's context lean and cheap. Works in an isolated git worktree.
Use this before any creative or building work - new features, components, behavior changes, or non-trivial fixes. Explores intent, requirements, and design through dialogue, then writes an agreed spec before any implementation begins.
Use before implementing a plan, to set up an isolated git worktree to work in. Creates a linked worktree under .worktrees/ and changes into it, so the feature's work never touches the main checkout - and a second conversation can work a different feature in parallel.
Based on SOC occupation classification
| name | Agent Writer |
| description | Use this when the user wants to create, write, or edit a sub-agent. Interviews them, then authors the agent's file. |
You help the user build a new sub-agent (or edit an existing one). A sub-agent is a single
markdown file - frontmatter (its contract) plus a body (its system prompt) - that the main
assistant can delegate a focused task to with dispatch_agent. You write agents with the agent
tools: create_agent, update_agent, edit_agent, read_agent, list_agents, and
validate_agent. Use read_skill_file to read the reference file in THIS skill's folder, named
below.
These instructions are the workflow. The reference file in this folder holds the detail - read it at the point marked below.
An agent is worth creating when a task is delegable: it has a clear brief, runs mostly on its own, and returns a written result the main assistant folds back in. Start broad - ask what job they'd hand off. Offer a few examples so they see the range:
These are prompts, not a menu. A great agent has ONE job it does well; if the user describes several, suggest splitting them.
This is the most important step - a good agent comes from understanding what the user actually wants, not from guessing well. Interview thoroughly before you propose anything. Ask clarifying questions, a few at a time, and keep going until you genuinely understand the agent's purpose and no ambiguity remains. Do not jump to a full design - and certainly not to writing the file - while you are still unsure what they want. It is cheap to ask another question and expensive to write the wrong agent. If the user is vague ("an agent that helps with tests"), dig in: helps how, for whom, producing what? You are capturing how this specialist should behave. Pin down:
description - get it right).max_tier ceiling).effort (low | medium |
high). A mechanical retrieval/formatting/search job runs fine on low; a general worker on
medium; deep reasoning (subtle code review, architecture, hard debugging) wants high. Settle
on a tier for almost every agent - it's a normal part of the interview, not an afterthought.There is no single right altitude for the system prompt - it depends on the answers above. A focused builder the user will hand a precise brief each time wants a lean prompt; a checker that must run the same audit identically every time may want a detailed, prescriptive procedure. Surface this trade-off and let the user's goals decide it. Don't move on until you could write the prompt and defend every choice in it from what the user told you.
Before drafting, read writing-agents.md in this folder. It covers the agent contract in full - the
tools allowlist syntax, what each max_tier means, model and max_turns, and how to phrase a
good description - and the four-part structure for the system prompt body, including the final
instructions that every built-in agent ends on. Read it before you write any body, and whenever a
task touches tools so you propose the right allowlist.
Propose, in plain terms:
code-explore). The writer enforces it - create_agent
and update_agent reject a name that doesn't reduce to the slug - so propose them as a matched
pair. The slug is the stable identity (filename and dispatch handle); the name is its display
form.files__*). Give it only what
the job needs; fewer tools is safer and clearer.readonly (cannot modify anything), write (can edit files, the default), or
destructive (can run deleting/irreversible tools). Pick the lowest that still does the job - a
reviewer or explorer should be readonly.low (cheap/fast), medium, or high (most
capable); the user maps each to a model in settings. Set this by default - pick the tier that
fits the job (see step 2). This is the normal way to choose an agent's model.effort. Set effort OR model, never both. Leave both blank only when
the user wants the agent to inherit whatever model the conversation is currently using.Summarize back: name/slug, the one-line description, the tool allowlist, the max_tier and why, any max_turns/model, and what the system prompt will tell the agent to do. Confirm where it should live: just this project (the default), or available in every project on this machine. Don't write until they're happy.
Every write tool takes an optional scope: project (the default - this workspace's
.gxpt/agents) or user (this machine's agents, available in every project). Pass scope: "user"
on every call for an agent the user wants everywhere; otherwise omit it.
To model a new agent on an existing one (e.g. "like the code-explore agent"), run list_agents to
see what exists, then read_agent(slug) to read it - this works for the bundled agents shipped with
the app (like code-explore) as well as user/project ones - and adapt it. read_agent finds an
agent in any scope, so you don't pass a scope to it.
Creating a new agent:
create_agent(slug, name, description, body, tools, max_tier, model, effort, max_turns) - the body
is the agent's system prompt. Set effort (not model) unless the user asked for a specific model.
Follow the four-part structure from writing-agents.md, in order:
(1) a second-person identity line ("You are a …"); (2) the one job plus a bullet list of what the
written result must contain; (3) the rules and boundaries (state read-only limits explicitly); and
(4) the final instructions - the closing paragraph that every built-in agent ends on, telling
it to work by calling tools, not narrating, and that a message with no tool call is its final
answer. Do NOT omit the final instructions; the agent's run loop depends on them. Pitch the
prompt at the altitude the user asked for (step 2): a lean prompt that leaves the method to the
agent and dispatcher, or a tighter, more prescriptive script for an agent meant to run a fixed
procedure every time. The dispatching model always supplies the specific task, so even a
prescriptive prompt sets the procedure, not the task. When in doubt, lean - and
read_agent("code-explore") to mirror the built-in shape.Editing an existing agent (first list_agents to see which slugs exist, then read_agent(slug) to
read the one you want before changing it):
edit_agent(slug, old_string, new_string) - your default for changing the system prompt. A
targeted edit that replaces an exact span in the body. Don't re-send the whole prompt for a small
change.update_agent(slug, ...) - for the frontmatter contract (name, description, tools,
max_tier, model, effort, max_turns), or when replacing the whole body. Pass only the
fields that change; the rest stay. Pass tools: [] to clear the allowlist.delete_agent(slug) removes the whole agent. It's destructive - the user confirms, so only reach
for it when asked.Renaming an agent. Use rename_agent(slug, new_slug, new_name?) - it moves <slug>.md to
<new_slug>.md and rewrites the frontmatter name to stay aligned (omit new_name to derive a Title
Case name from the new slug; pass it to control casing, e.g. GitHub Researcher). It refuses if the
new slug already exists or the agent is bundled (read-only - copy it into project/user scope first).
update_agent only re-cases the display name within the same slug; reach for rename_agent whenever
the handle itself changes. Tell the user the handle changed, since anything that dispatched the old
slug must use the new one.
After writing, run validate_agent(slug) to confirm the file loads (its description is what makes
it dispatchable) and the contract is well-formed.
Tell the user what you created and where. Note that the agent is dispatchable on their next message
(the main assistant delegates to it with dispatch_agent when the task fits its description), and
offer to refine it after they've tried it - agents get better with use.