CtrlK
BlogDocsLog inGet started
Tessl Logo

python-design

Python design patterns for CLI scripts and utilities — type-first development, deep modules, complexity management, and red flags. Use when reading, writing, reviewing, or refactoring Python files, especially in .trellis/scripts/ or any CLI/scripting context. Also activate when planning module structure, deciding where to put new code, or doing code review.

63

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/python-design/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

63%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-written, example-driven design reference whose BAD/GOOD pairs and red-flags table give it real practical value. Its weaknesses are length and single-file monolithity: it re-teaches design concepts Claude already knows and inlines ~450 lines of detail that progressive disclosure would split into an overview plus one-level-deep references.

Suggestions

Conciseness: compress the conceptual exposition (complexity symptoms, KISS, rule of three, single responsibility) to one-line statements and let the BAD/GOOD example pairs carry the teaching — Claude already knows these principles and their origin.

Progressive disclosure: move the Red Flags table and the longer per-principle examples into references/ files (e.g., references/red-flags.md, references/principles.md) and keep SKILL.md as a concise overview with clearly signaled one-level-deep links.

Actionability: replace the '...' skeleton bodies in the deep-module and iteration examples with complete implementations, or explicitly label them as illustrative stubs.

DimensionReasoningScore

Conciseness

The BAD/GOOD contrast pairs and red-flags table earn their tokens, but substantial space re-explains concepts Claude already knows — Ousterhout's three complexity symptoms, KISS, single responsibility, rule of three — and the ASCII module diagram plus two overlapping checklists could be tightened. Mostly efficient but padded in the conceptual exposition, matching anchor 3 rather than 4.

3 / 5

Actionability

Mostly executable guidance: concrete BAD/GOOD code pairs for deep modules, NewType, discriminated unions, error design, and semantic whitespace parsing, plus a grep-able red-flags table. Falls short of 5 because several exemplars ('load_task', 'list_active_tasks', 'iter_active_tasks', 'FormatterRegistry') are '...' skeletons/pseudocode without explicit justification, which the guidelines penalize.

4 / 5

Workflow Clarity

The type-first development section gives a clear 4-step sequence (define shapes, signatures, implement, validate at boundaries) and the before-writing/during-review checklists act as process checkpoints. Not 5 because there are no explicit validation commands or feedback loops (e.g., 'run mypy' after step 3), leaving checkpoints implicit rather than executable.

4 / 5

Progressive Disclosure

A single ~450-line file with no references/ or scripts/ bundle; sections are clearly headed and navigable, but the detailed per-principle examples and the red-flags quick reference are exactly the material that belongs in one-level-deep reference files, with SKILL.md as an overview. Good inline structure, but content that should be separate is inline — matching anchor 3 rather than 4, which assumes appropriate placement or mostly-clear references.

3 / 5

Total

14

/

20

Passed

Description

85%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description with an explicit what/when structure, concrete capability vocabulary, and natural trigger phrases in third-person voice. Its main weakness is over-broad triggers — 'writing Python files' could fire on almost any Python work — which raises conflict risk with general coding and review skills.

Suggestions

Narrow the 'Use when' triggers from 'reading, writing, reviewing, or refactoring Python files' to design-shaped situations (e.g., 'Use when designing or restructuring Python scripts, deciding module boundaries, or reviewing Python code for design quality') to reduce overlap with general Python/editing skills.

Add one or two missing natural trigger terms such as '.py files' or 'type hints' to round out keyword coverage.

DimensionReasoningScore

Specificity

The description lists multiple specific concrete capabilities — 'type-first development, deep modules, complexity management, and red flags' — and concrete activities ('reading, writing, reviewing, or refactoring Python files', 'planning module structure', 'deciding where to put new code') with comprehensive coverage of its design niche. Not score 4 because coverage is broad and specific rather than having minor gaps; not below because nothing is vague fluff.

5 / 5

Completeness

It clearly answers both: 'what' ('Python design patterns for CLI scripts and utilities — type-first development, deep modules, complexity management, and red flags') and an explicit 'when' with concrete trigger phrases ('Use when reading, writing, reviewing, or refactoring Python files... Also activate when planning module structure, deciding where to put new code, or doing code review'). This matches the anchor-5 example structure exactly.

5 / 5

Trigger Term Quality

Good keyword coverage with natural user phrases like 'refactoring Python files', 'code review', 'module structure', and 'deciding where to put new code', plus the concrete path '.trellis/scripts/'. A few natural terms are missing (e.g., '.py' extension, 'type hints', 'design review', 'messy script'), so it falls short of the comprehensive-with-synonyms anchor 5.

4 / 5

Distinctiveness Conflict Risk

The design-guidance niche (deep modules, type-first development for CLI scripts) is distinguishable, but the trigger 'reading, writing... Python files' is broad enough to activate on virtually any Python task, creating real overlap risk with general Python, refactoring, and code-review skills. Not 4 because the over-trigger surface is more than 'minor overlap with closely related skills'; not 2 because the technique vocabulary and .trellis/scripts context do anchor it to a specific niche.

3 / 5

Total

17

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository
mindfold-ai/Trellis
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.