Content
78%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A strong, highly actionable body with executable commands, complete code examples, and a clearly sequenced editing workflow with validation. Weaknesses are mild redundancy in the table-width guidance and a fully monolithic structure: ~480 lines with no progressive disclosure into reference files despite large XML/API reference sections that would naturally split out.
Suggestions
Split the 'XML Reference' section (tracked changes, comments, images) and possibly the docx-js recipe sections into references/*.md files (e.g. references/xml-patterns.md) linked with clear one-level-deep pointers from the body, keeping SKILL.md as a lean overview.
Deduplicate the table-width guidance: state the dual-width/DXA rules once in the Tables section and remove the repeated warnings from the width-calculation block, 'Width rules' list, and 'Critical Rules' list.
Add an explicit recovery step to the editing workflow: after Step 3, state that if pack validation fails on items auto-repair cannot fix (malformed XML, missing relationships), fix the XML and re-run pack.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is code-first and mostly lean — no concept explanations Claude already knows — but repeats the same guidance multiple times: dual table widths appears in the Tables section, the width-calculation block, the 'Width rules' list, and the 'Critical Rules' list, and the DXA-vs-PERCENTAGE warning appears three times. Fits 'efficient; minor instances of over-explanation that could be trimmed'; not 5 due to this repetition, not 3 since the padding is duplication of genuinely critical rules rather than verbosity. | 4 / 5 |
Actionability | Everything is executable: copy-paste bash commands (`pandoc --track-changes=all ...`, `python scripts/office/unpack.py ...`), complete docx-js code blocks, a DXA units table, exact XML entity codes, and concrete pitfalls (ShadingType.CLEAR, PageBreak-in-Paragraph). All referenced scripts (accept_changes.py, comment.py, office/unpack.py, office/pack.py, office/validate.py, office/soffice.py) exist in the bundle. Fully matches 'fully executable; copy-paste ready code or commands; specific examples cover the common cases'. | 5 / 5 |
Workflow Clarity | The editing workflow is explicitly sequenced ('Follow all 3 steps in order': unpack → edit XML → pack) and the creation path has an explicit feedback loop ('If validation fails, unpack, fix the XML, and repack'), with pack listing what auto-repair does and does not fix. Falls just short of anchor 5 because the editing path never states the retry step when pack validation fails on the 'won't fix' items (malformed XML, missing relationships) — recovery is implied rather than an explicit validate→fix→re-validate checkpoint. | 4 / 5 |
Progressive Disclosure | The body is well-sectioned (Quick Reference, Creating, Editing, XML Reference) but is a single ~480-line file with no reference documents at all — the XML pattern reference (tracked changes, comments, images) and the docx-js API recipes are exactly the content that belongs in one-level-deep references/*.md files. Matches 'some structure... content that should be separate is inline'; not 4 because there are no clearly signaled reference files to navigate to, not 2 because the inline file itself is well-organized and navigable via its section headers. | 3 / 5 |
Total | 16 / 20 Passed |