Content
67%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 well-organized, highly actionable codebase-specific guide with concrete commands, paths, and a decision table, though slightly redundant in places and lacking an explicit fix-and-retry loop. Its main defect is that both deferred-detail references point to files absent from the bundle, leaving the core migration examples unavailable.
Suggestions
Ship the referenced files (references/migration-patterns.md and references/type-compatibility.md) or inline their essential content — as delivered, the bundle's only file is SKILL.md and both clearly-signaled references are broken.
Add an explicit feedback loop to the verification step, e.g. "If typescript:check fails, fix the reported call sites and re-run before proceeding".
Trim the "When to use" section, which restates the frontmatter description's triggers almost verbatim and duplicates the decision guide.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with codebase-specific knowledge (naming conventions, import path rules, the Orval pipeline) and assumes Claude's competence, e.g. "Generated functions wrap the same `api` module via `api-orval-mutator.ts" with no basic explanations. Not 5: the "When to use" section largely repeats the frontmatter triggers, and lines like "All three patterns should be replaced with generated functions where available" restate the decision table. | 4 / 5 |
Actionability | Concrete throughout: exact search paths ("Core endpoints: `frontend/src/generated/core/api.ts`"), the naming convention ("surveysList — GET /api/projects/{id}/surveys/"), full import statements, runnable commands ("`pnpm --filter=@posthog/frontend typescript:check`", "`hogli test <test_file>`"), and a decision table with specific actions. Not 5: step 4 ("Replace the call") and step 3 defer to references/migration-patterns.md and references/type-compatibility.md, which do not exist in the bundle, so the key before/after examples are not actually available. | 4 / 5 |
Workflow Clarity | A clear 6-step sequence (identify → find equivalent → check compatibility → replace → update types → clean up) culminating in a "Verifying the migration" section with concrete checks (TypeScript check, grep for leftover types, run tests). Not 5: there is no explicit fix-and-retry feedback loop (no "if the check fails, fix and re-run" guidance), and verification guidance is concentrated at the end rather than as in-workflow checkpoints. | 4 / 5 |
Progressive Disclosure | Section structure and reference signaling are good ("See [type-compatibility.md](references/type-compatibility.md) for details"), but the bundle contains no references/ directory — both referenced files are missing, so the clearly-signaled navigation leads nowhere and the deferred core content (before/after migration examples, type-compatibility details) is entirely unavailable. Scored against the actual bundle structure, this is worse than either inlining the content or shipping the files. Not 3: the problem is not organization or unclear signaling but broken/missing reference targets. | 2 / 5 |
Total | 14 / 20 Passed |