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.

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

65%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.

The body is highly actionable with strong concrete examples and useful review aids, but it is a long monolithic reference that explains some philosophy Claude already knows and does not split detailed material into bundle files. Tightening the philosophical sections and externalizing the reference material would lift the weaker dimensions.

Suggestions

Move the Red Flags Quick Reference and the per-principle extended code examples into a references/ file (e.g. references/red-flags.md), keeping SKILL.md as a lean overview with one-level-deep links to improve progressive_disclosure.

Trim the "Core Thesis" and "Strategic Investment" sections to a few lines each, since the complexity-management philosophy is largely familiar; this respects the token budget and lifts conciseness.

Add an explicit review workflow with validation checkpoints (e.g. run the red-flags scan, then the type-safety and information-hiding checks, then re-scan) so the during-review process has a clear sequenced loop.

Dimension	Reasoning	Score
Conciseness	The ~450-line body is dense and mostly actionable, but the opening "Core Thesis" (Change Amplification, Cognitive Load, Unknown Unknowns) and closing "Strategic Investment" sections restate design-philosophy concepts Claude already knows and could be trimmed.	3 / 5
Actionability	Every principle ships concrete BAD/GOOD code pairs (e.g. run_git, remove_agent, ensure_workspace), a red-flags quick-reference table, and two ordered design checklists — copy-paste-ready guidance covering the common cases.	5 / 5
Workflow Clarity	Two checklists ("Before Writing Code", "During Code Review") provide sequenced steps, but this is a reference of principles rather than a procedural workflow, and there are no explicit validation checkpoints tying the steps together.	3 / 5
Progressive Disclosure	The skill is a well-headed monolithic ~450-line SKILL.md with no bundle files and no external references; material that could live in separate files (the red-flags table, detailed per-principle examples) is all inlined, so structure exists but content is not split for progressive disclosure.	3 / 5
	Total	14 / 20 Passed

Description

87%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.

The description is strong: it answers what and when explicitly, uses third-person voice, and is scoped to a distinct Python CLI/scripting niche with natural trigger terms. Minor room to tighten trigger synonyms, but no structural weaknesses.

Dimension	Reasoning	Score
Specificity	Names the domain plus several concrete capabilities — "type-first development, deep modules, complexity management, and red flags" — giving specific topical coverage rather than vague abstraction, though these are themes rather than discrete actions.	4 / 5
Completeness	It explicitly states both the "what" (Python design patterns for CLI scripts and utilities — type-first development, deep modules, complexity management, red flags) and the "when" ("Use when reading, writing, reviewing, or refactoring Python files... Also activate when planning module structure...") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural user-facing phrases like "reading, writing, reviewing, or refactoring Python files", "planning module structure", and "doing code review" appear, plus the concrete ".trellis/scripts/" and "CLI/scripting context"; a few common synonyms are absent.	4 / 5
Distinctiveness Conflict Risk	Scoped tightly to Python design for CLI/scripting contexts with a named directory (".trellis/scripts/") and design-review triggers, giving it a clear niche with minimal overlap against generic Python or doc-handling skills.	5 / 5
	Total	18 / 20 Passed

Validation

100%

Warnings & errors only

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
Path: .claude/skills/python-design/SKILL.md
Commit: 64e6636

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

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.