CtrlK
BlogDocsLog inGet started
Tessl Logo

coding-principles

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

43

Quality

43%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/coding-principles/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

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.'

DimensionReasoningScore

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.

DimensionReasoningScore

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.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
shinpr/claude-code-workflows
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.