Content
81%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.
Highly actionable with an excellent validated workflow and clean reference structure. The main weakness is verbosity from command repetition across sections and some generic best-practice padding.
Suggestions
De-duplicate the detect/replace/test commands: show them once in the Workflow and reference back from Common Scenarios and Advanced Usage rather than repeating full blocks.
Trim generic Best Practices items (e.g., "Have team members review changes", "Run full test suite") that Claude already assumes, keeping only skill-specific guidance.
Consider moving the three Common Scenarios and Troubleshooting sections into a reference file to keep SKILL.md a lean overview, lifting progressive disclosure toward 5.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly actionable but noticeably verbose: the same detect/replace/test commands are repeated across Quick Start, Workflow, Common Scenarios, and Advanced Usage, and some Best Practices entries ("Have team members review changes") are generic padding. | 3 / 5 |
Actionability | Fully executable copy-paste commands, concrete output examples, CI/CD YAML, and custom-pattern code snippets covering the common detection and replacement cases. | 5 / 5 |
Workflow Clarity | A clear 6-step sequence (scan → review → dry-run → apply → validate → commit) with explicit validation checkpoints ("Critical: Always validate", dry-run, tests/linters) and .bak-based feedback loops for a destructive batch operation. | 5 / 5 |
Progressive Disclosure | Good structure with one-level-deep, clearly signaled real references (python/javascript/java_deprecations.md and the two scripts), but the SKILL.md itself inlines lengthy scenarios, troubleshooting, and advanced sections that could be externalized. | 4 / 5 |
Total | 17 / 20 Passed |