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 'when' trigger is far too broad—firing on any TypeScript/JavaScript file read or write would cause conflicts with nearly every other coding skill. The capability descriptions lean toward abstract design patterns rather than concrete actions a user would request.
Suggestions
Narrow the trigger condition significantly—instead of 'Must use when reading or writing TypeScript/JavaScript files', specify 'Use when the user asks about TypeScript type design, type safety patterns, discriminated unions, or runtime validation with zod/io-ts'.
Add more natural trigger terms users would actually say, such as 'type safety', 'type guards', 'discriminated unions', 'zod', 'branded types', '.ts files'.
Replace abstract pattern names with concrete actions, e.g., 'Creates discriminated union types, adds exhaustive switch statements, implements runtime validation with zod schemas, and designs type-safe API boundaries'.
| 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 the pattern-specific terms like 'making illegal states unrepresentable' and 'exhaustive handling' are not phrases users would naturally say. Missing common terms like 'types', 'interfaces', 'generics', '.ts files', '.tsx'. | 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 any other skill that touches TS/JS files (e.g., testing, linting, React components, Node.js APIs). | 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, actionable code examples covering discriminated unions, branded types, Zod validation, and configuration patterns. Its main weaknesses are some unnecessary general programming advice that Claude already knows (the 'Functional Patterns' and 'Instructions' sections), and the monolithic structure that could benefit from splitting advanced topics into referenced files. The workflow guidance is present but could include more explicit validation checkpoints.
Suggestions
Remove or significantly trim the 'Functional Patterns' and 'Instructions' sections — these contain general programming advice (prefer const, use await, write tests) that Claude already knows, wasting token budget.
Split Zod validation, configuration, and type-fest into separate referenced files to improve progressive disclosure and reduce the main skill's token footprint.
Add an explicit validation checkpoint to the Type-First Development workflow, e.g., 'Run `tsc --noEmit` after step 3 to verify type satisfaction before proceeding.'
| 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 'Instructions' section is largely a list of general programming advice that doesn't add novel value. The type-fest section is appropriately brief. | 2 / 3 |
Actionability | Provides fully executable, copy-paste ready TypeScript code examples throughout — discriminated unions, branded types, Zod schemas, exhaustive switches, config validation. Every pattern is demonstrated with concrete, runnable code rather than pseudocode or vague descriptions. | 3 / 3 |
Workflow Clarity | The 'Type-First Development' section provides a clear 4-step workflow, but the rest of the skill is pattern-oriented rather than workflow-oriented. There are no explicit validation checkpoints or feedback loops for the development process (e.g., no 'run tsc --noEmit to verify' step, no error recovery guidance when types don't compile). | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers and logical grouping, 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. | 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
aa009ea
- 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.