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

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/aif-best-practices/SKILL.md

Quality

Content

71%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 highly actionable with concrete, executable examples and specific quantitative rules throughout. Its weaknesses are the padded, repetitive skill-context preamble and a fully inline ~280-line structure with no reference files, which costs both conciseness and progressive disclosure.

Suggestions

Compress the skill-context preamble to 3-4 lines stating the rule once (skill-context overrides this SKILL.md and applies to all outputs) instead of restating it across ~25 lines.

Split the five major topic sections (naming, structure, errors, testing, review) into one-level-deep reference files under references/, keeping SKILL.md as a concise overview with clearly signaled links.

Add an explicit feedback step to the review workflow (e.g., 'after addressing review comments, re-run the reviewer checklist before approving') to close the validation loop.

Dimension	Reasoning	Score
Conciseness	The topic sections are dense and token-efficient (terse good/bad tables, bulleted rules), but the ~25-line skill-context preamble states its override rule repeatedly ('the skill-context rule wins', 'Do NOT ignore skill-context rules', 'CRITICAL... you MUST comply'), which is more than minor padding. This places it at 'mostly efficient but could be tightened' rather than the 'minor instances' anchor.	3 / 5
Actionability	Guidance is fully concrete and executable: complete TypeScript/PHP examples with type declarations, explicit numeric limits ('Max 20-30 lines per function', 'Max 3-4 parameters'), copy-paste test cases, and filled-in good/bad review comment examples covering the common cases. Not below 5 because every section instructs with specifics rather than abstraction.	5 / 5
Workflow Clarity	The review flow is sequenced with checkpoints ('Before Requesting Review' self-check list, then the 'Reviewer Checklist' with correctness/edge-cases/security items). It misses the explicit validate-then-proceed feedback loop of the top anchor — no step tells the reader to re-check after fixes — so it lands at 'clear sequence with most checkpoints; minor validation gaps'.	4 / 5
Progressive Disclosure	No bundle files exist (references/, scripts/, assets/ are absent) and all ~280 lines are inline; the naming, testing, and review sections are each substantial enough to be one-level-deep reference files, and the only external pointer is a conditional '.ai-factory/skill-context' file plus slash-command invocations. Section headers and the Quick Reference give it reasonable structure, matching 'some structure but content that should be separate is inline' rather than the minimal-structure anchor.	3 / 5
	Total	15 / 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 well-constructed description with explicit what-and-when structure and genuinely natural trigger phrases. Its main weakness is breadth: code quality/review territory overlaps with adjacent code-review and testing skills, and a few common trigger synonyms are absent.

Dimension	Reasoning	Score
Specificity	The description lists several concrete coverage areas — 'Covers naming, structure, error handling, testing, and code review standards' — which matches the 'several specific actions; minor gaps' anchor. It falls short of 5 because it names topic areas rather than the fully comprehensive, concrete action list of the top anchor.	4 / 5
Completeness	It clearly answers 'what' ('Code quality guidelines and best practices for writing clean, maintainable code...') and 'when' with an explicit 'Use when' clause containing concrete trigger phrases. Not below 5 because both halves are explicit and specific.	5 / 5
Trigger Term Quality	Explicit natural phrases users would say are quoted directly: '"how should I name this", "best practice for", "clean code"', plus 'writing code, reviewing, refactoring'. A few common variations are missing (e.g., 'code smell', 'linting', 'conventions'), keeping it below the comprehensive-synonyms anchor.	4 / 5
Distinctiveness Conflict Risk	'Code quality guidelines' plus triggers like 'reviewing' and 'testing' overlap significantly with dedicated code-review, linting, and testing skills. It is somewhat specific via naming/best-practice framing but not mostly-distinct, so it sits at the 'could still overlap with similar skills' anchor rather than 4.	3 / 5
	Total	16 / 20 Passed

Validation

93%

Warnings & errors only

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

Criteria	Description	Result
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
Commit: ac92beb

Reviewed: 4 days ago

Table of Contents

Discovery Implementation Validation

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.