typescript-best-practices
Provides TypeScript patterns for type-first development, making illegal states unrepresentable, exhaustive handling, and runtime validation. Must use when reading or writing TypeScript/JavaScript files.
75
62%
Does it follow best practices?
Impact
96%
1.11xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./data/skills-md/0xbigboss/claude-code/typescript-best-practices/SKILL.mdQuality
Discovery
59%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description has a clear 'when' clause which is good for completeness, but the trigger is far too broad ('any TypeScript/JavaScript file'), creating high conflict risk with other skills. The capabilities listed are somewhat abstract patterns rather than concrete actions, and the overly aggressive trigger scope undermines the skill's distinctiveness.
Suggestions
Narrow the trigger scope significantly — instead of 'Must use when reading or writing TypeScript/JavaScript files', specify 'Use when the user asks about type safety, type design, discriminated unions, exhaustive pattern matching, or runtime validation in TypeScript'.
Add more natural trigger terms users would say, such as 'type safety', 'discriminated unions', 'zod', 'type guards', '.ts files', 'type errors', or 'strict typing'.
Replace abstract pattern names with concrete actions, e.g., 'Defines discriminated union types, implements exhaustive switch statements, adds runtime validation with schemas' instead of 'making illegal states unrepresentable'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (TypeScript) and some actions/patterns ('type-first development', 'making illegal states unrepresentable', 'exhaustive handling', 'runtime validation'), but these are more conceptual patterns than concrete actions like 'extract', 'fill', or 'merge'. | 2 / 3 |
Completeness | Clearly answers both what ('Provides TypeScript patterns for type-first development, making illegal states unrepresentable, exhaustive handling, and runtime validation') and when ('Must use when reading or writing TypeScript/JavaScript files') with an explicit trigger clause. | 3 / 3 |
Trigger Term Quality | Includes 'TypeScript' and 'JavaScript' which are natural keywords, but misses common variations like '.ts', '.js', '.tsx', '.jsx', 'type safety', 'types', 'interfaces'. The pattern names like 'making illegal states unrepresentable' are not terms users would naturally say. | 2 / 3 |
Distinctiveness Conflict Risk | The trigger 'Must use when reading or writing TypeScript/JavaScript files' is extremely broad and would fire on virtually any TypeScript or JavaScript task, conflicting with many other skills that might also work with TS/JS files (e.g., testing, linting, formatting, framework-specific skills). | 1 / 3 |
Total | 8 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A solid TypeScript best practices skill with excellent, executable code examples covering discriminated unions, branded types, Zod validation, and exhaustive handling. Its main weaknesses are some redundant guidance on basics Claude already knows (functional patterns, async/await usage), and a monolithic structure that could benefit from splitting advanced topics into referenced files. The workflow section could be strengthened with explicit compiler validation checkpoints.
Suggestions
Remove or significantly trim the 'Functional Patterns' and 'Instructions' sections — items like 'prefer const over let', 'use await for async calls', and 'add focused tests' are basic knowledge Claude already has.
Add explicit validation checkpoints to the type-first workflow, e.g., 'Run `tsc --noEmit` after defining types to verify they compile before implementing logic'.
Consider splitting Zod validation, Configuration, and type-fest into separate referenced files to improve progressive disclosure and reduce the main file's length.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient with good code examples, but includes some unnecessary guidance Claude already knows (e.g., 'prefer const over let', 'use await for async calls', 'add or update focused tests'). The 'Functional Patterns' and 'Instructions' sections contain several items that are basic TypeScript knowledge. The type-fest section is appropriately brief. | 2 / 3 |
Actionability | Excellent executable code examples throughout — discriminated unions, branded types, Zod schemas, exhaustive switches, config validation, and runtime parsing are all copy-paste ready with clear patterns. Every major concept has a concrete, runnable TypeScript example. | 3 / 3 |
Workflow Clarity | The type-first development workflow has a clear 4-step sequence, but lacks explicit validation checkpoints or feedback loops. For a skill that involves writing/modifying TypeScript files, there's no mention of running the compiler to verify, no 'check for errors before proceeding' steps, and no error recovery guidance when types don't compile. | 2 / 3 |
Progressive Disclosure | Content is well-organized with clear section headers, but it's a fairly long monolithic file (~200 lines of content) with no references to supporting files. The Zod section, configuration section, and type-fest section could be split into separate reference files. The cross-reference to react-best-practices is a good pattern though. | 2 / 3 |
Total | 9 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- NeverSight/skills_feed
- Commit
2d09b29
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.