Your first sub-agent in 30 minutes

Sub-agents are the answer to "I do the same thing every day and prompt it twenty times". You encapsulate the instruction and the flow once into a sub-agent, and Claude Code spawns it from then on at the push of a button. Everything you learned in Level 5 about CEO-Worker pattern, in a concrete 30-minute build.

If you go through this, you end up with a sub-agent that for example does "turn this ticket into a clean GitHub PR title and body" without you having to explain conventions every time.

1. Pick a use case

Find a task you do at least three times a week by hand and that has clear input and output. Examples that work well:

• From a bug description generate a clean GitHub issue title + labels
• From a voicenote transcription pull a list of tasks
• From a customer email thread build a CRM update snippet
• From an idea write a Reddit post variant in second-person

Bad use case: "Research XY". Too open-ended; for that you need the research agent (Level 5), not a small sub-agent.

A tip: if you can't decide, take the first item from the list above. Everyone needs that, and you can transfer the lessons to other use cases.

2. Create the agents folder

In your Claude Code setup (either globally under ~/.claude/agents/ or project-specific under .claude/agents/):

mkdir -p ~/.claude/agents
cd ~/.claude/agents
touch ticket-formatter.md

The filename is the agent's slug. No spaces, use dashes.

3. Write the agent frontmatter

At the top of ticket-formatter.md goes YAML frontmatter with three fields: name, description, tools.

---
name: ticket-formatter
description: "Use this agent when the user pastes a raw bug description or Slack message and wants a clean GitHub-Issue title + body + labels. Trigger when user says 'turn this into a ticket' or 'format as issue'."
tools: ["Read", "Write"]
---

The description is the most important field. Claude Code reads it and decides on its own when to invoke the sub-agent. Be specific, use concrete trigger phrases the user is likely to say.

A tip: if the description is vague ("helps with tickets"), the agent gets triggered either never or too often. Better to name two concrete trigger phrases explicitly than one general description.

4. Write the system prompt

Below the frontmatter goes the actual system prompt. That's Markdown. Structure it like this:

You are a GitHub Issue Formatter. Your job is to take raw text
(bug reports, Slack pastes, voice memo transcripts) and turn it
into a clean GitHub Issue.

Output Format (always exactly this structure):
- Title: max 70 chars, imperative ("Fix login redirect", not "Login is broken")
- Body: 3-5 short sentences max, no marketing
- Labels: pick from {bug, feat, docs, infra, security}
- Priority: pick from {p0, p1, p2, p3} based on user pain

Rules:
- Title MUST be in English even if input is German.
- Body in same language as input.
- If input is too vague, write "Title: NEEDS CLARIFICATION" and list 2 questions.

Concrete output spec > vague instructions. The agent is good when output is formally consistent, not when it's creative.

5. Keep the tool list minimal

In tools: only list the tools the agent really needs. For ticket-formatter you actually don't need any (it gets text, returns text), but Read/Write is useful in case it should read conventions from a CONVENTIONS.md.

If you omit tools:, the agent has access to all tools. That's usually too much and makes the agent unfocused.

6. First test

In Claude Code:

"Format this as a GitHub ticket: [paste raw bug-text]"

Claude Code matches the description, spawns the sub-agent automatically. You see in the output that ticket-formatter is active. Output comes back.

If Claude Code does NOT spawn the agent: description was too vague or trigger phrase too far from the user prompt. Sharpen the description.

A tip: you can also explicitly invoke sub-agents with "use the ticket-formatter agent on this text". That bypasses auto-detection. Useful in the early phase to test.

7. Check output on a real task

Take two or three real bug reports from your backlog and have the agent format them. Check:

• Is the title consistent in form (imperative, max 70 chars)?
• Are the labels accurate?
• Did it over- or undershoot on priority?
• For vague inputs: did it use the "NEEDS CLARIFICATION" logic?

If not, the system prompt isn't specific enough. Iterate.

8. Build in edge cases

What happens if the user mixes two bugs in one text? What if the text is in Spanish? What if they enter a feature request instead of a bug?

The first draft of a sub-agent doesn't handle these cases. It mashes them into a bad output. You build the handling into the system prompt:

If input contains MULTIPLE distinct issues, output one ticket per issue
in a numbered list.
If input is in Spanish or German, body language follows input.
If input is a feature request (not a bug), use Title prefix "[Feat]" 
and body must include "Why this matters: ..." section.

Test it. Iterate.

9. Put it into use

Once the agent is stable, use it for a week on all tickets. Collect the two or three cases where it screws up. Iterate the system prompt once more.

Sub-agents don't get perfect in one go. The value comes from two or three iterations on real inputs. You invest one hour upfront, then save five per week.

10. Build more sub-agents from the same template

Once your first sub-agent is stable, you can repeat the pattern for three to five other tasks. Examples:

• commit-msg-writer (turn a diff into a clean commit message)
• slack-summarizer (turn a Slack conversation into a decision note)
• lead-qualifier (turn an email inquiry into lead score + next action)

The advantage of multiple small sub-agents over one universal agent: each has a clear trigger and clear output. Claude Code picks the right one automatically. Maintenance per agent is small.

If you eventually have twenty sub-agents and Claude Code has trouble picking the right one, you need special triggers (slash commands, hot words). But that's phase two. For now, three agents is a good state.