Clean Code JavaScript Skills

A collection of skills for AI-assisted JavaScript development based on the principles from Clean Code JavaScript.

These skills provide coding agents such as Claude, Gemini, OpenCode, Cursor, Copilot, and others with procedural knowledge, patterns, and concrete examples for writing clean, maintainable, and intention-revealing JavaScript code.

The focus is not on syntax, but on how to structure code, name things, design functions, and organize modules in real-world projects.

---

Installation

Install all skills from this repository:

npx skills add damianwrooby/javascript-clean-code-skills

Or install individual skills:

npx skills add damianwrooby/javascript-clean-code-skills/skills/clean-codejs-naming
npx skills add damianwrooby/javascript-clean-code-skills/skills/clean-codejs-functions
npx skills add damianwrooby/javascript-clean-code-skills/skills/clean-codejs-modules
npx skills add damianwrooby/javascript-clean-code-skills/skills/clean-codejs-comments
npx skills add damianwrooby/javascript-clean-code-skills/skills/clean-codejs-objects

Give the GitHub repo a ⭐️ if you find it useful!

---

Available Skills

Skill	Description
clean-codejs-naming	Naming patterns for variables, functions, constants, and booleans with intention-revealing names
clean-codejs-functions	Function design patterns: single responsibility, size limits, parameter objects, and side-effect control
clean-codejs-modules	File and module organization, export patterns, and separation of concerns
clean-codejs-comments	Commenting guidelines focused on explaining why, not what
clean-codejs-objects	Object and class design patterns: encapsulation, immutability, and cohesion

---

Skill Structure

Each skill follows the standard Skills.sh structure:

skills/
└── clean-codejs-{name}/
    └── SKILL.md   # Skill definition with patterns, explanations, and examples

Each SKILL.md contains:

• YAML front-matter (name, description)
• Pattern-based sections
• ❌ Bad vs ✅ Good examples
• Guidance designed for direct application by AI agents

---

JavaScript Scope & Assumptions

These skills target modern JavaScript with the following assumptions:

• ES2019+ syntax
• Works for frontend and backend JavaScript
• Framework-agnostic (usable with React, Vue, Angular, Svelte, Node.js, etc.)
• Emphasis on behavior-preserving refactors
• No reliance on TypeScript (but compatible with it)

---

Key Patterns

Naming

// ❌ Bad
const d = 86400000;

// ✅ Good
const MILLISECONDS_PER_DAY = 86400000;

// ❌ Bad
function getUser(u) {}

// ✅ Good
function fetchUserById(userId) {}

Functions

// ❌ Bad
function handleUser(user) {
  saveUser(user);
  sendEmail(user);
}

// ✅ Good
function saveUser(user) {}
function notifyUser(user) {}

// ❌ Bad
function createUser(name, age, city, zip) {}

// ✅ Good
function createUser({ name, age, address }) {}

Modules

// ❌ Bad
// user.js
export function createUser() {}
export function connectToDb() {}

// ✅ Good
// user.service.js
export function createUser() {}

/users
  user.service.js
  user.repository.js
  user.controller.js

Comments

// ❌ Bad
// Increment i by 1
i++;

// ✅ Good
// Retry once to handle flaky network conditions
retryRequest();

Objects & Classes

// ❌ Bad
user.name = 'John';

// ✅ Good
user.rename('John');

// ❌ Bad
class User {
  calculateTax() {}
}

// ✅ Good
class TaxCalculator {
  calculate(user) {}
}

---

Contributing

Contributions are very welcome! Please ensure that additions:

• Follow Clean Code JavaScript principles
• Focus on patterns, not just rules
• Include Bad vs Good examples
• Preserve behavior (no breaking refactors)
• Avoid framework-specific assumptions unless clearly stated

---

Resources

• Clean Code JavaScript
• Skills.sh

---

License

MIT