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 any other coding skill. The capability descriptions lean toward abstract pattern names rather than concrete actions a user would request.
Suggestions
Narrow the trigger condition from 'reading or writing TypeScript/JavaScript files' to something more specific like 'Use when designing type hierarchies, adding type safety, or when the user asks about discriminated unions, exhaustive checks, or runtime validation with Zod/io-ts'.
Add more natural trigger terms users would actually say, such as 'type safety', 'discriminated unions', 'type guards', 'Zod', 'branded types', '.ts files'.
Replace abstract pattern names with concrete actions, e.g., 'Creates discriminated union types, adds exhaustive switch handling, implements runtime validation schemas, and designs type-safe APIs'.
| 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 fire on virtually any TypeScript or JavaScript task, creating high conflict risk with any other skill that touches TS/JS files (e.g., testing, linting, 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 concrete code examples covering discriminated unions, branded types, Zod validation, and configuration patterns. Its main weaknesses are moderate verbosity from explanatory rationale phrases that Claude doesn't need, and a somewhat monolithic structure that could benefit from splitting detailed sections (Zod, config) into referenced files. The workflow guidance could be strengthened with explicit validation/verification checkpoints.
Suggestions
Remove the rationale phrases after semicolons in the Instructions section (e.g., 'Strong typing catches bugs at compile time') — Claude already knows why these practices matter.
Add explicit verification steps like 'run tsc --noEmit to check for type errors' after implementation steps to strengthen the workflow with validation checkpoints.
Consider extracting the Zod and Configuration sections into separate referenced files (e.g., ZOD.md, CONFIG.md) to keep the main skill as a concise overview with signposted links.
| 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'). The Instructions section contains rationale phrases after semicolons that Claude already knows. The debug logging example adds limited value. However, most code examples are lean and purposeful. | 2 / 3 |
Actionability | Provides fully executable, copy-paste ready TypeScript code examples throughout — discriminated unions, branded types, Zod schemas, exhaustive switches, config validation, and schema composition. Each pattern has concrete, runnable code with good/bad comparisons where appropriate. | 3 / 3 |
Workflow Clarity | The type-first development section has a clear 4-step workflow, but the Instructions section is a flat bullet list without sequencing or validation checkpoints. There are no explicit feedback loops for catching errors during development (e.g., 'run tsc --noEmit to verify', or 'validate schema before deploying'). For a skill that involves writing/modifying TypeScript files, some verification steps would strengthen the workflow. | 2 / 3 |
Progressive Disclosure | Content is well-structured with clear headers and logical sections, but it's a fairly long monolithic file (~200 lines of content). The type-fest section is appropriately marked optional, and there's a good cross-reference to the React skill. However, the Zod section and configuration section could be split into separate reference files to keep the main skill leaner, with signposted links. | 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
f772de4
- 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.