Non-negotiable rules:
- Read
references/claude-agent-runtime.md before planning or rewriting.
- Default to
--mode plan unless the user explicitly asks for rewrite now.
- Keep the body lean because the full markdown body becomes the agent system prompt.
- Use frontmatter for runtime controls before adding more prose.
- Never preload large skills into agent frontmatter unless they have already been slimmed and justified.
- Never add skill-only frontmatter to an agent.
allowed-tools, argument-hint, arguments, when_to_use, disable-model-invocation, user-invocable, context, agent, shell, and paths belong to skills, not agents.
Normalize Agent For Claude
Inputs
$target: Agent directory or direct path to AGENT.md
$mode: Optional. plan or rewrite. Default: plan
Goal
Produce a Claude Code optimized agent that carries role identity and constraints cleanly, uses frontmatter intentionally, and avoids wasting prompt budget on procedural bulk that belongs in skills or shared rules.
Step 1: Resolve the target
- Accept either an agent directory or a direct
AGENT.md path.
- Normalize to the agent root and confirm
AGENT.md exists.
- Determine mode:
--mode rewrite means plan first, then rewrite in the same run
- missing mode means
plan
- Inventory the current agent:
- line count of
AGENT.md
- existing frontmatter fields
- section map of the body
- obvious duplicated global policy or giant knowledge catalogs
Success criteria: You know the exact target agent, target mode, and the current prompt-shape risks.
Step 2: Load the Claude Code agent runtime anchors
Read references/claude-agent-runtime.md fully before making any recommendation.
Extract these constraints from the reference:
- agent
description becomes whenToUse
- the whole markdown body becomes the system prompt
- Claude supports richer agent frontmatter than most custom agents use
- agent
skills: preloads full skill content
- tool allow and deny lists are enforced at runtime
- repo-wide project rules already have a separate instruction hierarchy
- agent rewrites must use agent-native frontmatter only, not skill-native headers
If this repository contains claude-code-source/, use the exact source files named in the reference to verify unusual frontmatter or isolation decisions.
Success criteria: Every planned change is backed by specific Claude runtime behavior.
Step 3: Audit the current agent against Claude's runtime
Evaluate the target agent using this checklist:
- Identity vs procedure
- What content is true role identity? (role definition, expertise bullets, decision heuristics, domain knowledge, traits)
- What content is actually workflow and should live in skills? (step-by-step procedures, shell commands, templates, checklists)
- Role-specific expertise lists and decision heuristics are
IDENTITY — they stay in the body. Only move procedure into skills or references.
- Prompt mass
- Which large sections exist only because the current agent is compensating for missing skills or shared rules?
- Frontmatter opportunities
- Would
disallowedTools, skills, initialPrompt, hooks, permissionMode, maxTurns, background, memory, or isolation improve runtime behavior?
- Are there any skill-only headers that must be removed or explicitly avoided?
- Tool surface
- Is the tool list broader than the role actually needs?
- Skill preload risk
- Would adding a skill to frontmatter create prompt bloat because the skill is still too large?
- Instruction duplication
- Are repo-wide rules duplicated here even though Claude already loads project memory separately?
Classify each issue:
PROMPT: body is too large or carries the wrong content
RUNTIME: missing or misused Claude frontmatter
TOOLS: tool exposure is too broad or too vague
DUPLICATION: project policy is duplicated in agent body
EXTRACTION: content should move into skills or references
Success criteria: You have a concrete, source-backed explanation of what should stay, move, or shrink.
Step 4: Write the per-agent DAG plan
Create both of these artifacts:
.ulpi/plans/agents/<agent-name>-normalize-for-claude.md
.ulpi/plans/agents/<agent-name>-normalize-for-claude.json
The plan must include:
- Current state
- line count
- current frontmatter
- oversized sections
- duplicated global policy
- Claude runtime findings
- each finding mapped to source references from
references/claude-agent-runtime.md
- Target state
- final frontmatter shape
- body sections to keep, delete, or move
- skills or references the agent should depend on instead
- DAG tasks
- frontmatter rewrite
- prompt-body reduction
- procedure extraction into skills or references
- tool-surface tightening
- validation
- Guardrails
- what identity must stay
- what must move out
- what must not be preloaded
- Validation
- concrete checks to confirm the final agent is structurally sound
Each DAG task should include:
id
title
rationale
filesToModify
filesToCreate
dependencies
validation
Success criteria: The markdown and JSON plans describe the same safe sequence of work.
Step 5: Rewrite only if requested
If mode is plan, stop after writing the DAG artifacts.
If mode is rewrite:
- Rewrite the frontmatter first.
- Reduce the body to:
- role and expertise (specific domain knowledge and capability claims)
- scope
- decision heuristics (how to choose between approaches)
- failure boundaries
- output contract
- brief skill handoff guidance
- Move repeated procedures and large examples out of the agent. Keep role expertise bullets and decision heuristics — these are identity, not procedure.
- Add Claude-native frontmatter only when it changes runtime behavior materially.
- Keep the result role-specific, not generic.
Preferred rewrite outcomes:
- agent
description becomes a strong whenToUse
- body becomes much smaller and more identity-focused
disallowedTools and tighter tools are used where appropriate
skills: is used sparingly and only for already-slim skills
- duplicated project rules are removed from the body
- no skill-only headers are introduced into the rewritten agent
Success criteria: The rewritten agent is thinner, more precise, and better aligned to Claude's runtime model.
Step 6: Validate the result
After planning or rewriting:
- Re-read the final
AGENT.md.
- Confirm the frontmatter reflects real runtime decisions.
- Confirm the body is mostly identity, scope, heuristics, and boundaries.
- Confirm no skill-only headers were introduced.
- Confirm large procedure blocks are gone or explicitly moved.
- Confirm the summary names the Claude source anchors that drove the major changes.
Success criteria: The output can be used immediately without re-interpreting why the structure changed.
Output Contract
Always report:
Agent: target path and normalized root
Mode: plan or rewrite
Top runtime issues: the highest-value Claude mismatches
Artifacts: exact plan or rewritten file paths
Guardrails applied: 3 to 5 bullets tied to Claude runtime behavior
If rewrite mode was used, also report:
- which sections were removed or moved
- which frontmatter fields were added, removed, or intentionally omitted
1---
2name: normalize-agent-for-claude
3version: 1.0.0
4description: |
5 Convert a local AGENT.md into a Claude Code optimized agent — an AUDIT-then-rewrite that ties every
6 change to real Claude agent-runtime behavior, not taste. Inventories the agent, checks it against the
7 runtime reference (the whole body becomes the system prompt; role identity stays, procedure moves to
8 skills), writes a per-agent DAG rewrite plan with source-backed guardrails, and — only when asked —
9 rewrites the frontmatter and prompt body thinner and more role-specific. Defaults to PLAN mode, never a
10 blind rewrite, uses agent-native frontmatter only, and grounds each decision in the runtime source rather
11 than inventing conventions. Use to migrate or thin an AGENT.md for Claude's agent runtime.
12allowed-tools:
13 - Bash
14 - Read
15 - Write
16 - Edit
17 - Glob
18 - Grep
19 - Agent
20argument-hint: "<agent-dir-or-AGENT.md> [--mode plan|rewrite]"
21arguments:
22 - target
23 - mode
24when_to_use: |
25 Use when a repository has custom markdown agents to migrate or rewrite for Claude's agent runtime —
26 "convert this agent to Claude", "rewrite this reviewer agent for Claude Code", "thin these AGENT.md
27 files", "create a detailed Claude rewrite plan for this agent". Do NOT use on a SKILL.md or skill folder
28 (use normalize-skill-for-claude), and do NOT jump straight to rewrite without the plan unless the user
29 explicitly asks — audit first, rewrite only on request.
30metadata:
31 source: https://skillmd.com/skills/ulpi-io/normalize-agent-for-claude
32---
33
34<EXTREMELY-IMPORTANT>
35Every rewrite decision must be tied to Claude Code's agent runtime.
36
37Non-negotiable rules:
381. Read `references/claude-agent-runtime.md` before planning or rewriting.
392. Default to `--mode plan` unless the user explicitly asks for rewrite now.
403. Keep the body lean because the full markdown body becomes the agent system prompt.
414. Use frontmatter for runtime controls before adding more prose.
425. Never preload large skills into agent frontmatter unless they have already been slimmed and justified.
436. Never add skill-only frontmatter to an agent. `allowed-tools`, `argument-hint`, `arguments`, `when_to_use`, `disable-model-invocation`, `user-invocable`, `context`, `agent`, `shell`, and `paths` belong to skills, not agents.
44</EXTREMELY-IMPORTANT>
45
46# Normalize Agent For Claude
47
48## Inputs
49
50- `$target`: Agent directory or direct path to `AGENT.md`
51- `$mode`: Optional. `plan` or `rewrite`. Default: `plan`
52
53## Goal
54
55Produce a Claude Code optimized agent that carries role identity and constraints cleanly, uses frontmatter intentionally, and avoids wasting prompt budget on procedural bulk that belongs in skills or shared rules.
56
57## Step 1: Resolve the target
58
591. Accept either an agent directory or a direct `AGENT.md` path.
602. Normalize to the agent root and confirm `AGENT.md` exists.
613. Determine mode:
62 - `--mode rewrite` means plan first, then rewrite in the same run
63 - missing mode means `plan`
644. Inventory the current agent:
65 - line count of `AGENT.md`
66 - existing frontmatter fields
67 - section map of the body
68 - obvious duplicated global policy or giant knowledge catalogs
69
70**Success criteria**: You know the exact target agent, target mode, and the current prompt-shape risks.
71
72## Step 2: Load the Claude Code agent runtime anchors
73
74Read `references/claude-agent-runtime.md` fully before making any recommendation.
75
76Extract these constraints from the reference:
77- agent `description` becomes `whenToUse`
78- the whole markdown body becomes the system prompt
79- Claude supports richer agent frontmatter than most custom agents use
80- agent `skills:` preloads full skill content
81- tool allow and deny lists are enforced at runtime
82- repo-wide project rules already have a separate instruction hierarchy
83- agent rewrites must use agent-native frontmatter only, not skill-native headers
84
85If this repository contains `claude-code-source/`, use the exact source files named in the reference to verify unusual frontmatter or isolation decisions.
86
87**Success criteria**: Every planned change is backed by specific Claude runtime behavior.
88
89## Step 3: Audit the current agent against Claude's runtime
90
91Evaluate the target agent using this checklist:
92
931. **Identity vs procedure**
94 - What content is true role identity? (role definition, expertise bullets, decision heuristics, domain knowledge, traits)
95 - What content is actually workflow and should live in skills? (step-by-step procedures, shell commands, templates, checklists)
96 - Role-specific expertise lists and decision heuristics are `IDENTITY` — they stay in the body. Only move *procedure* into skills or references.
972. **Prompt mass**
98 - Which large sections exist only because the current agent is compensating for missing skills or shared rules?
993. **Frontmatter opportunities**
100 - Would `disallowedTools`, `skills`, `initialPrompt`, `hooks`, `permissionMode`, `maxTurns`, `background`, `memory`, or `isolation` improve runtime behavior?
101 - Are there any skill-only headers that must be removed or explicitly avoided?
1024. **Tool surface**
103 - Is the tool list broader than the role actually needs?
1045. **Skill preload risk**
105 - Would adding a skill to frontmatter create prompt bloat because the skill is still too large?
1066. **Instruction duplication**
107 - Are repo-wide rules duplicated here even though Claude already loads project memory separately?
108
109Classify each issue:
110- `PROMPT`: body is too large or carries the wrong content
111- `RUNTIME`: missing or misused Claude frontmatter
112- `TOOLS`: tool exposure is too broad or too vague
113- `DUPLICATION`: project policy is duplicated in agent body
114- `EXTRACTION`: content should move into skills or references
115
116**Success criteria**: You have a concrete, source-backed explanation of what should stay, move, or shrink.
117
118## Step 4: Write the per-agent DAG plan
119
120Create both of these artifacts:
121
122- `.ulpi/plans/agents/<agent-name>-normalize-for-claude.md`
123- `.ulpi/plans/agents/<agent-name>-normalize-for-claude.json`
124
125The plan must include:
126
1271. **Current state**
128 - line count
129 - current frontmatter
130 - oversized sections
131 - duplicated global policy
1322. **Claude runtime findings**
133 - each finding mapped to source references from `references/claude-agent-runtime.md`
1343. **Target state**
135 - final frontmatter shape
136 - body sections to keep, delete, or move
137 - skills or references the agent should depend on instead
1384. **DAG tasks**
139 - frontmatter rewrite
140 - prompt-body reduction
141 - procedure extraction into skills or references
142 - tool-surface tightening
143 - validation
1445. **Guardrails**
145 - what identity must stay
146 - what must move out
147 - what must not be preloaded
1486. **Validation**
149 - concrete checks to confirm the final agent is structurally sound
150
151Each DAG task should include:
152- `id`
153- `title`
154- `rationale`
155- `filesToModify`
156- `filesToCreate`
157- `dependencies`
158- `validation`
159
160**Success criteria**: The markdown and JSON plans describe the same safe sequence of work.
161
162## Step 5: Rewrite only if requested
163
164If mode is `plan`, stop after writing the DAG artifacts.
165
166If mode is `rewrite`:
167
1681. Rewrite the frontmatter first.
1692. Reduce the body to:
170 - role and expertise (specific domain knowledge and capability claims)
171 - scope
172 - decision heuristics (how to choose between approaches)
173 - failure boundaries
174 - output contract
175 - brief skill handoff guidance
1763. Move repeated procedures and large examples out of the agent. Keep role expertise bullets and decision heuristics — these are identity, not procedure.
1774. Add Claude-native frontmatter only when it changes runtime behavior materially.
1785. Keep the result role-specific, not generic.
179
180Preferred rewrite outcomes:
181- agent `description` becomes a strong `whenToUse`
182- body becomes much smaller and more identity-focused
183- `disallowedTools` and tighter `tools` are used where appropriate
184- `skills:` is used sparingly and only for already-slim skills
185- duplicated project rules are removed from the body
186- no skill-only headers are introduced into the rewritten agent
187
188**Success criteria**: The rewritten agent is thinner, more precise, and better aligned to Claude's runtime model.
189
190## Step 6: Validate the result
191
192After planning or rewriting:
193
1941. Re-read the final `AGENT.md`.
1952. Confirm the frontmatter reflects real runtime decisions.
1963. Confirm the body is mostly identity, scope, heuristics, and boundaries.
1974. Confirm no skill-only headers were introduced.
1985. Confirm large procedure blocks are gone or explicitly moved.
1996. Confirm the summary names the Claude source anchors that drove the major changes.
200
201**Success criteria**: The output can be used immediately without re-interpreting why the structure changed.
202
203## Output Contract
204
205Always report:
206
2071. `Agent:` target path and normalized root
2082. `Mode:` `plan` or `rewrite`
2093. `Top runtime issues:` the highest-value Claude mismatches
2104. `Artifacts:` exact plan or rewritten file paths
2115. `Guardrails applied:` 3 to 5 bullets tied to Claude runtime behavior
212
213If rewrite mode was used, also report:
214- which sections were removed or moved
215- which frontmatter fields were added, removed, or intentionally omitted