python-best-practices
Provides Python patterns for type-first development with dataclasses, discriminated unions, NewType, and Protocol. Must use when reading or writing Python files.
76
67%
Does it follow best practices?
Impact
88%
1.66xAverage 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/python-best-practices/SKILL.mdQuality
Discovery
70%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 does well at specifying concrete capabilities (dataclasses, discriminated unions, NewType, Protocol) and includes an explicit 'when' clause. However, the trigger condition 'Must use when reading or writing Python files' is far too broad—it would activate for any Python task, creating massive conflict potential with other Python-related skills and diluting its specificity as a typing/type-system skill.
Suggestions
Narrow the trigger condition to type-related contexts, e.g., 'Use when writing Python code involving type annotations, dataclasses, union types, or protocol-based interfaces'
Add natural user trigger terms like 'type hints', 'type annotations', 'typing module', 'type safety' to help distinguish from general Python skills
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete patterns: dataclasses, discriminated unions, NewType, and Protocol. Clearly names the domain (Python type-first development) and specific actions/concepts. | 3 / 3 |
Completeness | Clearly answers both 'what' (provides Python patterns for type-first development with specific constructs) and 'when' ('Must use when reading or writing Python files'). The 'when' clause is explicit, though arguably too broad. | 3 / 3 |
Trigger Term Quality | Includes relevant terms like 'Python', 'dataclasses', 'discriminated unions', 'NewType', 'Protocol', and 'Python files', but the trigger is overly broad ('reading or writing Python files') which would match virtually any Python task, not just type-related ones. Missing natural user terms like 'typing', 'type hints', 'type annotations', '.py'. | 2 / 3 |
Distinctiveness Conflict Risk | The trigger 'Must use when reading or writing Python files' is extremely broad and would conflict with virtually any Python-related skill. This skill would fire for all Python work, not just type-system-related tasks, creating high conflict risk. | 1 / 3 |
Total | 9 / 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 skill with excellent executable code examples covering Python type-first development patterns. Its main weaknesses are moderate verbosity from explanatory comments that Claude doesn't need, and a monolithic structure that could benefit from splitting advanced topics into referenced files. The workflow section would benefit from explicit validation checkpoints (e.g., 'run ty check after defining types').
Suggestions
Remove rationale phrases like 'Resource leaks cause production issues' and 'Swallowed exceptions hide root causes' — Claude already knows why these patterns matter.
Add an explicit validation checkpoint to the type-first workflow, e.g., 'After step 2, run `uvx ty check` to verify signatures before implementing.'
Consider splitting the ty tooling section and configuration patterns into separate referenced files to improve progressive disclosure for this longer skill.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with good code examples, but includes some unnecessary explanation Claude already knows (e.g., 'Frozen dataclasses are immutable - no accidental mutation', 'Resource leaks cause production issues', 'Swallowed exceptions hide root causes'). The rationale comments after instructions add tokens without adding actionable value. The ty section includes comparative guidance that's somewhat verbose. | 2 / 3 |
Actionability | The skill provides fully executable, copy-paste ready Python code examples throughout — dataclasses, discriminated unions, NewType, Protocol, TypedDict, config patterns, error handling, and logging. Every pattern is demonstrated with concrete, runnable code rather than pseudocode or abstract descriptions. | 3 / 3 |
Workflow Clarity | The type-first development workflow has a clear 4-step sequence at the top, but lacks validation checkpoints or feedback loops. There's no guidance on what to do when type checking fails, no explicit 'run the type checker after step N' checkpoint, and the workflow steps are high-level without concrete commands tying them together. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers and logical grouping, but it's a monolithic file with no references to supporting documents. At ~200 lines covering multiple concerns (types, module structure, functional patterns, error handling, configuration, tooling), some sections like the ty tool comparison or configuration patterns could be split into separate files. | 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.