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

86%

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

Quality

Content

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 well-organized, highly actionable design skill with strong code examples and clear section structure, scoring high on actionability and progressive disclosure. Its main weaknesses are restating concepts Claude already knows (conciseness) and lacking explicit validation checkpoints in its review/refactor workflows (workflow_clarity).

Suggestions

Trim or compress the 'Core Thesis' complexity definitions and explanatory prose that restate general software-design concepts Claude already knows, keeping only the scripting-specific framing.

Add explicit validation/verification checkpoints to the code-review and refactoring workflows (e.g., 'run the type checker / tests after applying a refactor; only proceed if they pass') to lift workflow_clarity.

Move the long Red Flags table into a bundled reference file if the skill grows, so the overview stays lean.

Dimension	Reasoning	Score
Conciseness	The body is largely lean and assumes Claude's competence with concrete BAD/GOOD code pairs, but the 'Core Thesis' complexity definitions and several explanatory paragraphs restate software-design concepts Claude already knows, adding tokens that could be trimmed.	2 / 3
Actionability	Provides numerous complete, executable code snippets (frozen dataclasses, TypedDict, NewType, discriminated unions with match statements) plus a red-flags table and concrete checklists that are copy-paste ready guidance.	3 / 3
Workflow Clarity	The Type-First Development section gives a clear 4-step sequence and the design checklists are ordered, but there are no validation/verification checkpoints or feedback loops for the review/refactoring workflows it describes, which the rubric caps at 2 for processes lacking validation.	2 / 3
Progressive Disclosure	No bundle files exist and none are referenced; the skill is self-contained at well under the threshold where external references are needed, organized into clearly headed sections (Principles, Red Flags, Checklists), so it qualifies for a top score per the simple-skills guidance.	3 / 3
	Total	10 / 12 Passed

Description

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.

The description is specific, third-person, and clearly states both what the skill does and when to activate it, with natural trigger terms and a well-scoped niche that minimizes conflict risk. It is a strong, well-rounded description.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete capabilities — 'type-first development, deep modules, complexity management, and red flags' — naming several distinct design actions rather than vague language.	3 / 3
Completeness	Explicitly answers both what ('Python design patterns for CLI scripts and utilities ...') and when ('Use when reading, writing, reviewing, or refactoring Python files ... Also activate when ...'), with an explicit trigger clause.	3 / 3
Trigger Term Quality	Covers natural user phrasings such as 'reading, writing, reviewing, or refactoring Python files', 'code review', 'planning module structure', and 'refactoring', which a user would naturally say.	3 / 3
Distinctiveness Conflict Risk	Niche is clearly scoped to Python CLI/script design with distinct triggers (.trellis/scripts/, module structure, refactoring), making it unlikely to fire for unrelated skills.	3 / 3
	Total	12 / 12 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: .agents/skills/python-design/SKILL.md
Commit: 12e279a

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.