Refine wp-patterns skill

[karmatosed]

Summary

Refactors the wp-patterns skill to improve predictability — the agent following the same process every run — by applying the writing-great-skills skill framework from https://github.com/mattpocock/skills/tree/main/skills along with own suggestions. SKILL.md shrinks from 309 to 121 lines; detailed reference moves behind context pointers into sibling files.

Changes and rationale

SKILL.md — description and frontmatter

Change	Why
Front-load Pattern: as the leading word in the description	Anchors invocation: the agent links shared language in prompts to this skill more reliably
Collapse description to two branches: create/update patterns, improve design quality	One trigger per branch — subtype synonyms (starter page, template part, etc.) were duplication of a single branch
Move routing clauses (wp-block-development, wp-interactivity-api) into description only	Single source of truth for cross-skill reach; removed duplicate routing from body
Trim compatibility field to version requirements only	Cut identity already covered by guardrails and references — reduces context load

SKILL.md — structure and content

Change	Why
Remove When to use section	Duplicated description triggers — single source of truth in description
Remove generic "production-grade patterns" prose	No-op: restated default agent behaviour without changing process
Collapse 9 guardrails to 6 with pointers instead of inline detail	Progressive disclosure — rules stay in-skill, examples and detail live in reference files
Anchor guardrails on leading words: block markup, preset	Fewer tokens, sharper execution hooks versus spelling out the same constraints repeatedly
Move design decisions, visual moves, verification, and example prompts out of SKILL.md	Sprawl cure — reference belongs on lower rungs of the information hierarchy
Add Done when: completion criteria to every procedure step (0–6)	Defence against premature completion — each step has a checkable done condition
Promote verification to step 6 in the numbered procedure	Verification was previously easy to skip after writing; now it is a gated step
Replace inline checklists with pointers to anti-patterns.md	Single source of truth for design quality and technical validation gates
Remove duplicate file header example from step 3	pattern-registration.md already holds header fields and examples
Deduplicate pattern-categories-and-types.md pointer — reuse step 1 decisions in step 3	Avoid re-reading the same reference unless header metadata was not decided earlier
Remove failure-modes bullet list and no-op escalation prose	Sediment and duplication — debugging guidance already lives in reference files
Remove "Stop and ask for help or consult canonical docs" framing	No-op sentence — escalation bullets carry the actual conditions

references/design-with-tokens.md

Change	Why
Add Design Decisions section (purpose, tone, spatial composition, typography, color)	Progressive disclosure target for material removed from SKILL.md step 1
Remove duplicate intro line restating step 1	Single source of truth — step 1 points here; reference should not repeat the invocation
Remove Typography Pairing section; merge emphasis techniques into Typography Hierarchy	Co-location — one authoritative place per concept; eliminated duplicated type-scale guidance
Remove spacing bullets from Spatial Composition (kept in Spatial Rhythm Techniques)	Duplication within the same file — layout strategy vs spacing tactics now separated cleanly
Use preset leading word consistently	Leading-word consolidation

references/anti-patterns.md

Change	Why
Remove Generic AI Aesthetic Markers section	Duplicated the Design Quality Checklist — checklist is now the single actionable source
Add Design Quality Checklist (moved from SKILL.md)	Single source of truth for step 4 completion gate
Add Technical Validation Checklist (moved from SKILL.md)	Single source of truth for step 5 completion gate
Remove repeated nesting rule prose after examples	Duplication — guardrails and checklist already cover nesting; examples remain
Trim redundant "always prefer presets" sentence	Duplication — covered by guardrails and design-with-tokens.md

New reference files

File	Why
references/visual-composition.md	Branch-specific reference for visually distinctive patterns — only some runs need it
references/verification.md	Verification steps are reference, not primary procedure — disclosed behind step 6 pointer
references/example-prompts.md	Optional branch reference — not needed on every pattern run

Net effect

• 309 → 121 lines in SKILL.md (−61%)
• Same workflow preserved: triage → design → plan → write → design check → technical check → verify
• Every meaning has one authoritative home; pointers use branch-specific wording (_distinctive_, checklists, verification)

Test plan

• Confirm SKILL.md description triggers on "create a block pattern" and "improve pattern design"
• Run a wp-patterns eval scenario and verify the agent follows steps 0–6 with checklist gates
• Confirm reference pointers resolve: design-with-tokens.md, anti-patterns.md, verification.md, visual-composition.md
• Verify no broken relative paths from SKILL.md to references/*.md

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: karmatosed <karmatosed@git.wordpress.org>
Co-authored-by: bgrgicak <berislavgrgicak@git.wordpress.org>
Co-authored-by: mikeyarce <mikeyarce@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[bgrgicak]

Thanks for working on this @karmatosed!

The new skill is missing Verification and Failure section which are required.

[karmatosed]

Thank you for review @bgrgicak. I had moved to separate file as thought that was maybe an option on verification but absolutely can move back. I did also iterate this round to a more slimmed down failure, because we need to maybe not be as verbose. I am happy to be pushed back on though.

Once we have a path for how we want to iterate skills now, I can take this and review all our skills in bank.

[bgrgicak]

I had moved to separate file as thought that was maybe an option on verification but absolutely can move back.

Sorry I missed that it was just moved. I'm ok with it being a reference.

[bgrgicak]

Thanks for the improvements @karmatosed!

[mikeyarce]

Overall looks good! I think if we make a few small changes we can ship this. Thanks @karmatosed !

[karmatosed]

@mikeyarce I updated with your feedback, thank you.