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

68%

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 ./skills/coding-principles/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

53%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 a well-organized, well-referenced principles document whose distinctive decision criteria (Design Convergence, the comment justification test, conditional retain/extract guidance) add genuine value. It is dragged down by redundancy across sections, a large share of generic programming wisdom Claude already knows, and the absence of any explicit validation checkpoints for the quasi-procedural sections (refactoring, reference expansion).

Suggestions

Deduplicate overlapping bullets (early returns, function extraction, optimization timing, naming guidance) by merging each pair into a single entry, cutting token cost without losing content.

Remove or compress well-known principles ('Fail fast', 'Separate concerns', 'Measure first', 'Each function should do one thing well') and keep only the project-specific decision criteria that go beyond Claude's defaults.

Add explicit validation checkpoints to the quasi-procedural sections, e.g. refactoring ('after each step, run the test suite; stop and revert if red') and reference expansion ('record which consumers were checked and which remain unverified').

DimensionReasoningScore

Conciseness

The body uses lean bullet style with no padded prose, but contains duplicated guidance (early returns appear at both 'Use early returns to reduce nesting' and the following bullet; function extraction is stated twice; optimization timing is stated twice) and many generic principles Claude already knows ('Fail fast', 'Separate concerns', 'Measure first'). This matches anchor 3 ('mostly efficient but could be tightened'), not 4 because the redundancy and well-known content are more than minor.

3 / 5

Actionability

Some entries give concrete, decidable criteria ('Mask or exclude passwords, tokens, PII from logs', 'Group related positional parameters into an object... when call-site clarity or coordinated evolution requires it', 'Split a file when it contains independently changing responsibilities'), but much of the guidance is abstract direction ('Keep code self-documenting where possible', 'Each function should do one thing well') that restates common knowledge. This is anchor 3 ('some concrete guidance but incomplete'), below 4 because concrete executable specifics are the minority.

3 / 5

Workflow Clarity

This is a principles skill, not a procedural one; partial sequences exist (refactoring: 'small steps... run tests after each change'; the reference-expansion procedure in 'Reference Representativeness') but there are no explicit validation checkpoints or feedback loops anywhere in the body. That matches anchor 3 ('sequence present but checkpoints missing or implicit'), and the simple-skill exception does not apply since this is a 165-line multi-topic skill rather than a single unambiguous action.

3 / 5

Progressive Disclosure

Both referenced files exist in the bundle, are one level deep, and are well signaled with purpose and trigger conditions ('read when implementing, reviewing, or fixing React/TypeScript code'; 'For concrete detection patterns used by security review, see references/security-checks.md'). Sections are clearly organized, but the 165-line body inlines dense domain-specific prose (e.g. the two-paragraph 'Reference Representativeness' section) that could arguably live in a reference, matching anchor 4 rather than 5.

4 / 5

Total

13

/

20

Passed

Description

66%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 solid description with an explicit and well-phrased 'Use when...' trigger clause covering the three main use cases. Its weaknesses are an abstract 'what' (qualities rather than concrete actions or deliverables) and broad overlap risk with other code-quality and review skills.

Suggestions

Make the 'what' more concrete, e.g. 'Applies a checklist of language-agnostic principles covering naming, function design, error handling, security defaults, and commenting' instead of naming only the target qualities.

Add common trigger synonyms such as 'code review', 'writing new code', or 'clean code' to reduce missed activations.

Sharpen distinctiveness by stating what this skill is not (e.g. 'principles only; language-specific rules live in references') to reduce conflict with dedicated code-review skills.

DimensionReasoningScore

Specificity

The description names the domain ('Language-agnostic coding principles') and the target qualities ('maintainability, readability, and quality'), but offers deliverable attributes rather than concrete actions the skill performs. It sits between anchor 2 (generic actions) and anchor 4 (several specific actions); the three named quality areas keep it at 3.

3 / 5

Completeness

Both parts are present: the 'what' ('Language-agnostic coding principles for maintainability, readability, and quality') and an explicit 'Use when...' clause with three concrete triggers. The 'what' is more abstract than anchor 5's fully concrete action list, so it fits anchor 4 ('when' explicit, 'what' could be more specific) rather than 5, and clearly above 3 since 'when' is explicit.

4 / 5

Trigger Term Quality

'implementing features', 'refactoring code', and 'reviewing code quality' are natural phrases users would say when needing this skill. Common variations such as 'code review', 'clean code', or 'writing code' are missing, matching the 'good keyword coverage; a few natural terms missing' anchor rather than 5.

4 / 5

Distinctiveness Conflict Risk

The broad coding-quality domain and the trigger 'reviewing code quality' create real overlap risk with code-review, refactoring, and security-review skills, matching anchor 3 ('somewhat specific but could still overlap with similar skills'). It is not anchor 4 because the overlap extends beyond closely related skills, and not anchor 2 because the language-agnostic framing plus explicit triggers give it a discernible niche.

3 / 5

Total

14

/

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

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.