coding-principles
Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.
52
40%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/coding-principles/SKILL.mdQuality
Discovery
59%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 has good structural completeness with an explicit 'Use when' clause, but suffers from being too generic and abstract for effective skill selection. The capabilities described are high-level principles rather than concrete actions, and the trigger terms are so broad ('implementing features', 'reviewing code') that this skill would likely conflict with many other coding-related skills in a large skill library.
Suggestions
Narrow the distinctiveness by specifying what unique principles or patterns this skill covers, e.g., 'Applies SOLID principles, DRY/KISS guidelines, naming conventions, and function decomposition strategies'
Add more specific trigger terms that distinguish this from language-specific skills, e.g., 'Use when asking about clean code practices, reducing complexity, naming conventions, code smells, or general best practices independent of programming language'
List concrete actions instead of abstract qualities, e.g., 'Identifies code smells, suggests refactoring patterns, enforces consistent naming, reduces function complexity' rather than 'coding principles for maintainability, readability, and quality'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (coding principles) and some qualities (maintainability, readability, quality), but does not list specific concrete actions like 'enforce naming conventions, reduce cyclomatic complexity, apply SOLID principles.' The actions mentioned (implementing, refactoring, reviewing) are in the trigger clause rather than capability descriptions. | 2 / 3 |
Completeness | Clearly answers both 'what' (language-agnostic coding principles for maintainability, readability, and quality) and 'when' (implementing features, refactoring code, or reviewing code quality) with an explicit 'Use when...' clause. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'refactoring', 'code quality', 'implementing features', and 'reviewing code' that users might naturally say. However, it misses common variations like 'clean code', 'best practices', 'code smell', 'technical debt', 'code style', or 'coding standards'. | 2 / 3 |
Distinctiveness Conflict Risk | Very generic and would likely conflict with many other coding-related skills. 'Implementing features' and 'reviewing code' are extremely broad triggers that could overlap with virtually any language-specific skill, testing skill, or architecture skill. | 1 / 3 |
Total | 8 / 12 Passed |
Implementation
20%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a comprehensive but generic restatement of widely-known software engineering best practices that Claude already understands. It consumes significant token budget without providing novel, project-specific, or actionable guidance. The content would be far more valuable if it were reduced to only project-specific conventions and constraints that differ from standard practice, with concrete examples and executable code.
Suggestions
Remove or drastically reduce sections covering universal principles Claude already knows (SOLID, DRY, YAGNI, single responsibility, etc.) and focus only on project-specific conventions or non-obvious constraints.
Add concrete, executable code examples in at least one target language for key patterns like dependency injection, error handling, and parameterized queries — the current pseudocode snippet is insufficient.
Convert abstract advice ('Use language-appropriate error handling mechanisms') into specific, actionable rules with examples of correct and incorrect patterns.
Split the monolithic content into a concise overview SKILL.md with references to detailed files (e.g., security-principles.md, refactoring-guide.md) to improve progressive disclosure and reduce token consumption.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This is extremely verbose and largely restates well-known software engineering principles that Claude already knows (YAGNI, SOLID, DRY, single responsibility, early returns, etc.). Very little here is novel or project-specific — it reads like a textbook summary rather than a skill that adds information Claude doesn't already possess. | 1 / 3 |
Actionability | The content is almost entirely abstract guidance with no executable code, no concrete commands, and no specific examples beyond one pseudocode snippet for parameter grouping. Statements like 'Use language-appropriate error handling mechanisms' and 'Choose based on access patterns' are vague directions, not actionable instructions. | 1 / 3 |
Workflow Clarity | The refactoring section provides a reasonable sequence (small steps, maintain working state, verify behavior), and there are some logical groupings. However, most sections are unordered bullet lists without clear sequencing or validation checkpoints, and there are no feedback loops for error recovery. | 2 / 3 |
Progressive Disclosure | The content is organized into clear sections with headers, which aids navigation. However, it's a monolithic wall of text (~200 lines) that could benefit from splitting detailed sections (security, testing, etc.) into separate reference files. Only one external reference exists (references/security-checks.md). | 2 / 3 |
Total | 6 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- shinpr/claude-code-workflows
- Commit
2e719be
- 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.