Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.
43
43%
Does it follow best practices?
Impact
—
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 broad coding principles rather than specific actions, and the trigger terms are so general ('implementing features', 'refactoring code') that this skill would likely conflict with many other coding-related skills in a large skill library.
Suggestions
Narrow the scope and add specific concrete actions, e.g., 'Enforces naming conventions, reduces function complexity, applies DRY/SOLID principles, structures modules for separation of concerns.'
Make trigger terms more distinctive to reduce conflict risk, e.g., 'Use when the user asks about clean code practices, coding standards, code smells, or wants general (non-language-specific) guidance on code structure and style.'
Differentiate from language-specific or domain-specific coding skills by explicitly stating what this skill covers that others don't, e.g., 'Provides cross-language guidance distinct from language-specific linting or framework conventions.'
| 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' (Use when implementing features, refactoring code, or reviewing code quality) with an explicit 'Use when...' clause. | 3 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'refactoring', 'code quality', 'readability', and 'maintainability' that users might naturally say. However, it misses common variations like 'clean code', 'best practices', 'code review', 'code smell', 'technical debt', 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 language-specific skills, testing skills, architecture skills, or any other development-related skill. | 1 / 3 |
Total | 8 / 12 Passed |
Implementation
27%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 overly verbose collection of software engineering best practices that largely restates knowledge Claude already possesses. While it contains some useful specific thresholds (50-line functions, 3-level nesting max, 0-2 parameters) and the 'Reference Representativeness' section adds genuine value, the majority of content is standard textbook material that wastes context window tokens. The monolithic structure with 15+ sections and no meaningful progressive disclosure makes it poorly suited as a skill file.
Suggestions
Reduce content by 60-70% by removing sections that restate common knowledge (basic error handling, testing philosophy, version control practices, security fundamentals) and focus only on project-specific conventions or non-obvious guidance.
Split the monolithic file into a concise SKILL.md overview (~50 lines) with references to separate files for detailed topics like security-checks.md, refactoring-patterns.md, and reference-representativeness.md.
Replace the single pseudocode example with 2-3 concrete, executable code examples in a common language showing before/after patterns for the most impactful principles.
Add concrete validation steps or checklists that Claude can actually execute (e.g., 'Before submitting: verify no function exceeds 50 lines, no nesting exceeds 3 levels') rather than abstract principles.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~250+ lines, with extensive sections explaining concepts Claude already knows well (SOLID principles, DRY, single responsibility, error handling basics, testing philosophy, version control practices). Much of this is standard software engineering knowledge that doesn't need to be spelled out. The 'Minimum Surface for Required Coverage' principle alone is a dense paragraph that could be a single sentence. Many sections like 'Security Principles' and 'Testing Considerations' restate widely-known best practices. | 1 / 3 |
Actionability | The skill provides some concrete guidance (e.g., '< 50 lines per function', 'max 3 levels of nesting', '0-2 parameters') but is mostly abstract principles rather than executable instructions. The single code example is pseudocode-level ('// Instead of: createUser(name, email, age, city, country) // Use: createUser(userData)'). Most sections describe what to do conceptually rather than providing concrete, copy-paste-ready patterns. | 2 / 3 |
Workflow Clarity | The refactoring section provides a reasonable sequence (small steps, maintain working state, verify behavior), and the 'Reference Representativeness' section uses clear IF/THEN decision logic. However, there are no explicit validation checkpoints or feedback loops for the multi-step processes described. The skill reads more as a reference checklist than a guided workflow. | 2 / 3 |
Progressive Disclosure | The content is a monolithic wall of text with 15+ top-level sections all inline. There is one reference to 'references/security-checks.md' but no bundle files are provided, making it a broken reference. Content like the full security principles, testing considerations, and version control practices could easily be split into separate reference files, with the main skill providing a concise overview. | 1 / 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.
68ecb4a
Table of Contents
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.