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 typing constructs and includes an explicit 'when' clause, but the trigger condition is far too broad—'reading or writing Python files' would cause this skill to activate for essentially all Python work, creating massive conflict risk with other Python skills. The typing-specific nature of the skill is undermined by the overly aggressive trigger.
Suggestions
Narrow the trigger to match the skill's actual scope, e.g., 'Use when the user asks about Python type annotations, type safety, dataclasses, Protocols, NewType, or discriminated unions.'
Add natural user-facing trigger terms like 'type hints', 'type annotations', 'type checking', 'mypy', 'typing module' to improve trigger term coverage for the skill's actual domain.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions and patterns: 'type-first development with dataclasses, discriminated unions, NewType, and Protocol.' These are concrete, specific Python typing constructs. | 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 relevant terms like 'Python', 'dataclasses', 'discriminated unions', 'NewType', 'Protocol', but the trigger is overly broad ('reading or writing Python files') and misses natural user phrases like 'type hints', 'typing', 'type annotations', 'type safety'. | 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 typing 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, example-rich skill that provides actionable Python typing patterns with executable code throughout. Its main weaknesses are moderate verbosity from explanatory comments Claude doesn't need, and a type-first workflow that lacks concrete validation checkpoints (e.g., when to run ty/mypy during the process). The content would benefit from trimming rationale sentences and adding an explicit 'run type checker' step in the workflow.
Suggestions
Remove the explanatory rationale sentences after bullet points (e.g., 'This makes failures debuggable and prevents silent corruption') — Claude already understands why these practices matter.
Add an explicit type-checking validation step to the workflow, e.g., 'After implementing, run `uvx ty check` and fix all errors before proceeding' to create a proper feedback loop.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with good code examples, but includes some unnecessary explanation Claude would already know (e.g., 'Frozen dataclasses are immutable - no accidental mutation', 'Resource leaks cause production issues', 'Swallowed exceptions hide root causes'). The rationale comments after several bullet points are redundant for Claude. The ty section includes comparative guidance that adds moderate value but could be tighter. | 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 vague 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. For a skill that 'must use when reading or writing Python files,' there's no guidance on when to run type checking during the workflow, no verify-then-proceed pattern, and the steps are more philosophical than operational. | 2 / 3 |
Progressive Disclosure | The content is well-organized with clear section headers, but it's a monolithic file (~200 lines) with no references to supporting files. The ty tool section, configuration patterns, and detailed type examples could be split into separate reference files. However, for a skill of this size, the inline approach is borderline acceptable. | 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
2d09b29
- 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.