CtrlK
BlogDocsLog inGet started
Tessl Logo

ai-development-guide

Technical decision criteria, anti-pattern detection, debugging techniques, and quality check workflow. Use when making technical decisions, detecting code smells, or performing quality assurance.

55

Quality

61%

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/ai-development-guide/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 broad and abstract. It tries to cover too many domains (decision-making, anti-patterns, debugging, QA) without being specific about concrete actions, making it both hard to distinguish from other skills and unlikely to be the clear best match for any particular user request.

Suggestions

Narrow the scope or clearly delineate sub-capabilities — e.g., instead of 'technical decision criteria', specify 'evaluate trade-offs between architectural approaches using decision matrices'.

Add more natural trigger terms users would actually say, such as 'code review', 'refactor', 'tech debt', 'best practices', 'architecture decision', 'performance issue'.

Improve distinctiveness by focusing on what makes this skill unique compared to general coding or debugging skills — e.g., is this specifically about a quality check workflow or checklist?

DimensionReasoningScore

Specificity

Names a domain (technical decisions, debugging, quality) and lists some actions (anti-pattern detection, debugging techniques, quality check workflow), but these are still fairly abstract categories rather than concrete specific actions like 'extract text from PDF' or 'generate commit messages'.

2 / 3

Completeness

Clearly answers both 'what' (technical decision criteria, anti-pattern detection, debugging techniques, quality check workflow) and 'when' with an explicit 'Use when' clause specifying trigger scenarios (making technical decisions, detecting code smells, performing quality assurance).

3 / 3

Trigger Term Quality

Includes some relevant terms like 'code smells', 'quality assurance', 'debugging', and 'technical decisions' that users might say, but misses many natural variations (e.g., 'code review', 'refactor', 'best practices', 'architecture decision', 'tech debt', 'lint').

2 / 3

Distinctiveness Conflict Risk

Very broad scope covering technical decisions, debugging, and quality assurance — three areas that could easily overlap with many other skills such as code review skills, debugging-specific skills, architecture skills, or general coding assistance skills.

1 / 3

Total

8

/

12

Passed

Implementation

62%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill provides a comprehensive collection of technical decision criteria, anti-patterns, and quality workflows that are well-structured and logically organized. Its main strengths are clear workflow sequencing with validation checkpoints and useful decision frameworks (Rule of Three table, code modification decision tree). Its weaknesses are moderate verbosity explaining concepts Claude already knows, reliance on pseudocode rather than executable examples, and a monolithic structure that would benefit from splitting into referenced sub-files.

Suggestions

Replace pseudocode blocks with concrete, executable examples in at least one language (e.g., Python or TypeScript) for the error handling pattern and Rule of Three example, or explicitly justify the generic approach more concisely.

Split the document into a concise overview SKILL.md with references to separate files like ANTI-PATTERNS.md, DEBUGGING.md, QUALITY-WORKFLOW.md, and IMPACT-ANALYSIS.md to improve progressive disclosure.

Remove explanations of well-known concepts Claude already understands (e.g., what SRP means, what DRY stands for, basic stack trace reading) and focus on the specific decision criteria and thresholds that are unique to this skill.

DimensionReasoningScore

Conciseness

The skill is moderately efficient but includes some content Claude already knows well (e.g., explaining what SRP is, what DRY means, basic debugging concepts like reading stack traces). Several sections could be tightened—for instance, the 'Common Failure Patterns' section explains concepts like 'start with failing tests' and '5 Whys' that are well-known. However, the structured tables, decision trees, and patterns do add value beyond basic knowledge.

2 / 3

Actionability

The skill provides structured guidance with decision criteria, tables, and pseudocode patterns, but lacks fully executable code examples. Code blocks use generic pseudocode (e.g., '<handle error>', '<propagate error>') rather than concrete, copy-paste-ready implementations. The quality check workflow lists phases but doesn't provide specific commands. The impact analysis template is concrete and useful, but many other sections remain at the 'describe rather than instruct' level.

2 / 3

Workflow Clarity

Multi-step processes are clearly sequenced with explicit validation checkpoints. The Quality Check Workflow has clear phases with a final quality gate. The Impact Analysis has a mandatory 3-stage process with a 'do not implement until documented' checkpoint. The error handling section includes review triggers and a 'before implementing any fallback' checklist. The existing code modification section uses a clear decision tree.

3 / 3

Progressive Disclosure

The content is well-organized with clear headers and logical sections, but it's a monolithic document (~300 lines) with no references to external files. Several sections (e.g., the full Quality Check Workflow, the Impact Analysis template, the Debugging Techniques) could be split into separate reference files to keep the main SKILL.md as a concise overview. Without bundle files, everything is inline.

2 / 3

Total

9

/

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.