Skip to content

feat(skill-maker): add XML structure guidance and update examples#28

Merged
schultzp2020 merged 5 commits into
mainfrom
fix/skill-maker-xml-consistency
May 19, 2026
Merged

feat(skill-maker): add XML structure guidance and update examples#28
schultzp2020 merged 5 commits into
mainfrom
fix/skill-maker-xml-consistency

Conversation

@schultzp2020

Copy link
Copy Markdown
Collaborator

Summary

Agents parse XML tags more reliably than markdown headings for skills with multiple semantic sections. This updates skill-maker to recommend and demonstrate XML structure throughout.

Changes

New files:

  • references/xml-structure-guide.md — suggested tag patterns, when to use XML vs markdown, anti-patterns
  • templates/router-skill-xml.md — XML-based starter template for router skills

SKILL.md updates:

  • Uses <intake>, <routing>, <reference_index> tags (practices what it preaches)
  • Adds XML structure guidance section with when-to-use decision criteria
  • Updates audit and review checklists to consider XML for multi-section skills

Reference file updates:

  • architecture-patterns.md — router structure section lists XML tags, router table example uses <intake>/<routing>
  • anti-patterns.md — missing intake question fix shows <intake> example
  • spec-guide.md — body section shows XML structure example

Audit fixes:

  • xml-structure-guide.md examples use generic placeholder paths instead of paths from sibling skills
  • SKILL.md routing table uses specific section names instead of vague "follow below"

Design decisions

  • XML is presented as suggested patterns, not a rigid vocabulary — skills should invent tags that fit their domain
  • Skill-maker phases (1–5) stay as markdown headings — sequential instructional content where order matters more than section lookup
  • XML recommended for skills with semantically distinct sections (intake, routing, principles) that agents need to jump between

Agents parse XML tags more reliably than markdown headings for skills with
multiple semantic sections. Based on prompting best practices and the
pattern already used by 6 of 7 skills in this repo.

- Add references/xml-structure-guide.md with tag vocabulary and patterns
- Add templates/router-skill-xml.md as XML-based starter template
- Update SKILL.md to recommend XML for router/domain skills
- Update audit and review checklists with XML consistency checks
- Replace markdown-only router example with XML intake/routing example
…ocabulary

- Rename 'Established tag vocabulary' to 'Suggested tag patterns'
- Reframe tags as patterns that have worked well, not a closed set
- Encourage inventing new tags when existing ones don't fit
- Soften audit/review checklists from requirements to considerations
- Clarify when XML helps vs when markdown is enough
- skill-maker itself stays markdown — sequential instructional content
Practice what we preach — skill-maker has three distinct entry points
(audit, create, consolidate) and 8 reference files scattered as inline
pointers. Add XML structure where it helps:

- <intake> for the top-level mode selection
- <routing> mapping responses to workflows
- <reference_index> consolidating all reference file pointers

Phases 1-5 stay as markdown headings — sequential instructional content
where order matters more than section lookup.
- architecture-patterns.md: router structure lists XML tags, router table
  and routing rules examples use <intake>/<routing> instead of markdown
- anti-patterns.md: missing intake question fix shows <intake> example
- spec-guide.md: body section shows XML structure example with
  <essential_principles>, <intake>, <routing>
- xml-structure-guide.md: replace skill-specific paths (to-issue.md,
  refine.md, auth.md) with generic placeholders (command-a.md, setup.md)
  so agents don't confuse examples with real local files
- SKILL.md: replace vague 'Follow ... below' routing targets with
  specific section names and file paths
@schultzp2020 schultzp2020 merged commit d4898dc into main May 19, 2026
4 checks passed
@schultzp2020 schultzp2020 deleted the fix/skill-maker-xml-consistency branch May 19, 2026 19:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant