coding-principles

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

Quality

55%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/coding-principles/SKILL.md

Quality

Content

61%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-structured, mostly lean principles reference with concrete actionable directives and a properly signaled one-level reference file. Its main weaknesses are redundant bullets that dilute conciseness and the absence of a coherent multi-step workflow with validation checkpoints.

Suggestions

Consolidate redundant bullets in Function Design and Commenting (e.g., merge the multiple extraction/early-return rules into a single decision rule) to tighten conciseness.

For the Refactoring section, present the safe-refactoring steps as an explicit numbered sequence with a validation feedback loop (change -> run tests -> fix -> re-run) to raise workflow clarity.

Consider moving the longer qualified bullets (e.g., Design Convergence, Reference Representativeness IF/THEN block) into a separate reference file so the overview stays scannable.

Dimension	Reasoning	Score
Conciseness	The body is mostly terse bullet directives that assume Claude's competence, but several sections repeat near-identical guidance (e.g., multiple extraction/early-return bullets across Function Design) and some bullets are heavily qualified, so it could be tightened.	3 / 5
Actionability	Directives are concrete and specific ("Use parameterized queries (prepared statements) for all database access", "Store credentials and secrets through environment variables or dedicated secret managers", "Profile before optimizing"), giving mostly actionable guidance for an instruction-only skill with only minor abstract gaps.	4 / 5
Workflow Clarity	The skill is a principles reference rather than a sequenced workflow; the Refactoring section offers a loose sequence with a validation checkpoint ("Run tests after each change"), but there is no dominant multi-step process with explicit checkpoints.	3 / 5
Progressive Disclosure	Content is organized into clearly headed sections and offloads detail to one real, clearly-signaled one-level reference ("see `references/security-checks.md`", which exists), with only minor inline bulk that could arguably split further.	4 / 5
	Total	14 / 20 Passed

Description

50%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 clearly states both purpose and trigger conditions in third person, but is held back by abstract capability language and broad scope that risks overlapping with other coding skills. Adding concrete actions and sharper trigger synonyms would lift the weaker dimensions.

Suggestions

Replace abstract quality nouns with concrete actions the skill performs (e.g., 'Applies maintainability heuristics such as extracting single-responsibility functions, removing dead code, and injecting dependencies').

Broaden trigger phrases with natural synonyms users say (e.g., 'cleaning up code', 'reducing coupling', 'code review', 'tech debt') to improve trigger term coverage.

Narrow distinctiveness by scoping the trigger to principle/guidance contexts (e.g., 'Use when deciding how to structure or review code quality, not when executing a specific framework task') to reduce overlap with tool-specific skills.

Dimension	Reasoning	Score
Specificity	The description names the domain ("coding principles for maintainability, readability, and quality") but states abstract qualities/outcomes rather than concrete actions, matching the 'names the domain but actions are minimal or generic' anchor.	2 / 5
Completeness	It explicitly answers both what (language-agnostic coding principles for maintainability/readability/quality) and when ("Use when implementing features, refactoring code, or reviewing code quality"), with the 'when' concrete but slightly general rather than maximally specific.	4 / 5
Trigger Term Quality	"implementing features, refactoring code, or reviewing code quality" are reasonably natural trigger phrases, but coverage lacks common synonyms or variations, fitting the 'some relevant keywords but missing common variations' anchor.	3 / 5
Distinctiveness Conflict Risk	General language-agnostic coding principles apply to virtually all coding tasks, creating high overlap risk with many related skills, matching the 'very broad; high overlap risk' anchor.	2 / 5
	Total	11 / 20 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: shinpr/claude-code-workflows
Path: skills/coding-principles/SKILL.md
Commit: 83cf695

Reviewed: 1 day 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.