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.

61

Quality

77%

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 ./.agents/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.

This is a genuinely useful, example-driven design manual with strong BAD/GOOD contrasts and actionable checklists. Its two weaknesses are token efficiency — it re-explains well-known software design principles Claude already knows — and the absence of any progressive disclosure, inlining ~450 lines of reference material that should be split into bundled reference files.

Suggestions

Move the Red Flags Quick Reference table and the detailed type-pattern examples (discriminated unions, NewType, TypedDict) into a references/ file (e.g., references/red-flags.md, references/type-patterns.md), leaving SKILL.md as a lean overview of the nine principles with pointers.

Cut the generic principle prose Claude already knows (the deep-module ASCII diagram, "complexity is incremental", KISS/rule-of-three rationale) and keep only the project-specific application: the BAD/GOOD pairs against task.json, registry, and common/ conventions.

Complete the truncated code examples (give `load_task`/`list_active_tasks` real bodies or mark them clearly as contracts) and define or stub the referenced helpers (`GitError`, `check_process`, `create_pr`) so examples are copy-paste runnable.

DimensionReasoningScore

Conciseness

The body re-explains concepts Claude already knows — deep modules, information hiding, KISS, the rule of three, single responsibility, "complexity is incremental" — before applying them. The project-specific BAD/GOOD pairs are the real value, but they are diluted by generic principle prose and an ASCII-art diagram that could be tightened. Not a 2 because most sections are example-driven rather than padded; not a 4 because several full sections add background Claude does not need.

3 / 5

Actionability

Concrete BAD/GOOD code pairs, a capability-to-module placement table, red-flags table, and two checklists give mostly executable guidance. Minor gaps keep it from a 5: `load_task`/`list_active_tasks` bodies are `...` placeholders, and helpers like `GitError`, `check_process`, and `create_pr` are referenced but never defined.

4 / 5

Workflow Clarity

The type-first development section is a clearly sequenced 4-step workflow, and the "before writing code" / "during code review" checklists serve as explicit checkpoints. No validation feedback loops are required since the skill involves no destructive or batch operations, so the missing-validation cap does not apply. A 5 would require tighter coupling of the checklists to the principles they verify.

4 / 5

Progressive Disclosure

There are no bundle files at all: the entire ~450-line manual (nine principles, red-flags table, detailed type-pattern examples, checklists) is inlined in SKILL.md. Sections are well-organized and navigable, but content that clearly belongs in separate reference files (e.g., the red-flags quick reference and the advanced type patterns) loads into context unconditionally. This fits the anchor of "some structure but content that should be separate is inline" — better than a 2 thanks to clear headers, short of a 4 given zero offloading.

3 / 5

Total

14

/

20

Passed

Description

80%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 that clearly answers both what the skill does and when to use it, with good natural trigger phrases. Its main weakness is trigger breadth: "reading, writing, reviewing, or refactoring Python files" would activate on almost any Python work, creating overlap risk with other Python-oriented skills.

DimensionReasoningScore

Specificity

The description lists several specific capability areas — "type-first development, deep modules, complexity management, and red flags" — anchored to a named domain ("Python design patterns for CLI scripts and utilities"). It falls short of a 5 because these are topic labels rather than concrete executable actions (like "extract text and tables"), leaving minor coverage gaps.

4 / 5

Completeness

Both questions are answered explicitly and concretely: what ("Python design patterns for CLI scripts and utilities — type-first development, deep modules, complexity management, and red flags") and when ("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 score-5 anchor's structure of a full what-plus-when with concrete trigger phrases.

5 / 5

Trigger Term Quality

Natural phrases users would say are present: "reading, writing, reviewing, or refactoring Python files", "code review", "planning module structure", "CLI/scripting context". Not a 5 because common variations like "clean code", "best practices", or "refactor this script" as distinct keyword clusters are only partially covered.

4 / 5

Distinctiveness Conflict Risk

The niche (design patterns for CLI scripts, ".trellis/scripts/") is somewhat distinct, but the trigger "reading, writing, reviewing, or refactoring Python files" fires on virtually any Python task, creating real overlap risk with general Python or language-specific skills. It is more specific than a generic "helps with code" (1-2) but does not have the minimal-conflict niche of a 5 or the mostly-distinct profile of a 4.

3 / 5

Total

16

/

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.