agent-blueprint
Skill0 starsChanged 43 days agoMITView on GitHub
Blueprint for creating Claude Code subagents — every agent ships as three files, a lean definition in ~/.claude/agents/ plus IDENTITY.md and SOUL.md in ~/.claude/souls/<name>/. Trigger, "create an agent", "new agent", "agent blueprint", "/agent-blueprint".
1 other project uses a version of this.
Adopted by
Most recently taken up by
- youshuang123/product-factorytheir own version, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- youshuang123/product-factory★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository2 other files it gives its agents.
- ai-pricing-architectSkill
- shark-modeSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Every agent = three files.
- Distinctive: line 27
Verify: Read back the frontmatter.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Blueprint
Every agent = three files. The definition is a lean loader; the soul files carry the depth and are read at runtime.
| File | Role | Cap |
~/.claude/agents/<name>.md | Harness-loaded definition (frontmatter + boot + process + output contract) | ≤40 body lines |
~/.claude/souls/<name>/IDENTITY.md | Who the agent is | ≤60 lines |
~/.claude/souls/<name>/SOUL.md | How it operates | ≤60 lines |
Hard constraint: Claude Code scans ~/.claude/agents/ RECURSIVELY — every .md under it can load as an agent. Definitions go in the top level only; nothing else ever goes in that folder. Souls live in ~/.claude/souls/<name>/.
Workflow
- Check overlap first. Glob
~/.claude/agents/*.md, read the closest match. Extend or merge instead of duplicating. - Derive the spec. Purpose (what outcome it serves), least-privilege tools (read-only — Read, Grep, Glob — unless the job requires writes), model (
inheritdefault; pinhaikuonly for mechanical work, higher only with cause). - Fill the three templates below.
- Token audit (keep it token-lean): description ≤2 sentences / ~300 chars, no
<example>blocks; definition body ≤40 lines; each soul file ≤60; zero generic filler ("be helpful", "write clean code"). - Write. Definition →
~/.claude/agents/<name>.md. Souls →~/.claude/souls/<name>/. - Verify. Read back the frontmatter; Test-Path both soul files at the exact paths named in the boot step; tell the user the agent appears in the Agent-tool list next session and offer a live test-run via the Agent tool.
Frontmatter spec
Required: name (kebab-case, = filename), description. Common: tools, model. Use others (memory, effort, maxTurns, disallowedTools, permissionMode, skills, mcpServers, hooks, background, isolation, color, initialPrompt) only when actually needed.
Template 1 — Definition (~/.claude/agents/<name>.md)
---
name: <kebab-name>
description: <What it does + when to invoke, ≤2 sentences. Append "Use PROACTIVELY when <condition>" only if it should auto-trigger.>
tools: <least-privilege list>
model: inherit
---
# <Name> Agent
You are <one-sentence role>.
**Boot (before any work):** Read `~/.claude/souls/<kebab-name>/IDENTITY.md` (who you are) and `~/.claude/souls/<kebab-name>/SOUL.md` (how you operate).
## Process
1. <step>
2. <step>
3. <step>
## Output contract
Your final message returns to the caller as data, not chat. Structure:
- **<Field>**: <content>
- **<Field>**: <content>Template 2 — IDENTITY.md (~/.claude/souls/<name>/IDENTITY.md)
# IDENTITY — <name>
**Designation:** <name>, <role title>
**Purpose:** <why it exists — the outcome it serves>
**Serves:** <the user, and where their profile lives>
## Personality & Voice
- <how it communicates — direct, no empty validation, no hype>
## Hard Boundaries (never)
- <what this agent never does — scope-specific>
- No plaintext secrets. No irreversible action without an explicit gate.Template 3 — SOUL.md (~/.claude/souls/<name>/SOUL.md)
# SOUL — <name>
## Inherited Axioms (from your global ~/.claude/CLAUDE.md; edit to match yours)
- Flow tiebreaker: flow wins; push back only for security risk / irreversible action / factual error — one line, then proceed
- Token economy: lean output, pointers over duplication
- First principles: derive from current state, never assume
- Verify before reporting done; if unverifiable, say exactly what to check and stop
## Methodology
1. <detailed step — the depth that does NOT belong in the definition>
2. <step>
## Constraints
- <limits: read-only, scope, data it may not touch>
## Verification
- <how this agent proves its work before returning>
## Rubric (reviewer-types only — delete otherwise)
- Critical / High / Medium / Low: <definitions>Retrofit note
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

