Coding Conventions Skill

Overview

This skill centralizes general coding conventions and best practices that apply across multiple technologies and frameworks. It covers code organization, documentation, naming, and type import strategies.

Objective

Ensure consistent coding practices across the codebase regardless of technology stack. This skill delegates technology-specific conventions to their respective skills (e.g., TypeScript, React, MUI).

When to Use

Use this skill when:

• Establishing general code organization patterns

• Defining naming conventions across technologies

• Setting up documentation standards

• Creating project structure guidelines

• Reviewing code for general best practices

Don't use this skill for:

• Technology-specific patterns (use typescript, react, etc.)

• Accessibility rules (use a11y skill)

• Framework-specific conventions (use framework skill)

• Architecture patterns (use architecture-patterns when project already uses SOLID, Clean Architecture, DDD)

Scope Rule

conventions covers what applies to ALL/MOST technologies. If a convention is specific to one technology (e.g., React hooks rules, TypeScript generics), it belongs in that technology's skill.

Skills That Build on conventions

This skill is a dependency for 40+ skills. Technology skills extend these conventions with their own specifics:

• typescript → Adds strict typing, generics, utility types

• react → Adds component naming, hook rules, JSX patterns

• nodejs → Adds module patterns, error handling, async patterns

• code-quality → Adds linting/formatting tool configuration

• architecture-patterns → Adds layer organization, SOLID, DIP

Critical Patterns

✅ REQUIRED: Consistent Naming Conventions

// ✅ CORRECT: Proper naming by type const userId = 123; // camelCase for variables function getUserData() {} // camelCase for functions class UserService {} // PascalCase for classes const MAX_RETRY_COUNT = 3; // UPPER_SNAKE_CASE for constants

// ❌ WRONG: Inconsistent naming const UserID = 123; // Wrong case function GetUserData() {} // Wrong case class userService {} // Wrong case const maxRetryCount = 3; // Wrong case for constant

✅ REQUIRED: Group and Organize Imports

// ✅ CORRECT: Grouped imports // External libraries import React from "react"; import { Button } from "@mui/material";

// Internal modules import { UserService } from "./services/UserService"; import { formatDate } from "./utils/date";

// Types import type { User } from "./types";

// ❌ WRONG: Random import order import type { User } from "./types"; import { formatDate } from "./utils/date"; import React from "react"; import { Button } from "@mui/material";

✅ REQUIRED: Single Responsibility Principle

// ✅ CORRECT: Each file has one clear purpose // UserService.ts - handles user operations // UserValidator.ts - validates user data // UserTypes.ts - defines user types

// ❌ WRONG: Everything in one file // utils.ts - contains validation, API calls, formatting, types...

✅ REQUIRED: Named Imports Over Namespace Imports

// ✅ CORRECT: Named imports — explicit, tree-shakeable import { readFileSync, existsSync } from 'fs'; import { join, resolve } from 'path'; import { load, dump } from 'js-yaml';

// ❌ WRONG: Namespace import when only using a few exports import * as fs from 'fs'; import * as path from 'path'; import * as yaml from 'js-yaml';

// ✅ EXCEPTION: Namespace import OK when using many exports (6+) import * as p from '@clack/prompts'; // uses intro, spinner, select, multiselect, confirm, cancel, note, log, outro

✅ REQUIRED: Separate Type Imports

// ✅ CORRECT: import type for type-only imports import { UserService } from './services/UserService'; import type { User, UserRole } from './types';

// ✅ CORRECT: Inline type import when mixing values and types import { Installer, type Model } from '../core/installer';

// ❌ WRONG: Importing types as values (emits unnecessary JS) import { User, UserRole } from './types';

✅ REQUIRED: No Dead Code

// ❌ WRONG: Unused variables, imports, functions import { something } from './lib'; // never used const unused = 42; function neverCalled() {}

// ✅ CORRECT: Every import, variable, and function is used import { needed } from './lib'; const count = needed();

✅ REQUIRED: No any Type

// ❌ WRONG: Disables type safety function process(data: any) { return data.value; } let presetInfo: any = null;

// ✅ CORRECT: Use specific types or unknown function process(data: unknown) { /* narrow with guards */ } let presetInfo: PresetInfo | null = null;

✅ REQUIRED: Avoid Variable Shadowing

// ❌ WRONG: inner p shadows outer import import * as p from '@clack/prompts'; const result = items.find(p => p.id === selected); // shadows p

// ✅ CORRECT: Use distinct names import * as p from '@clack/prompts'; const result = items.find(item => item.id === selected);

✅ REQUIRED: Prefer Static Imports

// ❌ WRONG: Dynamic import/require when static works async function doWork() { const fs = await import('fs'); // unnecessary dynamic import const yaml = require('js-yaml'); // CJS require in TS }

// ✅ CORRECT: Static import at module top import fs from 'fs'; import { load } from 'js-yaml';

Decision Tree

Does this convention apply to ALL/MOST technologies? → Yes: Belongs here (conventions) → No: Belongs in technology-specific skill

Which concern? Naming (variables, functions, classes) → See Naming section Import organization → See Imports section File/folder structure → See Code Organization Documentation standards → See Documentation Type imports (TypeScript) → See Type Imports React-specific (hooks, JSX) → Use react skill Architecture (layers, SOLID) → Use architecture-patterns skill Linting/formatting tools → Use code-quality skill

Quick reference:

• New file? → Check naming (camelCase/PascalCase), place in appropriate directory

• Adding imports? → Group: external → internal → types. Use import type for TS

• Complex logic? → Comment the "why", not "what". Refactor if SRP violated

• Naming unclear? → Descriptive names revealing intent. No custom abbreviations

• Unused code? → Delete it. No dead code

• Variable name conflict? → Rename to avoid shadowing

• <6 exports? → Named imports. 6+ exports? → Namespace import OK

Edge Cases

Abbreviations: Use well-known abbreviations (HTTP, API, URL, ID) but avoid custom ones. userId is OK, usrId is not.

Acronyms in names: Treat as words: HttpService not HTTPService , apiKey not aPIKey .

File naming: Match export name: UserService.ts exports UserService , index.ts for barrel exports.

Boolean naming: Use is , has , should prefixes: isActive , hasPermission , shouldRender .

Callback naming: Use handle or on prefix: handleClick , onSubmit .

Resources

• naming-conventions.md — Boolean prefixes, acronyms, file naming, descriptive names

• import-organization.md — Grouping, named vs namespace, type imports, barrel exports

• code-structure.md — SRP for files, feature vs layer grouping, colocation

• documentation-standards.md — JSDoc, inline comments, README guidelines

See references/README.md for complete navigation.

Related skills: typescript, code-quality, architecture-patterns