Content
48%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 presents a clear pipeline, accurate CLI flags for init_run.py, and strong emphasis on validation, but it is padded with generic boilerplate sections and contains factual drift from the bundle: two broken validation commands, a referenced module that does not exist, a non-executable Python example, and unlisted built-in template assets. Trimming the boilerplate and reconciling commands with the actual scripts would substantially raise quality.
Suggestions
Remove or consolidate the generic boilerplate sections ('When Not to Use', 'Required Inputs', 'Recommended Workflow', 'Output Contract', 'Validation and Safety Rules', 'Deterministic Output Rules', 'Completion Checklist') into a few concrete, skill-specific rules, and drop the duplicated validation-command section.
Fix the validation shortcut to a command that actually runs (e.g., 'python scripts/init_run.py --list-formats'), remove the non-existent 'format_validator.py' module listing, and delete the fabricated 'Expected output format' block.
Make the Python example executable as written: import via the real entry point (e.g., from init_run import FormatAdjusterApp) or correct the import path and call apply_format(text) with its actual single-argument signature, and document the built-in journal configs in assets/formats/ instead of leaving them unmentioned.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~240-line body contains several padded, low-value sections: 'When Not to Use', 'Required Inputs', 'Recommended Workflow', 'Output Contract', 'Validation and Safety Rules', 'Deterministic Output Rules', and 'Completion Checklist' are generic boilerplate Claude already knows (e.g., 'Do not use this skill when the user asks for fabricated results'), and the same broken validation command is repeated twice ('Validation Shortcut' and 'Quick Validation'). This is noticeably verbose with multiple unnecessary sections, matching anchor 2 rather than 3 because the padding is systematic rather than incidental. | 2 / 5 |
Actionability | The CLI examples are concrete and their flags match init_run.py's actual argparse, but key examples are not executable as written: both validation shortcuts invoke 'python scripts/format_adjuster.py --help' though that script has no argparse/main, the Python example uses 'from scripts.format_adjuster import FormatAdjuster' (no scripts package or __init__.py exists; the modules use flat sibling imports) and calls 'adjuster.apply_format(md, config)' while the real signature is 'apply_format(text)'. Broken primary-adjacent examples plus a referenced-but-missing module ('format_validator.py') go beyond the 'minor gaps' of a 4, but the verified CLI path keeps it above 2. | 3 / 5 |
Workflow Clarity | The 'Processing pipeline' gives a clear 5-step sequence (detect, convert to Markdown, apply rules, validate, convert to target) with an explicit validation step, and 'Failure Handling' plus 'Completion Checklist' supply checkpoints and recovery guidance. It falls short of 5 because the documented checkpoint commands are non-functional (format_adjuster.py has no CLI) and the 'Expected output format' block describes a result file the command never produces, leaving validation more asserted than runnable. | 4 / 5 |
Progressive Disclosure | Sections are well organized and script references are one level deep, but measured against the actual bundle the structure is inconsistent: 'format_validator.py' is cited as a core module yet does not exist, and assets/formats/ with 18 built-in journal config JSONs is never mentioned in SKILL.md. Additionally, the full configuration schema, CLI parameters, and a long Python example are inlined in SKILL.md rather than split into reference files, matching anchor 3. | 3 / 5 |
Total | 12 / 20 Passed |