tessl-labs/python-project-structure
Python project structure — pyproject.toml, src layout, __init__.py, .gitignore, dependency groups, type hints, py.typed, test structure, entry points, ruff/mypy configuration
91
87%
Does it follow best practices?
Impact
99%
1.03xAverage score across 5 eval scenarios
Passed
No known issues
Quality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that excels across all dimensions. It provides comprehensive specificity with concrete Python project elements, includes natural trigger terms that match how users actually ask questions, explicitly addresses both what and when with detailed trigger scenarios, and carves out a clear niche that distinguishes it from general Python coding skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete elements: pyproject.toml, src layout, __init__.py, .gitignore, virtual environments, type hints, py.typed, test structure, entry points, dependency groups, and tool configuration. These are all concrete, actionable components. | 3 / 3 |
Completeness | Clearly answers both what (Python project structure best practices with specific elements) AND when (explicit 'Use when...' clause plus detailed 'Triggers on:' section covering multiple scenarios). Both sections are comprehensive and explicit. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'new FastAPI/Flask/Django project', 'CLI tool setup', 'Python library scaffolding', 'where should I put this', 'missing pyproject.toml', 'setup.py migration', 'dependency management questions'. These match real user language patterns. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with clear niche around Python project structure and organization. The specific triggers like 'pyproject.toml', 'src layout', 'setup.py migration' are unlikely to conflict with general Python coding skills or other language skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, comprehensive skill for Python project structure that excels in actionability with executable code examples and good progressive disclosure through clear section organization. The main weaknesses are some verbosity in explanatory sections that Claude doesn't need, and missing validation checkpoints after setup steps (e.g., 'run pip install -e . and verify with pip list' or 'run ruff check . to confirm configuration').
Suggestions
Remove explanatory paragraphs like 'Why not setup.py' and 'Why ruff over flake8' - Claude knows these tradeoffs
Add validation commands after key setup steps, e.g., 'Verify: pip install -e . && python -c "import my_project"' after package setup
Add a verification step to the Quick Checklist items, e.g., '[ ] Run ruff check . and mypy . with no errors'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive but includes some unnecessary explanations Claude would know (e.g., explaining why setup.py is legacy, what type hints are). Some sections like 'Why not setup.py' and 'Why ruff over flake8' add context Claude doesn't need. However, the code examples are lean and the structure is efficient overall. | 2 / 3 |
Actionability | Excellent actionability with fully executable code examples throughout. Every pattern includes copy-paste ready pyproject.toml snippets, Python code, and bash commands. The FastAPI example section provides complete, working code for a real application structure. | 3 / 3 |
Workflow Clarity | The skill provides clear patterns but lacks explicit validation steps. For example, after setting up pyproject.toml or configuring ruff/mypy, there are no verification commands (e.g., 'run ruff check . to verify configuration'). The Quick Checklist at the end is helpful but doesn't include validation/verification steps for each action. | 2 / 3 |
Progressive Disclosure | Well-organized with clear section headers using 'Critical Pattern' labels. Content is appropriately structured with a quick checklist summary at the end. References to verifiers are clearly signaled. The skill is self-contained without requiring deep navigation chains. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (571 lines); consider splitting into references/ and linking | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
Reviewed
Table of Contents