normalize-agent-for-claude — Claude Code skill: setup guide
normalize-agent-for-claude audits AGENT.md files and optimizes them for Claude Code runtime by separating role identity from procedures.
no license 117 installs ★ 5 updated 2026-08-31
npx skills add ulpi-io/skills --skill normalize-agent-for-claude -a claude-codeWhat normalize-agent-for-claude does
This skill audits an existing AGENT.md against real Claude Code runtime mechanics. Because Claude treats the markdown body as the system prompt, keeping step-by-step instructions inside the main prompt wastes context budget. The workflow preserves core identity and decision rules in the body while directing procedural commands into external skills.
Execution starts in plan mode by default. The tool inspects frontmatter fields, line count, and tool surface, then writes a DAG migration plan to .ulpi/plans/agents/ in both markdown and JSON formats. Changes are applied directly only when invoked with --mode rewrite.
The routine demands references/claude-agent-runtime.md before generating recommendations. It rejects skill headers like allowed-tools on agent files and will not process SKILL.md targets.
What it helps with
- audit oversized AGENT.md files against Claude runtime rules
- extract procedural steps into skills without losing role identity
- generate a structured DAG migration plan in markdown and JSON
- strip invalid skill-only frontmatter attributes from agent configs
Example prompts for the agent
- Create a migration plan for an agent: normalize-agent-for-claude ./agents/reviewer
- Rewrite prompt and frontmatter directly: normalize-agent-for-claude ./agents/tester/AGENT.md --mode rewrite
How to install normalize-agent-for-claude
1Skills CLI (Vercel)
npx skills add ulpi-io/skills --skill normalize-agent-for-claude -a claude-code2Manually: put the files in place
~/.claude/skills/normalize-agent-for-claude/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/normalize-agent-for-claude/
1Skills CLI (Vercel)
npx skills add ulpi-io/skills --skill normalize-agent-for-claude -a codex2Manually: put the files in place
.agents/skills/normalize-agent-for-claude/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ulpi-io/skills --skill normalize-agent-for-claude -a cursor2Manually: put the files in place
.cursor/skills/normalize-agent-for-claude/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ulpi-io/skills normalize-agent-for-claude2Manually: put the files in place
.github/skills/normalize-agent-for-claude/SKILL.md1Skills CLI (Vercel)
npx skills add ulpi-io/skills --skill normalize-agent-for-claude -a gemini-cli2Platform CLI
gemini skills install https://github.com/ulpi-io/skills --path normalize-agent-for-claudeManually: put the files in place
.devin/skills/normalize-agent-for-claude/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ulpi-io/skills --skill normalize-agent-for-claude -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about normalize-agent-for-claude
How to install normalize-agent-for-claude in Claude Code?
Run npx skills add ulpi-io/skills --skill normalize-agent-for-claude -a claude-code. The file will be placed into ~/.claude/skills/normalize-agent-for-claude/SKILL.md.
What does normalize-agent-for-claude do?
It checks AGENT.md against Claude Code architecture constraints, trims unnecessary context, and isolates procedural steps from role descriptions.
Does it modify files immediately?
No. The default mode is plan, which only produces reports in .ulpi/plans/agents/. It alters agent files only when --mode rewrite is explicitly passed.