CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

ai-development-guide

Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and frontend code. Use when implementing, reviewing, or diagnosing code, code smells, failures, or implementation completeness.

Quality

76%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./dev-skills/skills/ai-development-guide/SKILL.md

The canonical home for this skill is ai-development-guide in shinpr/claude-code-workflows

SKILL.md
Quality
Evals
Security

Quality

Content

60%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 dense, well-organized policy collection with genuinely useful, non-generic decision criteria and one properly structured reference file. Its weaknesses are token efficiency and actionability: known-concept restatements (SRP, DRY, YAGNI, 5 Whys), abstract principle prose, and pseudocode templates instead of concrete examples keep several sections from being immediately executable.

Suggestions

Cut or compress restatements of concepts Claude already knows — the SRP/DRY annotations on the anti-pattern list, "Should use version control", "Be conscious of YAGNI", and the 5 Whys reference — to pure one-line trigger entries, saving tokens for the non-obvious policy.

Replace abstract principle prose (e.g., "Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state...") with a short concrete example or decision checklist showing the judgment applied to a real choice.

Offload the fail-fast fallback design detail and the expanded impact-analysis report template into reference files like references/frontend.md, and add an explicit fix-and-rerun loop to the Quality Check Workflow for failed checks.

DimensionReasoningScore

Conciseness

Much of the body is genuinely non-obvious policy (boundary contracts, fallback acceptance criteria, scope rules), but several sections restate concepts Claude already knows — "Violates Single Responsibility Principle (SRP)", "Violates DRY principle", "Should use version control", "Be conscious of YAGNI", "Identify root cause with 5 Whys", "Measure before optimizing" — and phrasing like "Inspect until the evidence identifies the lowest-total-complexity solution that delivers the required user, operator, or maintainer value" could be tightened. This fits the 3 anchor (mostly efficient, some unnecessary explanation) better than 4, where only minor trimming would be needed.

3 / 5

Actionability

There are concrete, executable pieces — the four-step fallback checklist ("Identify the accepted requirement... Document the business justification..."), the 3-stage impact analysis with a report template, and the existing-code-modification decision tree. However, sizable portions are abstract principle ("Judge total complexity across every activated surface: user decisions, settings, modes, concepts, outputs, persistent state..."), and the code blocks are explicitly pseudocode templates ("<handle error>: return DEFAULT_VALUE") rather than executable examples; the quality workflow also names check categories without any example commands. This lands on the 3 anchor (some concrete guidance but incomplete, pseudocode rather than executable) rather than 4.

3 / 5

Workflow Clarity

The impact analysis is a clearly sequenced 3-stage process (Discovery → Understanding → Identification) with an explicit proceed checkpoint ("Proceed when discovery and understanding cover the accepted outcome..."), and the quality workflow orders static → build → behavior checks with a completion gate ("Completion requires every applicable configured check to pass"). It stops short of 5 because the quality workflow lacks an explicit fix-and-rerun feedback loop when a check fails, and the unused-code deletion flow's "callers and generated/operational uses are checked" is left implicit as to how.

4 / 5

Progressive Disclosure

Scored against the actual bundle: one real, clearly signaled, one-level-deep reference — "[references/frontend.md](references/frontend.md): read when implementing, reviewing, fixing, or diagnosing frontend code" — with an explicit read condition, and the body is well-sectioned with descriptive headers. It is not a 5 because the ~250-line body inlines substantial detail sections (the full fail-fast fallback design and the expanded impact-analysis report format) that could be offloaded the way frontend criteria were, leaving SKILL.md closer to an overview.

4 / 5

Total

14

/

20

Passed

Description

80%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.

A strong description that clearly states what the skill does and gives explicit, natural-language trigger guidance in third person. Its main weakness is breadth: the trigger clause covers almost all coding work, so it risks firing in situations where a more specialized skill applies.

DimensionReasoningScore

Specificity

The description lists several concrete capability areas — "technical decision criteria, anti-pattern detection, debugging, and quality gates" — scoped to "backend and frontend code", matching the anchor for several specific actions with minor gaps (e.g., impact analysis and completeness assurance are only partially surfaced via "implementation completeness"). It is not a 5 because the actions are capability categories rather than the fully comprehensive, fine-grained action list of the top anchor.

4 / 5

Completeness

It explicitly answers both questions: the "what" ("Applies technical decision criteria, anti-pattern detection, debugging, and quality gates for backend and frontend code") and a concrete "when" clause ("Use when implementing, reviewing, or diagnosing code, code smells, failures, or implementation completeness"). This mirrors the top anchor's structure of clear what plus explicit trigger phrases, so the 4 anchor ("when could be more explicit") does not fit.

5 / 5

Trigger Term Quality

"Use when implementing, reviewing, or diagnosing code, code smells, failures" provides good natural-phrase coverage a user would actually say. It falls short of the 5 anchor because common variations like "debugging", "bugs", "refactoring", or specific stack terms (e.g., React, TypeScript) are missing.

4 / 5

Distinctiveness Conflict Risk

The skill has a discernible niche (engineering decision criteria, anti-patterns, quality gates), but its triggers — "implementing, reviewing, or diagnosing code" — fire on nearly any coding task, creating real overlap risk with general code-review, refactoring, and debugging skills. It is more distinctive than the very-broad 2 anchor yet noticeably short of the 4 anchor's "minor overlap risk with closely related skills".

3 / 5

Total

16

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

shinpr/claude-code-workflows

Path

dev-skills/skills/ai-development-guide/SKILL.md

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.