CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

coding-principles

Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.

Quality

63%

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 ./dev-skills/skills/coding-principles/SKILL.md

The canonical home for this skill is coding-principles in shinpr/claude-code-workflows

SKILL.md
Quality
Evals
Security

Quality

Content

46%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 skill is well-structured with appropriately split, clearly conditioned one-level-deep references, but a substantial share of its body restates coding fundamentals Claude already knows and includes multiple duplicated bullets. Guidance oscillates between genuinely concrete directives and abstract principle statements without examples.

Suggestions

Remove duplicated bullets (the naming pair, the early-returns pair, the optimization-timing restatement) and cut sections that restate fundamentals Claude already knows (DRY, single responsibility, fail fast, high cohesion/low coupling), keeping only the non-obvious decision criteria like the commenting test and Reference Representativeness.

Convert abstract directives into concrete good/bad micro-examples (e.g. a before/after naming pair, a masked-log example) so more of the guidance is actionable rather than descriptive.

Move the security-checks link into the References section alongside frontend.md with its read condition, and clarify in frontend.md that it points to another skill's reference, to make navigation fully consistent.

DimensionReasoningScore

Conciseness

The body restates textbook knowledge Claude already knows ("Each function should do one thing well", "Measure first: Profile before optimizing", DRY, fail fast, high cohesion/low coupling) and contains several near-duplicate bullets ("Use meaningful, descriptive names" vs "Use descriptive names; single-letter names..."; "Use early returns to reduce nesting" vs the following bullet; "Optimize only after measurable bottlenecks are identified" restating the two bullets above it). This matches anchor 2 ("noticeably verbose; several unnecessary explanations or padded sections") rather than anchor 3, where redundancy would be occasional rather than systematic.

2 / 5

Actionability

Some bullets give concrete, executable guidance ("Use parameterized queries (prepared statements) for all database access", "Mask or exclude passwords, tokens, PII from logs", "Inject external dependencies as parameters"), but many others are abstract directives with no specifics or examples ("Keep the codebase lean and focused", "High cohesion within modules, low coupling between"). This fits anchor 3 ("some concrete guidance but incomplete") for an instruction-only skill; it is not anchor 4 because much of the guidance lacks operational detail or good/bad examples.

3 / 5

Workflow Clarity

This is a principles reference, not a process skill, and the quasi-workflows present are partially validated: Safe Refactoring sequences small steps with "Run tests after each change", and Reference Representativeness gives a procedure with an explicit stop condition. However there is no coherent overall workflow and checkpoints elsewhere (e.g. refactoring triggers, comment test) are implicit, matching anchor 3 ("steps listed but validation gaps") rather than anchor 4.

3 / 5

Progressive Disclosure

The body is organized into clear sections with two real, one-level-deep references that are signaled with read conditions ("read when implementing, reviewing, or fixing React/TypeScript code"; "For concrete detection patterns used by security review, see references/security-checks.md"), and specialized content is appropriately split out. It falls short of anchor 5 because the security-checks link is buried mid-body while the References section lists only frontend.md, and frontend.md itself points to another skill's file, creating minor navigation inconsistency.

4 / 5

Total

12

/

20

Passed

Description

62%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 follows the good pattern of an explicit what plus a "Use when..." trigger clause in third person, with natural trigger phrases. Its weaknesses are an abstract 'what' that names quality attributes rather than concrete capabilities, and overly broad triggers that create conflict risk with general coding skills.

Suggestions

Replace abstract quality attributes with concrete capability areas, e.g. "Apply checklists for naming, function design, error handling, commenting, and secure coding. Use when implementing features..." so the 'what' enumerates what the skill actually provides.

Narrow or differentiate the trigger clause (e.g. "clean code review", "code quality review", "deciding when to extract a function or split a file") so the skill is less likely to fire for every coding task and conflict with language-specific or review-specific skills.

Add one or two common user phrasings (e.g. "writing code", "code style") to the trigger clause for better keyword coverage.

DimensionReasoningScore

Specificity

"Language-agnostic coding principles for maintainability, readability, and quality" names the domain and three quality attributes but offers no concrete actions or deliverables. It sits above anchor 2 ("actions minimal or generic") because the scope attributes add specificity, but below anchor 4, which requires several specific listed actions.

3 / 5

Completeness

Both what ("coding principles for maintainability, readability, and quality") and when (explicit "Use when..." with three trigger phrases) are present, satisfying anchor 4. It falls short of anchor 5 because the 'what' remains abstract — no concrete capabilities or principle areas are enumerated to pair with the concrete triggers.

4 / 5

Trigger Term Quality

"Use when implementing features, refactoring code, or reviewing code quality" provides natural phrases users would say, matching anchor 4's "good keyword coverage; a few natural terms missing". It is not anchor 5 because common variations like "writing code", "clean code", "code style", or "code review" are absent.

4 / 5

Distinctiveness Conflict Risk

Triggers on "implementing features" and "refactoring code" cover nearly all coding work, creating high overlap with any code-style, review, or refactoring skill, which matches anchor 2 ("very broad; high overlap risk"). It does not reach anchor 3 because the scoped "language-agnostic coding principles" framing still does not carve a genuinely distinct niche from general coding-assistant skills.

2 / 5

Total

13

/

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

shinpr/claude-code-workflows

Path

dev-skills/skills/coding-principles/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.