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 around Python type-first development patterns and includes an explicit 'when' clause. However, the trigger condition ('reading or writing Python files') is far too broad, making it fire for any Python work rather than specifically type-related tasks. This creates a high conflict risk with other Python-focused skills.
Suggestions
Narrow the trigger condition from 'reading or writing Python files' to something like 'Use when adding type annotations, defining data models, creating typed interfaces, or implementing type-safe patterns in Python'.
Add natural user-facing trigger terms like 'type hints', 'type annotations', 'typing module', 'type safety', 'typed Python' to improve keyword matching for relevant queries.
| 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 dataclasses, discriminated unions, NewType, and Protocol') and when ('Must use when reading or writing Python files') with an explicit trigger clause. | 3 / 3 |
Trigger Term Quality | Includes good technical terms like 'dataclasses', 'discriminated unions', 'NewType', 'Protocol', and 'Python files', but the trigger is overly broad ('reading or writing Python files') and misses natural user phrases like 'type hints', 'typing', 'type annotations', '.py files'. | 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 every Python file interaction, not just type-related work. | 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 (explanatory comments Claude doesn't need) and a monolithic structure that could benefit from splitting detailed patterns into referenced files. The workflow could be strengthened with explicit validation checkpoints like running a type checker after changes.
Suggestions
Remove explanatory comments that state what Claude already knows (e.g., 'Frozen dataclasses are immutable', 'This makes failures debuggable and prevents silent corruption', 'Resource leaks cause production issues') to improve conciseness.
Add an explicit validation checkpoint to the type-first workflow, e.g., 'After implementing, run `uvx ty check` or `pyright` to verify type correctness before proceeding.'
Consider splitting detailed pattern examples (discriminated unions, Protocol, TypedDict) and the configuration/ty sections into separate referenced files to improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with good code examples, but includes some unnecessary explanation (e.g., 'Frozen dataclasses are immutable - no accidental mutation' comments, explanatory sentences like 'This makes failures debuggable and prevents silent corruption' that Claude already knows). The ty section includes some padding about features Claude would know. Overall it's reasonably lean but could be tightened. | 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. Each pattern has concrete, runnable code with clear usage context. | 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. For a skill that 'must use when reading or writing Python files,' there's no explicit verification step (e.g., run type checker after changes). The steps are listed but implicit about when to validate correctness. | 2 / 3 |
Progressive Disclosure | The content is well-structured with clear headers and sections, but it's a long monolithic file (~200 lines) that could benefit from splitting detailed pattern examples into separate reference files. The ty section and configuration section could be separate files referenced from the main skill. No external file references are used. | 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.