Content
62%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 content is highly actionable with concrete commands, explicit validation gates, and a well-sequenced workflow, but it is dense and verbose: long prose passages explain rationale and edge cases that could be tightened or moved into separate reference files. Splitting the specialized taxonomies out and tightening the explanatory paragraphs would meaningfully improve token efficiency.
Suggestions
Extract the 'Clearing coupling the scan won't show' taxonomy and the 'permanent-interface exception' into separate reference files (e.g. references/coupling-channels.md, references/permanent-interface.md) and link them one level deep, leaving the workflow body lean.
Tighten or cut rationale-heavy paragraphs (e.g. the 'No in-process callers, so no facade' section and repeated 'why' framing) to assume the reader's competence and reduce token cost.
Move the long PR-strategy and presentation-wave sections into referenced sub-documents, keeping SKILL.md as a concise overview that points to them.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is very long (~560 lines) and repeatedly elaborates rationale and edge cases at length (e.g. extended prose on why 'no in-process callers' is the wrong test, and the permanent-interface exception); while accurate, much of the explanatory framing restates reasoning a capable reader could infer and could be tightened. | 2 / 5 |
Actionability | Provides concrete, executable commands (hogli product:isolate:scan, product:isolate:move --dry-run, lint:tach, build:openapi) and specific file/module shapes (facade/contracts.py, facade/tasks.py) with only minor gaps where guidance is advisory rather than copy-paste ready. | 4 / 5 |
Workflow Clarity | The 'Required migration workflow' is a clearly sequenced multi-step chain with explicit validation checkpoints and feedback gates (lint:tach, lint-imports, product:lint blocking contract-check until ignore_imports is drained), plus a four-step verification sub-chain; the density of caveats does not undermine the sequence. | 5 / 5 |
Progressive Disclosure | No bundle files exist; the skill is a monolithic SKILL.md with heavy inline detail (the coupling-clearing taxonomy, permanent-interface exception) that would read better split into referenced files, and core docs are referenced one level deep but the body itself inlines what could be separate reference material. | 3 / 5 |
Total | 14 / 20 Passed |