Content
75%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 strong, expert-level instruction skill: nearly every line is non-obvious, project-aware guidance with concrete commands, flags, and patterns, organized into a clear learn-apply-verify flow. Its weaknesses are modest: a long single-file body with no reference split, inline time-sensitive version history, and a few places (boundary guards, migration assessment) where an example would make execution more copy-paste ready.
Suggestions
Move the TypeScript version-compatibility details (§1's 6.0/7.0 default changes and removals) into a references/ file such as references/version-compat.md, keeping only 'check the lockfile version; see version-compat.md for what differs' in SKILL.md — this both trims the body and quarantines time-sensitive information that will age.
Split the JavaScript-to-TypeScript adoption assessment (§7) into its own reference file, leaving the five outcome options and 'assess before recommending' framing inline; the assessment checklist and staged incremental plan are a self-contained sub-guide that inflates the main file.
Add one short executable snippet for the two most load-bearing patterns — a field-checking guard for boundary validation (§2) and the discriminated-union-with-never-default idiom (§3) — so the guidance is copy-paste ready rather than describable-only.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude's competence — no basics are re-explained, and nearly every rule carries non-obvious specifics (e.g. 'Number("") is 0, Boolean("false") is true', 'never export a const enum from a library', TS2589 bounding). It is not a 5 because the ~95-line body retains time-sensitive version history inline ('From 7.0 it is the native compiler... 7.0 removed baseUrl, moduleResolution: node10/classic...') rather than isolating it, which the judging guidelines say should penalize conciseness, and a few rules could be tightened. It is well above anchor 3, which requires genuinely unnecessary explanation. | 4 / 5 |
Actionability | For an instruction-only skill the guidance is highly concrete: exact commands ('tsc --noEmit', 'tsc -b', 'tsc --extendedDiagnostics'), exact config values ('module: nodenext', '.js' extensions, 'rewriteRelativeImportExtensions'), and exact patterns ('default: { const unreachable: never = value; … }', 'load<T>(): T' as an anti-pattern, 'K extends PropertyKey'). It falls short of anchor 5 only in minor gaps — e.g. 'write a guard that checks every field the code relies on' and the migration assessment give checklists but no example snippet a model could pattern-match directly. | 4 / 5 |
Workflow Clarity | A clear sequence is present — 'Read before writing' (§1) → applied rules (§2–8) → an explicit verification section (§9) with type-check, lint, run, and report checkpoints. The destructive/batch cap does not apply (the skill forbids fix/format modes and unrequested installs). It misses anchor 5 because there is no explicit error-recovery loop after a failed check (e.g. type-check fails → fix → re-run) and §9's checkpoints are a flat list rather than a gated loop like the anchor's 'Only when valid' pattern. | 4 / 5 |
Progressive Disclosure | The single-file body is well organized: an overarching rules section plus nine clearly titled, numbered sections, and no buried or nested references (there are no bundle files at all). It is not a 5 because at ~95 lines it exceeds the simple-skill range where sections alone suffice, and self-contained blocks — the TypeScript version-compatibility history in §1 and the full JS-adoption assessment methodology in §7 — are natural candidates for one-level-deep references/ files that would keep SKILL.md an overview. It is clearly above anchor 3, whose example is undifferentiated inline API reference. | 4 / 5 |
Total | 16 / 20 Passed |