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

79%

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

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

A well-organized, highly actionable best-practices reference with strong concrete examples and useful checklists. Its main weakness is a verbose, repetitive skill-context enforcement preamble that inflates the token budget without proportional value.

Suggestions

Compress the skill-context preamble (lines 13-33): collapse the repeated 'MANDATORY'/'CRITICAL' emphasis into a single concise statement that skill-context rules override these defaults and must be verified before output.

Move the longer good/bad code comparison blocks (e.g., naming and structure tables) into a references/ file and keep only one representative example per section in SKILL.md to reduce inline bulk.

Add a one-line 'How to use this guide' workflow at the top (identify area → apply rules → run review checklist → verify against skill-context) so the application sequence is explicit rather than implied.

Dimension	Reasoning	Score
Conciseness	The core best-practices sections are lean and example-driven, but the skill-context preamble ('MANDATORY', 'CRITICAL', repeated enforcement paragraphs) is noticeably verbose and could be tightened; mostly efficient with some padding.	3 / 5
Actionability	Concrete, copy-paste-ready good/bad code examples in TypeScript and PHP, explicit rule lists, and a reviewer checklist provide fully actionable guidance covering the common cases.	5 / 5
Workflow Clarity	Clear section organization with a review checklist supplying validation checkpoints and an explicit enforcement feedback loop ('verify against skill-context rules ... fix the output before presenting'); not a fragile multi-step process, so no deeper validation is required.	4 / 5
Progressive Disclosure	Well-organized into clearly headed sections (Naming, Structure, Errors, Testing, Review) with a Quick Reference and one-level-deep, clearly signaled external references (skill-context SKILL.md, ARCHITECTURE.md); no bundle files exist, so content stays reasonably inline with minor organization gaps.	4 / 5
	Total	16 / 20 Passed

Description

83%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, well-structured description that clearly states what the skill covers and when to invoke it, using natural user-language trigger phrases. It is mostly distinct from sibling skills with only minor overlap risk.

Dimension	Reasoning	Score
Specificity	Names the domain and enumerates concrete coverage areas ('naming, structure, error handling, testing, and code review standards') — several specific topics with only minor gaps, though framed as topic areas rather than discrete executable actions.	4 / 5
Completeness	Explicitly answers both 'what' (guidelines/best practices covering named areas) and 'when' with concrete trigger phrases ('Use when writing code, reviewing, refactoring, or asking ...'), matching the anchor 5 pattern.	5 / 5
Trigger Term Quality	Natural trigger phrases are present and quotable ('writing code, reviewing, refactoring', 'how should I name this', 'best practice for', 'clean code'), giving good keyword coverage; a few synonymous phrasings users might say are missing.	4 / 5
Distinctiveness Conflict Risk	The 'best practices / clean code' framing with naming-and-convention triggers carves a mostly distinct niche; minor overlap risk exists with closely related skills like linting, testing, or the referenced /aif-security-checklist.	4 / 5
	Total	17 / 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: e144f95

Reviewed: 5 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.