architecture-python
Python architecture: PEP-8, type hints, clean layering, dependency injection, and testing strategy
53
58%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/architecture-python/SKILL.mdQuality
Discovery
32%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 reads as a list of Python architecture topics rather than a functional skill description. It lacks action verbs describing what the skill does and has no 'Use when...' clause to guide skill selection. While the technical keywords provide some specificity, the description needs significant improvement to be effective for skill routing.
Suggestions
Add action verbs describing what the skill does, e.g., 'Guides Python project architecture decisions including module structure, clean layering, and dependency injection patterns.'
Add an explicit 'Use when...' clause, e.g., 'Use when the user asks about Python project structure, code organization, architectural patterns, or best practices for maintainable Python code.'
Include natural language trigger terms users would actually say, such as 'project structure', 'code organization', 'Python best practices', 'how to structure a Python project', or 'clean architecture'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Python architecture) and lists several specific concepts (PEP-8, type hints, clean layering, dependency injection, testing strategy), but these read more like topic keywords than concrete actions the skill performs. No verbs describe what the skill actually does. | 2 / 3 |
Completeness | The description only loosely addresses 'what' (Python architecture topics) without any verbs or actions, and completely lacks a 'when' clause or any explicit trigger guidance. Per the rubric, a missing 'Use when...' clause caps completeness at 2, and the 'what' is also weak, warranting a 1. | 1 / 3 |
Trigger Term Quality | Includes relevant technical keywords like 'PEP-8', 'type hints', 'dependency injection', and 'testing strategy' that users might mention, but misses common natural language variations like 'Python best practices', 'code structure', 'project layout', or 'clean code'. The terms lean technical rather than conversational. | 2 / 3 |
Distinctiveness Conflict Risk | The combination of Python architecture-specific terms like PEP-8, dependency injection, and clean layering provides some distinctiveness, but 'type hints' and 'testing strategy' are broad enough to overlap with general Python coding or testing skills. | 2 / 3 |
Total | 7 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured architectural reference skill that is concise, well-organized, and respects Claude's intelligence. Its main weakness is that some sections (error handling, async) provide rules without concrete code examples, making them slightly less actionable than the patterns section. Overall it serves well as a quick-reference guide for Python architecture decisions.
Suggestions
Add a brief executable code example for error handling showing domain exception definition and boundary-layer catch pattern
Add a small async example demonstrating asyncio.gather for concurrent I/O to make that section more actionable
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every section is lean and assumes Claude already knows Python. No unnecessary explanations of what PEP-8 is, what type hints are, or how asyncio works — just direct, actionable guidance. Every token earns its place. | 3 / 3 |
Actionability | Provides a concrete project structure and a Protocol example, but most guidance is rule-based rather than executable. The async section and error handling section describe principles without concrete code examples. The repository pattern example is good but incomplete (no implementation shown). | 2 / 3 |
Workflow Clarity | This is an architectural reference skill, not a multi-step process skill. The content is clearly sequenced from code quality → structure → patterns → error handling → async, which is a logical progression. No destructive or batch operations require validation checkpoints. | 3 / 3 |
Progressive Disclosure | For a skill under 50 lines with no need for external references, the content is well-organized into clearly labeled sections with appropriate depth. Each section is self-contained and scannable. No monolithic walls of text or unnecessary nesting. | 3 / 3 |
Total | 11 / 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
- ucdavis/ai-skills-registry
- Commit
c0b2e4b
- 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.