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 structure with both 'what' and 'when' clauses, which is good for completeness. However, the trigger condition is far too broad ('any TypeScript/JavaScript file'), creating high conflict risk with other skills. The capability descriptions lean toward abstract pattern names rather than concrete actions a user would request.
Suggestions
Narrow the 'when' clause to specific scenarios like 'Use when the user asks about TypeScript type safety, discriminated unions, exhaustive pattern matching, or Zod/runtime validation' instead of triggering on all TS/JS files.
Add more natural trigger terms users would say, such as 'type safety', 'type guards', 'discriminated unions', 'Zod', '.ts files', 'type errors', 'narrowing'.
Replace abstract pattern names with concrete actions, e.g., 'Creates discriminated union types, adds exhaustive switch handlers, implements Zod schemas for runtime validation'.
| 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 'create interfaces' or 'add type guards'. | 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 strong natural keywords, but misses common variations like '.ts', '.tsx', '.js', 'types', 'interfaces', 'generics', 'type safety'. 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 conflict with virtually any other skill that touches TypeScript or JavaScript files, such as testing skills, linting skills, or 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.
This is a solid, actionable TypeScript skill with excellent code examples covering discriminated unions, branded types, Zod validation, and error handling patterns. Its main weaknesses are moderate verbosity from explanatory comments that Claude doesn't need (rationale phrases after semicolons in the Instructions section), and the lack of progressive disclosure for what is a fairly lengthy document. The workflow for applying these patterns to existing code could be more explicit.
Suggestions
Remove rationale phrases in the Instructions section (e.g., 'Strong typing catches bugs at compile time') — Claude already knows why these practices matter; just state the directive.
Add a brief quick-reference summary at the top listing the key patterns (discriminated unions, branded types, exhaustive switches, Zod validation) with anchor links to sections below.
Consider extracting the Zod and Configuration sections into separate referenced files (e.g., ZOD.md, CONFIG.md) to keep SKILL.md as a concise overview with pointers.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient but has some unnecessary commentary (e.g., 'Strong typing catches bugs at compile time', 'Hidden failures delay debugging', 'Unhandled rejections crash Node processes' are things Claude already knows). The Instructions section reads like rationale explanations rather than lean directives. The good/bad pattern comparisons are valuable but some inline comments could be trimmed. | 2 / 3 |
Actionability | Excellent executable code examples throughout — discriminated unions, branded types, Zod schemas, exhaustive switches, config validation, and error handling are all copy-paste ready with real TypeScript. Every major concept has a concrete, runnable example. | 3 / 3 |
Workflow Clarity | The type-first development section has a clear 4-step workflow, but the rest of the skill is organized as a collection of patterns and guidelines without explicit sequencing or validation checkpoints. For a skill that 'must use when reading or writing TypeScript/JavaScript files,' there's no clear workflow for how to apply these patterns when modifying existing code (e.g., check types first, then validate, then implement). | 2 / 3 |
Progressive Disclosure | The skill is fairly long (~200+ lines) with all content inline. The cross-reference to react-best-practices is good, and the type-fest section is appropriately marked as optional. However, the Zod section and Configuration section could be split into separate reference files, and there's no quick-start summary or navigation structure for this substantial document. | 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
e437c3c
- 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.