aiready-best-practices_skill

Overview

This skill provides concise guidelines for writing AI-friendly JavaScript that AI coding assistants can understand and maintain. It detects semantic duplicates, interface fragmentation, and naming inconsistencies to reduce wasted context and improve assistant suggestions. Use it to guide new code, PR reviews, refactors, and debugging when AI helpers get confused.

How this skill works

The skill inspects code structure, naming, imports, and documentation to surface patterns that confuse models. It flags semantic duplicates, overly deep import chains, inconsistent names, fragmented interfaces, and documentation gaps. For each finding it recommends focused, minimal changes that reduce context size and improve cohesion. Rules are modular so only relevant checks run when needed.

When to use it

• When writing new features to ensure AI-friendly patterns from the start
• During pull request reviews to catch AI-unfriendly code before merging
• While refactoring to consolidate duplicates and unify interfaces
• When debugging assistant confusion or incorrect suggestions
• Before adopting AI tooling to prepare codebase structure and docs

Best practices

• Consolidate semantic duplicates into a single implementation to avoid model conflict
• Keep import depth shallow (aim for ≤3 levels) and group related functionality
• Use consistent naming conventions across modules and APIs
• Split oversized files and unify fragmented interfaces to improve cohesion
• Document non-obvious AI context needs and keep docs synced with code

Example use cases

• A PR reviewer runs checks to find duplicate helper functions and merges them
• Refactoring a service library to reduce import depth and improve autocomplete
• Fixing inconsistent error handling so the assistant produces uniform patches
• Preparing a legacy repo for AI-assisted development by consolidating interfaces
• Running checks before a demo so the assistant’s suggestions are accurate