Non-negotiable rules:
- Read
references/claude-skill-runtime.md before planning or rewriting.
- Default to
--mode plan unless the user explicitly asks to rewrite now.
- Treat frontmatter as the highest-leverage surface. Claude routes and budgets skills from metadata first.
- Keep
SKILL.md focused on workflow. Move bulky examples, framework variants, and edge-case catalogs into references/ or scripts/.
- Do not add
context: fork, paths:, or user-invocable: false without a concrete runtime reason.
- Never add agent-only frontmatter to a skill.
tools, disallowedTools, skills, initialPrompt, permissionMode, maxTurns, background, memory, isolation, color, and mcpServers belong to agents, not skills.
Normalize Skill For Claude
Inputs
$target: Skill directory or direct path to SKILL.md
$mode: Optional. plan or rewrite. Default: plan
Goal
Produce a Claude Code optimized skill that is easier to auto-invoke, cheaper to keep in prompt budget, and safer to execute. Always start by creating a per-skill DAG plan unless the user explicitly asks for direct rewrite.
Step 1: Resolve the target
- Accept either a skill directory or a direct
SKILL.md path.
- Normalize to the skill root and confirm
SKILL.md exists.
- Determine mode:
--mode rewrite means plan first, then rewrite in the same run
- missing mode means
plan
- Inventory the current skill:
- line count of
SKILL.md
- existing frontmatter fields
- whether
references/, scripts/, or assets/ already exist
- whether the skill appears internal-only or user-invocable
Success criteria: You know the exact skill root, target mode, current file shape, and likely scope of the rewrite.
Step 2: Load the Claude Code skill runtime anchors
Read references/claude-skill-runtime.md fully before making any recommendation.
Extract these constraints from the reference:
- Claude budgets skill discovery from frontmatter and short descriptions first.
- Full skill bodies are loaded on invocation, not for listing.
paths: activates conditional skills when matching files are touched.
context: fork runs the skill in a forked subagent and should be rare.
allowed-tools should be the minimum needed permission surface.
- Skill rewrites must use skill-native frontmatter only, not agent-native headers.
If this repository contains claude-code-source/, use the exact source files named in the reference to verify edge cases before rewriting unusual frontmatter.
Success criteria: Every planned change can be tied to a specific Claude runtime behavior.
Step 3: Audit the current skill against Claude's runtime
Evaluate the target skill using this checklist:
- Description and trigger quality
- Does
description say what the skill does, when to use it, and example trigger phrases?
- Is
when_to_use missing or weak?
- Frontmatter completeness
- Would
allowed-tools, arguments, argument-hint, user-invocable, paths, context, or agent improve runtime behavior?
- Are there any agent-only headers that must be removed or explicitly avoided?
- Body size and shape
- Is the body carrying reference material instead of core workflow?
- Are there giant examples, duplicated checklists, or framework-specific sections that belong in
references/?
- Structural content audit: Does the skill contain routing tables (task→reference mappings), personality/expertise definitions, numbered rule sets, or gate classifications? These are high-signal inline content, NOT bulk examples. Tag each as
PRESERVE-INLINE or EXTRACT-WITH-MANDATORY-LOAD.
- Invocation type
- Is this a public slash command, an internal router, or a conditional path-scoped helper?
- Execution model
- Would
context: fork help, or would it fragment work and require mid-flow user interaction?
- Determinism opportunities
- Are there repeated shell snippets or fragile transformations that belong in
scripts/?
Classify each issue:
ROUTING: metadata is too weak for auto-invocation
PROMPT: body is too large or redundant
SAFETY: tool scope or execution mode is too broad
STRUCTURE: references or scripts should be extracted
Success criteria: You have a concrete, source-backed audit of what must change and why.
Step 4: Write the per-skill DAG plan
Create both of these artifacts:
.ulpi/plans/skills/<skill-name>-normalize-for-claude.md
.ulpi/plans/skills/<skill-name>-normalize-for-claude.json
The plan must include:
- Current state
- line count
- existing frontmatter
- current folders
- largest bloat areas
- Claude runtime findings
- each finding mapped to source references from
references/claude-skill-runtime.md
- Target state
- final frontmatter shape
- files to keep, rewrite, create, or split
- DAG tasks
- frontmatter rewrite
- body trim
- reference extraction
- optional script extraction
- validation
- Guardrails
- what must not be changed
- what must not be over-automated
- Validation
- concrete commands or checks to confirm the skill 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 work and can be executed safely.
Step 5: Rewrite only if requested
If mode is plan, stop after writing the DAG artifacts.
If mode is rewrite:
- Rewrite the frontmatter first.
- Keep the body focused on:
- inputs
- goal
- workflow steps
- guardrails
- output contract
- Move bulky material into
references/, but respect content classification:
- Bulk (move to references): giant examples, framework variants, edge-case catalogs, verbose checklists, before/after code samples
- Structural (keep inline OR extract with mandatory load directive): routing tables (task→reference mappings), numbered guardrail rules in EXTREMELY-IMPORTANT, gate classifications (BLOCK/CONCERN/OBSERVATION), personality/expertise sections
- Routing tables that map task types to reference files MUST stay inline — they are the skill's primary navigation surface.
- Concrete guardrail lists (numbered rules, always/never) MUST either stay in the EXTREMELY-IMPORTANT block or get a mandatory load directive in the step that needs them — not a soft "see references" suggestion.
- When extracting personality/expertise to a reference file, add a mandatory load directive at session start, not just a "When To Load References" entry.
- Create
scripts/ only when deterministic repeated logic is clearly justified.
- Keep the resulting
SKILL.md lean enough that future edits remain easy.
Preferred rewrite outcomes:
description and when_to_use become trigger-oriented
- internal router skills become
user-invocable: false
- domain skills gain
paths: only when file-touch activation clearly helps
context: fork appears only for self-contained analysis/research workflows
- no agent-only headers are introduced into the rewritten skill
Success criteria: The rewritten skill is structurally smaller, clearer to route, and justified by Claude runtime behavior.
Step 6: Validate the result
After planning or rewriting:
- Re-read the final
SKILL.md.
- Confirm the body does not duplicate reference files.
- Confirm frontmatter fields are intentionally chosen, not cargo-culted.
- Confirm no agent-only headers were introduced.
- Confirm every
references/ file is directly linked from SKILL.md.
- Confirm no routing tables, numbered guardrail rules, or gate classifications were stripped without replacement.
- Confirm the plan or rewrite summary names the Claude source anchors that drove the major decisions.
Success criteria: The output is usable immediately by a human or follow-on agent without guessing.
Output Contract
Always report:
Skill: 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 moved to
references/
- which frontmatter fields were added, removed, or intentionally omitted
1---
2name: normalize-skill-for-claude
3version: 1.0.0
4description: |
5 Convert a local skill into a Claude Code optimized shape — an AUDIT-then-rewrite that ties every change
6 to real Claude skill-runtime behavior, treating FRONTMATTER as the highest-leverage routing surface.
7 Inventories the skill, checks it against the runtime reference (Claude routes and budgets skills from
8 metadata first), writes a per-skill DAG rewrite plan with source-backed guardrails, and — only when
9 asked — rewrites frontmatter, body, and references for cheaper routing and safer execution. Defaults to
10 PLAN mode, never a blind rewrite, uses skill-native frontmatter only, and preserves structural content
11 (routing tables, guardrail rules) rather than stripping it as bulk. Use to migrate or restructure a
12 SKILL.md for Claude's skill runtime.
13allowed-tools:
14 - Bash
15 - Read
16 - Write
17 - Edit
18 - Glob
19 - Grep
20 - Agent
21argument-hint: "<skill-dir-or-SKILL.md> [--mode plan|rewrite]"
22arguments:
23 - target
24 - mode
25when_to_use: |
26 Use when a repository has custom skills to migrate or rewrite for Claude's skill runtime — "convert this
27 skill to Claude", "make these skills Claude-native", "add proper when_to_use and paths metadata", "split
28 this huge skill into references". Do NOT use on an AGENT.md or agent definition (use
29 normalize-agent-for-claude), and do NOT jump straight to rewrite without the plan unless the user
30 explicitly asks — audit first, rewrite only on request.
31metadata:
32 source: https://skillmd.com/skills/ulpi-io/normalize-skill-for-claude
33---
34
35<EXTREMELY-IMPORTANT>
36Every recommendation must be justified by Claude Code runtime behavior, not taste.
37
38Non-negotiable rules:
391. Read `references/claude-skill-runtime.md` before planning or rewriting.
402. Default to `--mode plan` unless the user explicitly asks to rewrite now.
413. Treat frontmatter as the highest-leverage surface. Claude routes and budgets skills from metadata first.
424. Keep `SKILL.md` focused on workflow. Move bulky examples, framework variants, and edge-case catalogs into `references/` or `scripts/`.
435. Do not add `context: fork`, `paths:`, or `user-invocable: false` without a concrete runtime reason.
446. Never add agent-only frontmatter to a skill. `tools`, `disallowedTools`, `skills`, `initialPrompt`, `permissionMode`, `maxTurns`, `background`, `memory`, `isolation`, `color`, and `mcpServers` belong to agents, not skills.
45</EXTREMELY-IMPORTANT>
46
47# Normalize Skill For Claude
48
49## Inputs
50
51- `$target`: Skill directory or direct path to `SKILL.md`
52- `$mode`: Optional. `plan` or `rewrite`. Default: `plan`
53
54## Goal
55
56Produce a Claude Code optimized skill that is easier to auto-invoke, cheaper to keep in prompt budget, and safer to execute. Always start by creating a per-skill DAG plan unless the user explicitly asks for direct rewrite.
57
58## Step 1: Resolve the target
59
601. Accept either a skill directory or a direct `SKILL.md` path.
612. Normalize to the skill root and confirm `SKILL.md` exists.
623. Determine mode:
63 - `--mode rewrite` means plan first, then rewrite in the same run
64 - missing mode means `plan`
654. Inventory the current skill:
66 - line count of `SKILL.md`
67 - existing frontmatter fields
68 - whether `references/`, `scripts/`, or `assets/` already exist
69 - whether the skill appears internal-only or user-invocable
70
71**Success criteria**: You know the exact skill root, target mode, current file shape, and likely scope of the rewrite.
72
73## Step 2: Load the Claude Code skill runtime anchors
74
75Read `references/claude-skill-runtime.md` fully before making any recommendation.
76
77Extract these constraints from the reference:
78- Claude budgets skill discovery from frontmatter and short descriptions first.
79- Full skill bodies are loaded on invocation, not for listing.
80- `paths:` activates conditional skills when matching files are touched.
81- `context: fork` runs the skill in a forked subagent and should be rare.
82- `allowed-tools` should be the minimum needed permission surface.
83- Skill rewrites must use skill-native frontmatter only, not agent-native headers.
84
85If this repository contains `claude-code-source/`, use the exact source files named in the reference to verify edge cases before rewriting unusual frontmatter.
86
87**Success criteria**: Every planned change can be tied to a specific Claude runtime behavior.
88
89## Step 3: Audit the current skill against Claude's runtime
90
91Evaluate the target skill using this checklist:
92
931. **Description and trigger quality**
94 - Does `description` say what the skill does, when to use it, and example trigger phrases?
95 - Is `when_to_use` missing or weak?
962. **Frontmatter completeness**
97 - Would `allowed-tools`, `arguments`, `argument-hint`, `user-invocable`, `paths`, `context`, or `agent` improve runtime behavior?
98 - Are there any agent-only headers that must be removed or explicitly avoided?
993. **Body size and shape**
100 - Is the body carrying reference material instead of core workflow?
101 - Are there giant examples, duplicated checklists, or framework-specific sections that belong in `references/`?
102 - **Structural content audit**: Does the skill contain routing tables (task→reference mappings), personality/expertise definitions, numbered rule sets, or gate classifications? These are high-signal inline content, NOT bulk examples. Tag each as `PRESERVE-INLINE` or `EXTRACT-WITH-MANDATORY-LOAD`.
1034. **Invocation type**
104 - Is this a public slash command, an internal router, or a conditional path-scoped helper?
1055. **Execution model**
106 - Would `context: fork` help, or would it fragment work and require mid-flow user interaction?
1076. **Determinism opportunities**
108 - Are there repeated shell snippets or fragile transformations that belong in `scripts/`?
109
110Classify each issue:
111- `ROUTING`: metadata is too weak for auto-invocation
112- `PROMPT`: body is too large or redundant
113- `SAFETY`: tool scope or execution mode is too broad
114- `STRUCTURE`: references or scripts should be extracted
115
116**Success criteria**: You have a concrete, source-backed audit of what must change and why.
117
118## Step 4: Write the per-skill DAG plan
119
120Create both of these artifacts:
121
122- `.ulpi/plans/skills/<skill-name>-normalize-for-claude.md`
123- `.ulpi/plans/skills/<skill-name>-normalize-for-claude.json`
124
125The plan must include:
126
1271. **Current state**
128 - line count
129 - existing frontmatter
130 - current folders
131 - largest bloat areas
1322. **Claude runtime findings**
133 - each finding mapped to source references from `references/claude-skill-runtime.md`
1343. **Target state**
135 - final frontmatter shape
136 - files to keep, rewrite, create, or split
1374. **DAG tasks**
138 - frontmatter rewrite
139 - body trim
140 - reference extraction
141 - optional script extraction
142 - validation
1435. **Guardrails**
144 - what must not be changed
145 - what must not be over-automated
1466. **Validation**
147 - concrete commands or checks to confirm the skill is structurally sound
148
149Each DAG task should include:
150- `id`
151- `title`
152- `rationale`
153- `filesToModify`
154- `filesToCreate`
155- `dependencies`
156- `validation`
157
158**Success criteria**: The markdown and JSON plans describe the same work and can be executed safely.
159
160## Step 5: Rewrite only if requested
161
162If mode is `plan`, stop after writing the DAG artifacts.
163
164If mode is `rewrite`:
165
1661. Rewrite the frontmatter first.
1672. Keep the body focused on:
168 - inputs
169 - goal
170 - workflow steps
171 - guardrails
172 - output contract
1733. Move bulky material into `references/`, but respect content classification:
174 - **Bulk** (move to references): giant examples, framework variants, edge-case catalogs, verbose checklists, before/after code samples
175 - **Structural** (keep inline OR extract with mandatory load directive): routing tables (task→reference mappings), numbered guardrail rules in EXTREMELY-IMPORTANT, gate classifications (BLOCK/CONCERN/OBSERVATION), personality/expertise sections
176 - Routing tables that map task types to reference files MUST stay inline — they are the skill's primary navigation surface.
177 - Concrete guardrail lists (numbered rules, always/never) MUST either stay in the EXTREMELY-IMPORTANT block or get a mandatory load directive in the step that needs them — not a soft "see references" suggestion.
178 - When extracting personality/expertise to a reference file, add a mandatory load directive at session start, not just a "When To Load References" entry.
1794. Create `scripts/` only when deterministic repeated logic is clearly justified.
1805. Keep the resulting `SKILL.md` lean enough that future edits remain easy.
181
182Preferred rewrite outcomes:
183- `description` and `when_to_use` become trigger-oriented
184- internal router skills become `user-invocable: false`
185- domain skills gain `paths:` only when file-touch activation clearly helps
186- `context: fork` appears only for self-contained analysis/research workflows
187- no agent-only headers are introduced into the rewritten skill
188
189**Success criteria**: The rewritten skill is structurally smaller, clearer to route, and justified by Claude runtime behavior.
190
191## Step 6: Validate the result
192
193After planning or rewriting:
194
1951. Re-read the final `SKILL.md`.
1962. Confirm the body does not duplicate reference files.
1973. Confirm frontmatter fields are intentionally chosen, not cargo-culted.
1984. Confirm no agent-only headers were introduced.
1995. Confirm every `references/` file is directly linked from `SKILL.md`.
2006. Confirm no routing tables, numbered guardrail rules, or gate classifications were stripped without replacement.
2017. Confirm the plan or rewrite summary names the Claude source anchors that drove the major decisions.
202
203**Success criteria**: The output is usable immediately by a human or follow-on agent without guessing.
204
205## Output Contract
206
207Always report:
208
2091. `Skill:` target path and normalized root
2102. `Mode:` `plan` or `rewrite`
2113. `Top runtime issues:` the highest-value Claude mismatches
2124. `Artifacts:` exact plan or rewritten file paths
2135. `Guardrails applied:` 3 to 5 bullets tied to Claude runtime behavior
214
215If rewrite mode was used, also report:
216- which sections moved to `references/`
217- which frontmatter fields were added, removed, or intentionally omitted