CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

software-design-philosophy

Manage software complexity through deep modules, information hiding, and strategic programming. Use when the user mentions "module design", "API too complex", "shallow class", "complexity budget", "strategic vs tactical", "deep module", "information leakage", or "pass-through method". Also trigger when reviewing interface designs for simplicity, evaluating whether an abstraction is pulling its weight, or choosing between general-purpose and special-purpose approaches. Covers deep vs shallow modules, red flags for complexity, and comments as design documentation. For code quality, see clean-code. For boundaries, see clean-architecture.

Quality

84%

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

SKILL.md
Quality
Evals
Security

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.

Well-structured overview with excellent progressive disclosure into six real, one-level-deep reference files, and concrete pattern tables that make an advisory framework actionable. The main costs are padding (author biography, 'why it works' re-explanations of familiar concepts) and the absence of an explicitly sequenced workflow connecting the diagnostic, scoring, and recommendation steps.

Suggestions

Remove the 'About the Author' section and the affiliate 'Further Reading' link, and cut or compress the 'Why it works' paragraphs, which re-explain software-design concepts Claude already knows.

Add a short 'How to apply' workflow that explicitly sequences the pieces: run the Quick Diagnostic on the target design, score it 0-10 against the six principles, then list specific improvements to reach 10/10 (citing the relevant Common Mistakes row).

Deduplicate the 'Key insights' bullets against the 'Code applications' tables within each principle section — most rows restate the same point in both forms.

DimensionReasoningScore

Conciseness

The pattern tables and key-insight bullets are tight, but the 'Why it works' paragraphs re-explain well-known concepts (deep modules, information hiding, strategic programming), key insights overlap with table rows, and the 'About the Author' biography plus the affiliate-tagged 'Further Reading' link are pure padding. This fits anchor 3's 'some unnecessary explanation or could be tightened' better than anchor 4's 'minor instances', since whole sections (author bio, why-it-works) could be removed without losing actionable content.

3 / 5

Actionability

Concrete, specific guidance throughout: pattern tables with real examples ('numBytesReceived not n; retryDelayMs not delay', 'Combine RequestParser, RequestValidator, RequestProcessor into one RequestHandler'), a Quick Diagnostic with question-to-action mappings, and an explicit output protocol ('rate them 0-10... Always provide the current score and specific improvements needed to reach 10/10'). Per the scoring notes, an instruction-only skill is not penalized for lacking runnable code, but the guidance remains advisory heuristics rather than fully executable steps, so anchor 4 fits better than 5.

4 / 5

Workflow Clarity

The components of a process exist (Quick Diagnostic checklist, scoring protocol, common-mistakes fixes) but they are never sequenced into an explicit workflow for applying the framework during a review; the intended order (diagnose, score, recommend) is only implicit. This matches anchor 3's 'sequence present but checkpoints missing or implicit' rather than anchor 4's 'clear sequence with most checkpoints present'.

3 / 5

Progressive Disclosure

The body is a genuine overview: each of the six principles ends with 'See: [references/<file>.md]' and a 'Reference Files' section indexes all six with one-line descriptions. All six bundle files exist and are one level deep (verified: they contain only internal anchor links, no nested file references), matching anchor 5's 'clear overview with well-signaled one-level-deep references'.

5 / 5

Total

15

/

20

Passed

Description

95%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 explicitly answers both what and when, with a rich set of natural quoted trigger phrases and explicit cross-references that reduce conflict with adjacent code-quality and architecture skills. The only weakness is that the capability statement leans on domain topic coverage rather than a fully concrete list of operations.

DimensionReasoningScore

Specificity

The description lists several concrete actions ('Manage software complexity through deep modules, information hiding, and strategic programming', 'reviewing interface designs for simplicity, evaluating whether an abstraction is pulling its weight, or choosing between general-purpose and special-purpose approaches') with only minor coverage gaps. It falls short of anchor 5 because the closing 'Covers deep vs shallow modules, red flags for complexity, and comments as design documentation' reads as topic coverage rather than a comprehensive list of concrete operations.

4 / 5

Completeness

Both parts are explicit: 'what' ('Manage software complexity through deep modules, information hiding, and strategic programming... Covers deep vs shallow modules, red flags for complexity, and comments as design documentation') and 'when' ('Use when the user mentions... Also trigger when reviewing interface designs for simplicity...'). This matches anchor 5's 'clearly and explicitly answers both what AND when with concrete trigger phrases', exceeding anchor 4 where the 'when' is less specific.

5 / 5

Trigger Term Quality

It includes many natural, quoted trigger phrases users would actually say: 'module design', 'API too complex', 'shallow class', 'complexity budget', 'strategic vs tactical', 'deep module', 'information leakage', and 'pass-through method'. Coverage is comprehensive with synonyms across the domain, matching the anchor 5 example's breadth; it is clearly above anchor 4's 'a few natural terms missing'.

5 / 5

Distinctiveness Conflict Risk

Triggers are distinctive to the design-philosophy niche ('deep module', 'pass-through method', 'information leakage'), and it actively disambiguates from adjacent skills ('For code quality, see clean-code. For boundaries, see clean-architecture.'). This is a clear niche with minimal conflict risk, matching anchor 5 rather than anchor 4's 'minor overlap risk'.

5 / 5

Total

19

/

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

valeriibeck-star/claude-skills

Path

skills/software-design-philosophy/SKILL.md

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.