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.
A dense, high-signal body: executable code for every common flow, docx-specific traps instead of concept explanations, and explicit validation gates including a dedicated verify-before-returning section. The only structural note is that the advanced raw-OOXML material is inlined rather than externalized, keeping progressive disclosure one notch below perfect.
Suggestions
Move the raw-OOXML advanced tier (tracked-changes XML splicing, comments.xml anchoring, and the w:id/paraId uniqueness constraints) into a references/ file such as references/ooxml.md, keeping SKILL.md as a lean two-tier overview with a clearly signaled one-level-deep link.
If keeping everything inline, add a brief table of contents or per-section one-line summaries at the top so the ~100 lines of advanced XML detail can be skipped on first read without scanning.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every token is docx-specific knowledge Claude does not already have: the two-tier split ("Default — python-docx ... Advanced — raw OOXML"), traps like "Never type bullet/number characters", "No \n inside a run", "xml:space=\"preserve\" on any <w:t> with leading/trailing whitespace", and the run-splitting gotcha in find-and-replace. Not a 4: there is no over-explanation to trim — even the one-line format intro ("A .docx is a ZIP of XML parts") is load-bearing for the raw-OOXML tier, and the LibreOffice scaffold is abbreviated precisely because the tool is optional. | 5 / 5 |
Actionability | Every main flow ships complete, runnable code: reading (doc.paragraphs/tables loop), creation (headings, runs, real list styles, table with header row, picture, page break, then reopen-and-assert validation), find-and-replace with the runs[0]-collapse fallback, the raw-OOXML re-zip loop, and a full add_page_number field-XML function. Not a 4: the only non-executable block is the soffice scaffold, and its flexibility is explicitly justified ("optional and often absent" with a shutil.which check and degrade path), which the rubric guidelines exempt. | 5 / 5 |
Workflow Clarity | Sequences are explicit with validation checkpoints and feedback loops where it matters: create code ends with "Validate immediately" (reopen + assert paragraphs + ZIP test), the raw-OOXML tier states its workflow ("read the XML part → edit it as text → re-zip every original member"), a dedicated "Verify before returning" section requires reopening, testzip, and lxml well-formedness checks in the same exec call, and the LibreOffice path degrades with "If it is absent, degrade with a clear note". Not a 4: the feedback loop (validate → fix → re-verify) that anchor 4 leaves implicit is spelled out as a hard gate before returning. | 5 / 5 |
Progressive Disclosure | Structure is good: a clear two-tier overview ("Default — python-docx / Advanced — raw OOXML") with a signaled internal anchor ([Raw OOXML](#raw-ooxml-advanced)), and no bundle files exist so nothing is mis-filed. Not a 5: ~100 lines of advanced material (tracked-change XML splicing rules, comments.xml anchoring, w:id/paraId constraints) are inlined in the single SKILL.md rather than split into one-level-deep reference files, which the anchor-5 pattern reserves for a lean overview plus pointed references; not a 3 because the tiering and headers make the inline content easy to navigate and it is arguably within an acceptable single-file budget. | 4 / 5 |
Total | 19 / 20 Passed |