Content
88%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 high-quality, highly executable reference: concrete code for every common docx task, ordered workflows with validation feedback loops, and accurate references to the bundled scripts. The two areas keeping it from top marks are token duplication between inline CRITICAL callouts and the recap rules section, and the absence of any progressive-disclosure split for the long XML/API reference material.
Suggestions
Move the XML Reference (tracked changes, comments, image embedding, schema compliance) into a references/xml.md file and keep a short pointer plus the 2-3 most common patterns in SKILL.md, cutting the always-loaded body roughly in half.
Drop the 'Critical Rules for docx-js' recap section or reduce it to 3-4 rules that are not already flagged CRITICAL at their point of use, since nearly every entry duplicates an inline callout.
Consider folding the accept_changes and doc→docx conversion commands into the Quick Reference table so the conversion/reading paths are visible in one place without scrolling.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and imperative with almost no explanation of concepts Claude already knows (the one-line "A .docx file is a ZIP archive containing XML files" is the sole exception, and it earns its place). The deduction is for the "Critical Rules for docx-js" section, which restates ~13 rules already flagged as CRITICAL inline (page size, dual table widths, unicode bullets, ShadingType.CLEAR, etc.) — a noticeable duplication of tokens. Not the level below (5) because the rest is lean; not above because the recap section is more than a trivial trim. | 4 / 5 |
Actionability | Every section gives copy-paste-ready, executable code or commands: complete docx-js snippets with real DXA values, runnable shell invocations for every bundled script (unpack.py, pack.py, validate.py, soffice.py, comment.py, accept_changes.py), and literal XML blocks for tracked changes, comments, and images. Common cases (bullets, tables, TOC, headers/footers, page breaks) are all covered concretely. | 5 / 5 |
Workflow Clarity | The edit workflow is an explicitly ordered 3-step sequence ("Follow all 3 steps in order") with validation built into pack.py plus auto-repair behavior documented, and the creation workflow includes an explicit feedback loop: "After creating the file, validate it. If validation fails, unpack, fix the XML, and repack." The anchor-5 pattern (validate → fix → retry before proceeding) is present for this XML-manipulation skill. | 5 / 5 |
Progressive Disclosure | Structure is good: a Quick Reference routing table up top, then clearly headed sections (Creating / Editing / XML Reference / Dependencies), and every referenced bundle path (scripts/office/unpack.py, pack.py, validate.py, soffice.py, scripts/accept_changes.py, scripts/comment.py) exists on disk, one level deep. Not a 5 because the ~130-line XML Reference and the docx-js API material are fully inlined in a ~480-line SKILL.md rather than split into a references/ file, leaving the always-loaded body heavier than it needs to be; not a 3 because organization and navigation are clear with no nested references. | 4 / 5 |
Total | 18 / 20 Passed |