You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: skills/skill-maker/SKILL.md
+68-15Lines changed: 68 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,13 +3,29 @@ name: skill-maker
3
3
description: Create, audit, or consolidate agent skills following the Agent Skills open standard (agentskills.io). Interviews the user relentlessly about intent, scope, and edge cases before drafting. Covers SKILL.md structure, frontmatter, progressive disclosure, description optimization, script bundling, sub-command architecture, setup gates, context systems, and review. Use when the user wants to create a skill, write a skill, build a new skill, make a skill, draft a SKILL.md, or mentions "skill-maker". Also use when asked to review a skill, audit a SKILL.md, check why a skill never triggers, improve an existing skill, or fix a skill. Also use when asked to package expertise, workflows, or domain knowledge into a reusable skill. Also use when asked to consolidate skills, merge skills, combine skills, reduce skill count, or refactor multiple skills into one.
4
4
---
5
5
6
+
<intake>
7
+
6
8
# Create, Audit, or Consolidate Skills
7
9
8
10
Create agent skills following the [Agent Skills open standard](https://agentskills.io/specification).
9
11
10
-
**If auditing an existing skill**, follow the Audit Workflow below instead of the creation phases.
12
+
What do you need to do?
13
+
14
+
1.**Audit an existing skill** — Review, improve, or debug a SKILL.md
15
+
2.**Create a new skill** — Interview, draft, and review from scratch
16
+
3.**Consolidate skills** — Merge multiple skills into fewer
17
+
18
+
</intake>
19
+
20
+
<routing>
21
+
22
+
| Response | Workflow |
23
+
|----------|----------|
24
+
| 1, "audit", "review", "check", "fix", "improve" | Audit Workflow (Step 1–4 in this file) |
| 3, "consolidate", "merge", "combine" |`references/consolidation-guide.md` — return to Phase 5 for final checklist |
11
27
12
-
**If consolidating existing skills** (merging multiple skills into fewer), read `references/consolidation-guide.md` and follow its workflow instead of the phases below. Return to Phase 5 (Review) for the final checklist.
28
+
</routing>
13
29
14
30
## Audit Workflow
15
31
@@ -51,6 +67,7 @@ Check each category. Note issues as you go.
51
67
-[ ] Router table maps commands to reference files
52
68
-[ ] All referenced workflow/reference files exist
53
69
-[ ] Essential principles are in SKILL.md, not only in sub-command references
70
+
-[ ] If skill has multiple semantic sections, consider XML tags for structure (see `references/xml-structure-guide.md`)
54
71
55
72
**Scripts** (if present):
56
73
@@ -140,7 +157,7 @@ Do not proceed to Phase 2 until the user confirms the scope is complete.
140
157
141
158
Write the skill following the spec. Read `references/spec-guide.md` for the full format reference before drafting.
142
159
143
-
**Starter templates:** Use `templates/simple-skill.md` for single-purpose skillsor `templates/router-skill.md` for multi-command skills. Copy the template as a starting point, then customize.
160
+
**Starter templates:** Use `templates/simple-skill.md` for single-purpose skills, `templates/router-skill.md` for multi-command skills using markdown headings, or `templates/router-skill-xml.md` for multi-command skills using XML structure. Copy the template as a starting point, then customize.
144
161
145
162
### Frontmatter
146
163
@@ -188,25 +205,43 @@ Common trap: a new sub-command reference duplicates tables from an existing refe
188
205
189
206
Read `references/anti-patterns.md` during drafting to avoid known pitfalls.
190
207
208
+
### XML structure (router and domain expertise skills)
209
+
210
+
Agents parse XML tags more reliably than markdown headings when a skill has semantically distinct sections (principles, intake, routing, references). XML tags create unambiguous containers; markdown headings blend together in long prompts.
211
+
212
+
Read `references/xml-structure-guide.md` for suggested patterns and anti-patterns.
213
+
214
+
**When XML helps:**
215
+
216
+
- Skills with an intake question + routing table + essential principles
217
+
- Skills where an agent needs to quickly locate a specific section
218
+
- Skills with inline workflows that need clear start/end boundaries
219
+
220
+
**When markdown is enough:**
221
+
222
+
- Simple skills with a single linear workflow
223
+
- Sequential instructional content (phases, steps) where order matters more than section lookup
224
+
191
225
### Sub-command router (when applicable)
192
226
193
227
For skills with multiple distinct operations, use a router table in SKILL.md.
194
228
195
-
**Format choice:** Markdown headings work for most skills. For complex multi-agent orchestration or skills needing machine-parseable sections, XML tags (`<intake>`, `<routing>`, `<essential_principles>`) are also valid. You can mix them — XML tags for structural sections, markdown within content. Use whichever makes the skill easier to follow.
229
+
```xml
230
+
<intake>
231
+
## What would you like to do?
196
232
197
-
```markdown
198
-
## Commands
199
-
200
-
| Command | Description | Reference |
201
-
|---|---|---|
202
-
|`craft [feature]`| Build a feature end-to-end |[references/craft.md](references/craft.md)|
Copy file name to clipboardExpand all lines: skills/skill-maker/references/anti-patterns.md
+13-1Lines changed: 13 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -165,7 +165,19 @@ Migration is complete when: all tests pass, no deprecated imports remain
165
165
166
166
**Symptom:** Router skill launches into the first workflow without asking what the user wants.
167
167
168
-
**Fix:** Always ask first. Show a numbered menu of available commands. Support both menu selection and intent-based routing for users who skip the menu.
168
+
**Fix:** Wrap the menu in `<intake>` and the routing table in `<routing>`. Ask first, then route:
169
+
170
+
```xml
171
+
<intake>
172
+
What would you like to do?
173
+
1. **Command A** — description
174
+
2. **Command B** — description
175
+
176
+
**Wait for response before proceeding.**
177
+
</intake>
178
+
```
179
+
180
+
Support both menu selection and intent-based routing for users who skip the menu.
Copy file name to clipboardExpand all lines: skills/skill-maker/references/architecture-patterns.md
+28-25Lines changed: 28 additions & 25 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,12 +29,14 @@ Do not delay the migration until the skill is "complete" — add the router as s
29
29
30
30
### Structure
31
31
32
-
The SKILL.md contains:
32
+
The SKILL.md contains these sections, using XML tags to create unambiguous boundaries:
33
33
34
-
1.**Setup section** — shared gates that run before any command
35
-
2.**Shared rules** — domain laws that apply to every command
36
-
3.**Router table** — maps command names to reference files
37
-
4.**Routing rules** — how to interpret user input
34
+
1.`<essential_principles>` — domain laws that apply to every command
35
+
2.`<intake>` — ask the user what they want to do
36
+
3.`<routing>` — maps responses to reference/workflow files
37
+
4.`<reference_index>` — lists reference files with "load when..." guidance
38
+
39
+
Setup gates, success criteria, and CLI setup can use additional tags as needed (e.g., `<cli_setup>`, `<success_criteria>`). Invent descriptive tag names that fit the skill's domain.
38
40
39
41
Each command gets its own `references/<command>.md` file. The SKILL.md never contains command-specific instructions — it delegates.
40
42
@@ -64,26 +66,27 @@ This tells the agent which references to load together and prevents redundant AP
64
66
65
67
### Router table pattern
66
68
67
-
```markdown
68
-
## Commands
69
-
70
-
| Command | Category | Description | Reference |
71
-
|---|---|---|---|
72
-
|`init [project]`| Setup | Initialize a new project |[references/init.md](references/init.md)|
73
-
|`check [target]`| Evaluate | Run quality checks |[references/check.md](references/check.md)|
74
-
|`fix [target]`| Repair | Auto-fix common issues |[references/fix.md](references/fix.md)|
75
-
```
76
-
77
-
Group commands by category (Setup, Evaluate, Repair, Generate, etc.) for the user-facing menu.
78
-
79
-
### Routing rules
80
-
81
-
```markdown
82
-
### Routing rules
83
-
84
-
1.**No argument**: Render the table as a user-facing command menu, grouped by category. Ask what to do.
85
-
2.**First word matches a command**: Load its reference file and follow its instructions. Everything after the command name is the target.
86
-
3.**First word doesn't match**: General invocation. Apply setup, shared rules, and the full argument as context.
69
+
```xml
70
+
<intake>
71
+
## What would you like to do?
72
+
73
+
| # | Category | Command | Description |
74
+
|---|----------|---------|-------------|
75
+
| 1 | Setup | `init [project]` | Initialize a new project |
Copy file name to clipboardExpand all lines: skills/skill-maker/references/spec-guide.md
+22-1Lines changed: 22 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -33,10 +33,31 @@ description: What the skill does. Use when [triggers].
33
33
| metadata | No | Arbitrary key-value mapping. |
34
34
| allowed-tools | No | Space-separated string of pre-approved tools. (Experimental) |
35
35
36
-
### Body (markdown instructions)
36
+
### Body
37
37
38
38
Everything after the frontmatter closing `---` is the skill's instructions. This is loaded into the agent's context when the skill activates.
39
39
40
+
Use XML tags to create unambiguous section boundaries when a skill has multiple distinct sections (principles, intake, routing, references). Markdown content works inside the tags:
41
+
42
+
```xml
43
+
<essential_principles>
44
+
- Principle with reasoning
45
+
</essential_principles>
46
+
47
+
<intake>
48
+
## What would you like to do?
49
+
1. **Option A** — description
50
+
</intake>
51
+
52
+
<routing>
53
+
| Response | Workflow |
54
+
|----------|----------|
55
+
| 1, "keyword" | `references/option-a.md` |
56
+
</routing>
57
+
```
58
+
59
+
Simple skills with a single linear workflow can use markdown headings alone.
XML tags help agents parse complex prompts unambiguously — especially when a skill mixes instructions, context, examples, and variable inputs. Wrapping each type of content in its own tag reduces misinterpretation.
4
+
5
+
## When to use XML vs markdown
6
+
7
+
| Pattern | Structure | Rationale |
8
+
|---|---|---|
9
+
|**Simple skill** (single workflow) | Markdown headings | Not enough structure to benefit from XML overhead |
10
+
|**Router skill** (multiple commands) | XML tags for sections, markdown within | Sections are semantically distinct — XML makes boundaries unambiguous |
11
+
|**Domain expertise skill** (full lifecycle) | XML tags for sections, markdown within | Many interleaved concerns need clear separation |
12
+
13
+
**Rule of thumb:** If a skill has an intake question, a routing table, and essential principles, use XML tags. They give agents clear section boundaries that markdown headings can't reliably provide — headings blend together in long prompts, while XML tags create unambiguous containers.
14
+
15
+
## Suggested tag patterns
16
+
17
+
These are patterns that have worked well in practice. Invent new tags as needed — the goal is descriptive, consistent names (lowercase, underscored) that make section boundaries unambiguous.
18
+
19
+
### Common structural tags
20
+
21
+
| Tag | Purpose | Example use |
22
+
|---|---|---|
23
+
|`<essential_principles>`| Rules that apply across all commands | Cross-cutting constraints |
24
+
|`<intake>`| User-facing menu or intake question | "What do you want to do?" |
25
+
|`<routing>`| Table mapping responses to workflows/references | After `<intake>`|
26
+
|`<reference_index>`| Reference files with "load when..." guidance | Skills with multiple references |
Use `<principle name="...">` when principles need to be referenced by name from other sections or workflow files:
48
+
49
+
```xml
50
+
<essential_principles>
51
+
52
+
<principlename="token_safety">
53
+
Never read `.jira-token` into context. Always use shell substitution: `"$(cat "$TOKEN_FILE")"`.
54
+
Tokens in context risk leaking into outputs and persist across compacted sessions.
55
+
</principle>
56
+
57
+
<principlename="data_sources">
58
+
Plugin package definitions come from rhdh-plugin-export-overlays on GitHub.
59
+
Always fetch the OCI reference from `spec.dynamicArtifact` — do NOT construct OCI URLs manually.
60
+
Manually constructed URLs miss the PR number and commit SHA that CI embeds.
61
+
</principle>
62
+
63
+
</essential_principles>
64
+
```
65
+
66
+
When principles are short and don't need cross-referencing, plain `<essential_principles>` with bullet points or markdown content inside works fine.
67
+
68
+
### Intake → routing flow
69
+
70
+
The `<intake>` and `<routing>` tags form a natural pair. Keep them adjacent:
71
+
72
+
```xml
73
+
<intake>
74
+
## What would you like to do?
75
+
76
+
1. **Command A** — Short description of first option
77
+
2. **Command B** — Short description of second option
78
+
3. **Command C** — Short description of third option
79
+
80
+
**Wait for response before proceeding.**
81
+
</intake>
82
+
83
+
<routing>
84
+
| Response | Workflow |
85
+
|----------|----------|
86
+
| 1, "keyword-a" | `references/command-a.md` |
87
+
| 2, "keyword-b" | `references/command-b.md` |
88
+
| 3, "keyword-c" | `references/command-c.md` |
89
+
</routing>
90
+
```
91
+
92
+
### Reference index with conditional loading
93
+
94
+
The `<reference_index>` tag replaces a flat markdown list with structured guidance about when each reference should be loaded:
95
+
96
+
```xml
97
+
<reference_index>
98
+
99
+
| Reference | Purpose | Path |
100
+
|-----------|---------|------|
101
+
| setup | Environment setup and prerequisites | `references/setup.md` |
102
+
| patterns | Reusable patterns for common tasks | `references/patterns.md` |
103
+
104
+
</reference_index>
105
+
```
106
+
107
+
### Nesting markdown inside XML
108
+
109
+
XML tags are containers — use markdown freely inside them for formatting, tables, code blocks, and lists. This mixes the structural clarity of XML with the readability of markdown:
110
+
111
+
```xml
112
+
<essential_principles>
113
+
114
+
- **Copy-sync first** — all edits go in `rhdh-customizations/`, never in `rhdh-local/` directly.
115
+
After every edit, run `rhdh local apply` to sync.
116
+
- **Use scripts** — run `rhdh local up` / `rhdh local down`, never `podman compose` directly.
117
+
118
+
</essential_principles>
119
+
```
120
+
121
+
## Anti-patterns
122
+
123
+
**Don't wrap everything in XML.** Simple skills with a linear workflow don't benefit — XML just adds noise. Only use XML when the skill has semantically distinct sections that need unambiguous boundaries.
124
+
125
+
**Don't nest XML deeply.** One level of nesting (`<essential_principles>` → `<principle>`) is the maximum. Deeper nesting creates parsing ambiguity and is harder to read.
126
+
127
+
**Prefer existing tag names when they fit.** If your skill has an intake question, `<intake>` is clearer than `<user_prompt>` or `<menu>`. But don't force a tag name that doesn't describe your content — invent a better one.
128
+
129
+
**Don't put XML tags inside code blocks as examples and expect them to be parsed.** If showing XML as an example, use fenced code blocks. Only bare XML tags in the skill body are treated as structural.
0 commit comments