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

74%

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-workflows-frontend/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

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

A well-structured, disciplined principles document with genuinely useful conditional guidance and a clean two-file reference split. It loses points for duplicated bullets, coverage of fundamentals Claude already knows, and abstract directives that lack the concrete examples or thresholds that would make them fully actionable.

Suggestions

Remove near-duplicate bullets (paired naming bullets, the two early-return bullets, and the repeated bottleneck rule in 'When to Optimize') to tighten token use.

Add brief concrete examples or measurable thresholds to the abstract directives (e.g. a tiny before/after snippet for 'single level of abstraction', or coupling signals for 'depend on abstractions').

Trim or move well-known fundamentals (magic numbers, DRY, single responsibility) into a compact list or a reference file so the body focuses on the non-obvious decision criteria.

DimensionReasoningScore

Conciseness

The body is mostly terse imperatives rather than padded prose, but contains near-duplicate bullets ("Use meaningful, descriptive names" vs "Use descriptive names"; the two early-return bullets; the 'When to Optimize' list restating "only after measurable bottlenecks" twice) and restates basics Claude already knows (single responsibility, magic numbers, DRY). It fits anchor 3 ('mostly efficient but could be tightened'): above 2 because there is little explanatory padding, below 4 because the duplication and well-known content could be trimmed.

3 / 5

Actionability

Some guidance is concretely decidable ("single-letter names are acceptable only for loop counters or well-known conventions (i, j, x, y)"; "Mask or exclude passwords, tokens, PII from logs"), but many principles are abstract directives with no examples or thresholds ("Depend on abstractions, not concrete implementations"; "Functions should have a single level of abstraction"), and the body contains no code examples. This matches anchor 3 ('some concrete guidance but incomplete') rather than 4, where most guidance would be executable with only minor gaps.

3 / 5

Workflow Clarity

This is a principles catalog, not a multi-step procedure, so a rigid sequence does not apply; the Refactoring Approach section does give a sequenced micro-workflow with verification ("Run tests after each change", "Maintain working state: Keep tests passing"), and sections are organized by concern. It sits at 4 rather than 5 because there is no explicit guidance on how to order or apply the principles across a task, and 4 rather than 3 because the sequences that do exist include their verification steps.

4 / 5

Progressive Disclosure

Both bundle files exist and are well-signaled with one-level-deep references and explicit load conditions ("For concrete detection patterns used by security review, see references/security-checks.md"; "read when implementing, reviewing, or fixing React/TypeScript code"), with language-agnostic core kept inline and domain specifics split out. It is 4 rather than 5 because the ~165-line body still carries substantial detail (e.g. the full Reference Representativeness and Commenting sections) that could arguably live in references, leaving minor organization gaps.

4 / 5

Total

14

/

20

Passed

Description

75%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 well-formed description with an explicit and multi-trigger 'Use when' clause and natural vocabulary. Its main weaknesses are the absence of concrete capability verbs (it states topics rather than actions) and overly broad triggers that could conflict with dedicated code-review or refactoring skills.

Suggestions

State one or two concrete capabilities instead of only topic areas, e.g. "Applies coding principles for maintainability, readability, and quality; reviews code against them".

Narrow the trigger clause or add distinguishing terms (e.g. "use when writing or reviewing code against quality/maintainability principles") to reduce overlap with dedicated code-review and refactoring skills.

Add common user phrasings such as "code review", "clean code", or "best practices" to the trigger terms.

DimensionReasoningScore

Specificity

"Language-agnostic coding principles for maintainability, readability, and quality" names the domain plus its focus areas, but describes no concrete capabilities or actions (compare "Extracts text and tables from PDF files, fill forms"), matching the anchor 'names domain and 1-2 concrete actions'. It is above 2 because the three named quality attributes give more substance than a purely generic phrase, but below 4 because there are no enumerated actions at all.

3 / 5

Completeness

The description explicitly answers both: what ("Language-agnostic coding principles for maintainability, readability, and quality") and when ("Use when implementing features, refactoring code, or reviewing code quality") with three concrete trigger phrases, matching the top anchor. It is not 4 because the 'when' clause is already explicit and multi-trigger, not merely adequate.

5 / 5

Trigger Term Quality

"implementing features", "refactoring code", "reviewing code quality" are natural phrases users would say when needing this skill. Below 5 because common variations like "code review", "clean code", "best practices", or specific languages are missing.

4 / 5

Distinctiveness Conflict Risk

The trigger "implementing features" is broad enough to fire on nearly any coding task, and the skill overlaps with dedicated code-review or refactoring skills. It is somewhat specific (quality principles, not general help) but overlaps with similar skills, matching anchor 3; not 4 because "implementing features" creates real overlap risk.

3 / 5

Total

15

/

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-workflows-frontend/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.