Content
96%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.
The body is a dense, expert-level reference: every command is executable, both the edit and create paths have explicit validation and visual verification loops, and it consistently teaches only what Claude would not reliably know (footguns, schema ordering, rendering quirks). The only structural weakness is that the deep tracked-changes and comments XML detail lives inline in SKILL.md rather than in a one-level-deep reference file.
Suggestions
Move the tracked-changes XML mechanics (w:delText, deleted paragraph marks, rPr child ordering, the accept_changes.py/pandoc empty-bullet edge cases) into a references/tracked-changes.md file and keep a 2–3 line pointer plus the validate --author reminder in SKILL.md.
Compress the comments section to the comment.py invocations plus one sentence on what the script writes; the six-file architecture detail is already handled by the script and adds little value inline.
Consider a brief 'Common create pitfalls' checklist cross-link so the docx-js gotchas can be skimmed without loading the full list during simple edits.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Lean and dense throughout: it explicitly delegates known knowledge ("The model knows the API; these are the footguns") and spends tokens only on non-obvious specifics ("1440 = 1″", "ShadingType.CLEAR, never SOLID", "the text element is <w:delText>, not <w:t>"). Not 4: there is no padded explanation of concepts Claude already knows; even the one-line "A .docx is a ZIP archive of XML files" is load-bearing for the edit-via-unzip workflow. | 5 / 5 |
Actionability | Copy-paste-ready commands cover every common case: full bash blocks for editing (unzip → merge_runs.py → zip → validate.py), verification (soffice.py --convert-to pdf, pdftoppm -jpeg), and comments (comment.py in both directory and .docx modes), plus exact API values for each docx-js gotcha (e.g. "width: 12240, height: 15840", "PositionalTabAlignment.RIGHT"). Not 3/4: the guidance is executable as written, not pseudocode or high-level hints; the docx-js section's reliance on known API plus concrete footgun values leaves no material gap. | 5 / 5 |
Workflow Clarity | The task-approach table routes by operation type; the edit pipeline is a numbered sequence of concrete commands with an explicit validation step (`validate.py out.docx --original doc.docx`), error recovery (`--auto-repair fixes common issues`), a redlining audit (`--author` reports untracked edits), and a separate visual verification loop for created files (render to PDF → images → Read). Not 4: validation checkpoints and feedback loops are explicit for both the destructive XML-manipulation path and the creation path, satisfying the rubric's XML-editing feedback-loop requirement. | 5 / 5 |
Progressive Disclosure | Good structure: the task table is a genuine overview, sections are clearly headed, and every referenced script (scripts/merge_runs.py, scripts/office/soffice.py, scripts/office/validate.py, scripts/accept_changes.py, scripts/comment.py) exists in the bundle as a one-level-deep reference, with script complexity (six-file comments plumbing) properly pushed into comment.py. Not 5: the body is ~88 lines with the tracked-changes XML minutiae (w:delText, deleted paragraph marks, rPr child ordering) and the accept-changes edge-case discussion inlined in SKILL.md, where a skill of this breadth would benefit from splitting that deep detail into a references/ file with a short pointer. | 4 / 5 |
Total | 19 / 20 Passed |