CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

aif-best-practices

Code quality guidelines and best practices for writing clean, maintainable code. Covers naming, structure, error handling, testing, and code review standards. Use when writing code, reviewing, refactoring, or asking "how should I name this", "best practice for", "clean code".

Quality

75%

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 ./skills/aif-best-practices/SKILL.md
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 well structured and highly actionable, with concrete code examples, contrast tables, and checklists throughout. Its main weakness is token efficiency: a repetitive, padded skill-context preamble and core sections that restate clean-code fundamentals Claude already knows.

Suggestions

Collapse the 'Shared project skill-context' preamble (currently restated three times across the ordered list, the MANDATORY callout, the precedence bullets, and the enforcement paragraph) into a single short instruction of 5-6 lines.

Trim rules that restate textbook knowledge Claude already has (boolean prefixes, verb+noun naming, single responsibility, AAA pattern) and keep only project-specific or non-obvious guidance, letting the ✅/❌ examples carry the conventions.

Since the skill is ~290 lines covering five distinct modes, consider splitting per-topic detail (naming, structure, errors, testing, review) into references/ files and keeping SKILL.md as the routing overview with one-level-deep, clearly signaled links.

DimensionReasoningScore

Conciseness

The 'Shared project skill-context' preamble repeats the same instruction three ways (the ordered read list, the repeated 'Read .ai-factory/skill-context/aif-best-practices/SKILL.md — MANDATORY', the precedence bullets, and the enforcement paragraph), and the core sections restate basic programming knowledge Claude already has ("Boolean variables: is, has, can prefix", "Max 20-30 lines per function", single responsibility, the AAA pattern). With both padded meta-instructions and textbook restatements, this matches anchor 2 rather than anchor 3 — the format is tight, but the content does not assume Claude's competence.

2 / 5

Actionability

The body provides executable TypeScript/PHP code (calculateDiscount with a guard clause, a UserNotFoundError class, an AAA-pattern test), ✅/❌ contrast tables, a coverage-priority chart, and concrete checklists. Minor abstract rules remain ("Avoid circular dependencies", "Use error boundaries at system edges"), keeping it at anchor 4 rather than 5.

4 / 5

Workflow Clarity

Mode routing is unambiguous (Quick Reference maps each argument to a section), the skill-context reads are an ordered sequence, and there is an explicit post-output verification step ("After generating any output artifact, verify it against all skill-context rules"). As an advisory, read-only skill with no destructive or batch operations, no validation cap applies; small gaps (e.g., the duplicated context-read instruction) hold it at anchor 4.

4 / 5

Progressive Disclosure

No bundle files (references/, scripts/, assets/) exist, and the single-file body is well organized: clear section headers, a Quick Reference navigation, and a summary table, with external file references (.ai-factory/skill-context/..., .ai-factory/ARCHITECTURE.md) explicitly signaled and one level deep. Anchor 4 fits — good structure with minor gaps (the ~290-line body could split per-topic content into reference files, and the skill-context instructions are duplicated) rather than the clean split-and-navigate pattern of anchor 5.

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 covers and gives explicit, natural 'Use when' trigger phrases. Its main weaknesses are topic-style rather than action-style capability listing and overly broad primary triggers that could collide with related coding skills.

DimensionReasoningScore

Specificity

The description lists five specific coverage areas ("Covers naming, structure, error handling, testing, and code review standards") beyond naming the domain, though they are framed as topics rather than concrete actions and "Code quality guidelines and best practices" is generic. This matches anchor 4 (several specific items, minor gaps) — above anchor 3 (only 1-2 concrete actions) but below anchor 5 (comprehensive concrete actions).

4 / 5

Completeness

Both parts are explicit: the what ("Code quality guidelines and best practices... Covers naming, structure, error handling, testing, and code review standards") and the when with concrete trigger phrases ("Use when writing code, reviewing, refactoring, or asking..."). This directly matches anchor 5; the explicit 'Use when...' clause means no cap applies.

5 / 5

Trigger Term Quality

"Use when writing code, reviewing, refactoring, or asking 'how should I name this', 'best practice for', 'clean code'" includes natural phrases users would actually say. It falls short of anchor 5 because common synonyms like "code style", "conventions", or "lint" are missing.

4 / 5

Distinctiveness Conflict Risk

The primary trigger "Use when writing code" is broad enough to overlap with code-review, security, and language-style skills, though "clean code" and "best practice for" carve out a partial niche. This fits anchor 3 (somewhat specific but could still overlap with similar skills) rather than anchor 4, because the broad writing/reviewing triggers create real overlap risk.

3 / 5

Total

16

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

frontmatter_unknown_keys

Unknown frontmatter key(s) found; consider removing or moving to metadata

Warning

Total

15

/

16

Passed

Repository

lee-to/ai-factory

Path

skills/aif-best-practices/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.