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 risk with other Python-related skills. The trigger should be scoped to type-related work rather than all Python file operations.
Suggestions
Narrow the trigger condition from 'when 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 more natural user-facing trigger terms like 'type hints', 'type annotations', 'typing module', 'type safety', '.py type patterns' to improve discoverability
| 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 'what' (provides Python patterns for type-first development with specific constructs) and 'when' ('Must use when reading or writing Python files'). The explicit trigger clause is present. | 3 / 3 |
Trigger Term Quality | Includes relevant technical terms like 'dataclasses', 'discriminated unions', 'NewType', 'Protocol', and 'Python files', but these are more specialized terms than what a typical user would naturally say. Missing common variations 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 is about type patterns specifically, but the trigger would fire for any Python file interaction. | 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 concrete code examples covering a wide range of Python typing patterns. Its main weaknesses are moderate verbosity from explanatory comments Claude doesn't need, and the lack of an integrated validation/type-checking workflow that ties the ty tool back into the development process. The content would benefit from trimming rationale sentences and splitting detailed patterns into referenced sub-files.
Suggestions
Remove explanatory rationale sentences after instructions (e.g., 'Resource leaks cause production issues', 'Swallowed exceptions hide root causes') — Claude already knows why these matter.
Integrate the ty type checker into the type-first development workflow as an explicit validation checkpoint (e.g., 'After step 3, run `uvx ty check` and fix all errors before proceeding').
Consider splitting detailed pattern examples (discriminated unions, TypedDict, Protocol, config) into a referenced PATTERNS.md file, keeping SKILL.md as a concise overview with one example per pattern.
| 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, explanations like 'Resource leaks cause production issues' and 'Swallowed exceptions hide root causes' that Claude already knows). The rationale sentences after instructions add bulk without adding actionable value. | 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 ty usage. Every pattern is demonstrated with concrete, runnable code. | 3 / 3 |
Workflow Clarity | The type-first development workflow has a clear 4-step sequence at the top, but lacks validation checkpoints — there's no explicit 'run the type checker and fix errors' step integrated into the workflow. The ty section is mentioned as optional rather than woven into a verification loop. | 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 (discriminated unions, TypedDict, config) into separate reference files. No external file references are provided for deeper dives. | 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.