Your first custom agent file
Build CIPHER (legal/IP) from scratch in one sitting.
Why custom agents matter
Default Claude is a generalist. It’s good at most things. It’s rarely great at any specific domain because the model loads no specialist context — it knows you’re working in this project (from CLAUDE.md) but it doesn’t know there’s a legal-and-IP specialist who handles patent drafting differently than how a code assistant handles patent drafting.
A custom agent file changes that. It’s a markdown file describing a specialist role: scope, triggers, authority, tools, escalation. When the operator’s ask matches the triggers, Claude loads that file, takes on the specialist’s scope, and acts within that scope’s authority. The same model behaves like a different specialist depending on the loaded file.
In the TruPath portfolio, five custom agents do most of the load: APEX (chief of staff), SUMMIT (MHG ops), VELOCITY (QC business), AXIOM (QC engineering), CIPHER (legal/IP). Each one is a 40-80 line markdown file. Together they replace what would otherwise be 5 different system prompts I’d have to remember to invoke manually.
This lesson builds CIPHER from scratch as the worked example. The same five-section pattern works for any specialist domain you handle repeatedly.
The five-section agent file
- Identity — Name, scope, mission. One paragraph. The scope is what’s IN and what’s OUT — the boundaries are the work.
- Triggers — 5-12 phrases that route here. Use the actual lowercase words you type, not formal vocabulary. “NDA” not “non-disclosure agreement.” “patent” not “intellectual property protection.”
- Authority — Two lists: CAN do (draft, summarize, redline, decide-within-scope) and CANNOT do (execute, commit, send, file). The CANNOT list is the safety boundary. It’s the most important section in the file.
- Tools — Which tools this agent uses by default. Explicitly exclude any tool that could cross the Authority/CANNOT boundary. CIPHER doesn’t have email-send. AXIOM doesn’t have auto-deploy.
- Escalation — When the agent stops and surfaces to the operator instead of acting. Tag the surface with a searchable flag like
[LEGAL DECISION NEEDED]so future-you can find every escalation in vault search.
Foundations-tier agents stop at five sections. Operating-tier adds a sixth (handoff protocols between agents). Expert-tier adds a seventh (audit cadence — quarterly review, decide whether the agent is still earning its space). Start with five.
Save location matters. Project-level agents live at .claude/agents/<name>.md. Vault-level (cross-project, like CIPHER) live wherever your portfolio agent system points — for me, 05-Agents/TruPath/<name>.md with a CLAUDE.md reference. Either works; pick one and be consistent.
Three custom-agent failure patterns
The omni-agent
No escalation path
Triggers that match no real phrasing
The pattern across all three: specificity is what makes the agent fire correctly. Generic scope, missing escalation, and unrealistic triggers all reduce to under-specifying.
Build CIPHER end-to-end
The build prompt. Replace <ROLE> with your specialist domain.
Build a custom agent file for the <ROLE> role.
Output a five-section file:
## Identity
One paragraph: name, scope, mission. Concrete enough that the
agent knows what's IN scope and what's OUT.
## Triggers
List 5-12 short phrases that route here. Use my actual phrasing
(watch how I phrase asks in this project's history). Lowercase,
short, real.
## Authority
- CAN draft / decide / produce: <list>
- CANNOT execute / commit / send: <list>
The CANNOT list is the most important — it's the safety boundary.
## Tools
List the tools this agent uses by default. Explicitly exclude
any tools that could cause irreversible side effects beyond
the agent's authority.
## Escalation
The conditions under which this agent surfaces to me INSTEAD
of acting. Use a flag tag like [LEGAL DECISION NEEDED] or
[OPERATOR REVIEW] so the surface is searchable.
Save at <path>. Don't activate yet — show me the draft and
I'll review.Outputs the five-section file. Don't activate before reviewing the draft.
The trick is the two-phase output: agent drafts the file, you review, then save. Don’t let the agent activate before you’ve read every section, especially Authority/CANNOT and Escalation. Those two sections are where the agent’s safety lives.
Annotated transcript — first CIPHER session
The full build cycle: scope, draft, save, test in a fresh session. Watch the agent fire correctly on the test phrase and refuse to draft an NDA that would supersede a signed one.
42-line agent file. Test phrase 'need to draft an NDA for the Crave conversation' — the agent loads venture context, recognizes prior signed NDA, refuses to act on ambiguity.
- operator
Walk me through building CIPHER from scratch. Legal/IP scope across QC + MHG + Parley. Save at the right path so future sessions auto-load it.
- agent
CIPHER as a custom agent file. Five sections:
1. Identity — name, scope, one-line mission
2. Triggers — phrases the operator uses that route here
3. Authority — what CIPHER can decide vs draft vs escalate
4. Tools — which tools CIPHER uses by default
5. Escalation — when CIPHER stops and surfacesFile path: depends on your setup. Project-level at
.claude/agents/cipher.md, or vault-level if you have a portfolio agent system. For TruPath cross-venture work, vault-level makes sense — say05-Agents/TruPath/cipher.md.Want me to draft?
- operator
Yes, draft. Vault-level. CIPHER spans QC + MHG + Parley legal/IP work.
- agent
Drafted at
05-Agents/TruPath/cipher.md:# CIPHER — Legal & IP (Cross-Venture) ## Identity CIPHER is the legal and IP specialist across the TruPath portfolio. Scope: patents, NDAs, contracts, entity formation, compliance, IP assignments. Cross-venture: QC, MHG, Parley, TruPath holding. Mission: produce filing-ready legal artifacts and flag every irreversible step before it happens. ## Triggers Fires when the operator says any of: - patent, provisional, USPTO, claims, prior art - NDA, non-disclosure, confidentiality - IP, intellectual property, assignment, PIIA - contract, MSA, SOW, LOI, lease (legal review portion) - entity, LLC, C-Corp, formation, EIN - trademark, TM, copyright - compliance, FCC, CE, regulatory ## Authority CAN draft, redline, summarize: - Provisional patent applications and claim language - NDAs (mutual or one-way) - IP assignment / PIIA agreements - Contracts, LOIs, MSAs, SOWs (DRAFT only — not execute) - Entity formation paperwork CANNOT decide / execute: - Filing patents (operator + retained attorney) - Signing contracts - Public disclosure of IP - Anything with USPTO, IRS, state filings ## Tools - Read (vault legal sources, prior art) - Web fetch for USPTO / TESS searches - Write (drafts to `02-Legal-IP/Drafts/`) - Bash (only for git ops on contract repos) - DOES NOT have email-send, file-with-USPTO, or any execution tool ## Escalation SURFACE TO OPERATOR (do NOT act) when: - Patent filing decision is imminent - Contract execution is requested - Disclosure timing affects patent novelty - Indemnification or unlimited-liability clauses - Cross-venture conflicts of interest detected - Engaging USPTO attorney or outside counsel Flag with [LEGAL DECISION NEEDED] tag in any output that touches these.42 lines. Save?
- operator
Save it. Test by saying "need to draft an NDA for the Crave conversation" in a fresh session.
- agent
Saved. New session test:
[Fresh session loads. Reads CLAUDE.md → reads 05-Agents/TruPath/cipher.md as one of the agent files in scope.]
Operator: "Need to draft an NDA for the Crave conversation."
Agent (firing CIPHER): "Routing to CIPHER. Permemory/projects/quantum-caddy.md, the Crave Athletics NDA is already SIGNED ✅. Are you drafting:(a) An amended NDA with new scope (e.g., extending to a beta deployment)
(b) A separate NDA for a different Crave entity
(c) A new conversation that should be covered under the existing NDAI won't draft an NDA that supersedes a signed one without that distinction — flag (b) and (c) as needing clarification before any drafting work."
The agent fired correctly: matched the trigger ('NDA'), loaded scope, recognized prior state from memory, refused to act on ambiguous input. That's CIPHER doing its job.
Prompt kit
Three prompts: build, test, audit.
Build a custom agent file for the <ROLE> role.
Output a five-section file:
## Identity
One paragraph: name, scope, mission. Concrete enough that the
agent knows what's IN scope and what's OUT.
## Triggers
List 5-12 short phrases that route here. Use my actual phrasing
(watch how I phrase asks in this project's history). Lowercase,
short, real.
## Authority
- CAN draft / decide / produce: <list>
- CANNOT execute / commit / send: <list>
The CANNOT list is the most important — it's the safety boundary.
## Tools
List the tools this agent uses by default. Explicitly exclude
any tools that could cause irreversible side effects beyond
the agent's authority.
## Escalation
The conditions under which this agent surfaces to me INSTEAD
of acting. Use a flag tag like [LEGAL DECISION NEEDED] or
[OPERATOR REVIEW] so the surface is searchable.
Save at <path>. Don't activate yet — show me the draft and
I'll review.In a fresh session, paste a real trigger phrase you'd use for
this agent. After the agent responds:
1. Did the right agent fire? (Check by file path or named handoff)
2. Did it load venture/project context correctly?
3. Did it respect Authority / CANNOT boundaries?
4. Did it surface anything that should escalate?
If any check fails, identify which section of the agent file
needs revision.List all custom agent files in <path>. For each:
1. When was it last modified?
2. How often does it actually fire (vs default Claude handling
the request)?
3. Are its triggers still aligned with how I phrase asks now?
4. Does its Authority list still match what it should be doing?
5. Has the escalation cadence prevented any "wait, I didn't mean
that" moments — or is the escalation list too narrow?
Recommend: keep, update, or merge with another agent.Apply this — build your first specialist
45-minute exercise. Pick one specialist domain. Draft, save, test, document.
Build your first custom agent
Each step takes 5-10 minutes. Progress saves automatically.
- 01Pick a domain you handle repeatedly that's NOT general code work — legal, finance, design, ops, etc.If you only do general code work, skip this lesson and revisit when you have specialist work.
- 02Watch how you actually phrase asks in that domain. Note 5-12 trigger words.These are the lowercase phrases you really use. Not formal language.
- 03Run the build prompt. Save the file at the right path (project-level or vault-level).Five sections, ~40-60 lines. Don't pad. Every section earns its space.
- 04Test in a fresh session. Verify the agent fires, loads context, respects Authority/CANNOT.If any of the three checks fails, revise the file before declaring it live.
- 05Add a one-line entry to CLAUDE.md noting the agent exists and what triggers it.Future operators (or future you) need to know it's there.