Skip to content
Skills Library
Programming · Building & coding

writing-clean-javascript

/writing-clean-javascript

Applies opinionated JavaScript/TypeScript clean-code conventions whenever writing or changing JS/TS code (Node, React, Express, browser, microfrontends). Use for any task that edits .js/.jsx/.ts/.tsx files — implementing features or setups, fixing bugs, creating or changing functions, components, hooks, state stores (Zustand, Redux), routes, services, configs, modules, or tests (Vitest, Jest, Playwright), refactoring or tidying existing code, and reviewing code quality — even if the user doesn't mention clean code or style.

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/lint.sh, scripts/test-config.sh

What it does and when to use it

Applies opinionated JavaScript/TypeScript clean-code conventions whenever writing or changing JS/TS code (Node, React, Express, browser, microfrontends). Use for any task that edits .js/.jsx/.ts/.tsx files — implementing features or setups, fixing bugs, creating or changing functions, components, hooks, state stores (Zustand, Redux), routes, services, configs, modules, or tests (Vitest, Jest, Playwright), refactoring or tidying existing code, and reviewing code quality — even if the user doesn't mention clean code or style.

Original author description

Applies opinionated JavaScript/TypeScript clean-code conventions whenever writing or changing JS/TS code (Node, React, Express, browser, microfrontends). Use for any task that edits .js/.jsx/.ts/.tsx files — implementing features or setups, fixing bugs, creating or changing functions, components, hooks, state stores (Zustand, Redux), routes, services, configs, modules, or tests (Vitest, Jest, Playwright), refactoring or tidying existing code, and reviewing code quality — even if the user doesn't mention clean code or style.

How it works

  1. Workflow
  2. Writing tests
  3. Core rules
  4. Self-review checklist
Original SKILL.md headings · 105 lines, 712 words
SKILL.md preview
---
name: writing-clean-javascript
description: Applies opinionated JavaScript/TypeScript clean-code conventions whenever writing or changing JS/TS code (Node, React, Express, browser, microfrontends). Use for any task that edits .js/.jsx/.ts/.tsx files — implementing features or setups, fixing bugs, creating or changing functions, components, hooks, state stores (Zustand, Redux), routes, services, configs, modules, or tests (Vitest, Jest, Playwright), refactoring or tidying existing code, and reviewing code quality — even if the user doesn't mention clean code or style.
---

# Writing clean JavaScript

Apply these conventions to all JavaScript/TypeScript you write or modify.
They are opinionated; follow them over general defaults.

## Workflow

1. Before writing, check the project's existing style: Biome config
   (`biome.json`/`biome.jsonc`), ESLint config, Prettier config, `tsconfig.json`,
   and neighboring files. If the project's config conflicts with a rule below,
   the project wins — consistency within a codebase matters more than any
   individual rule.
2. Write the code following the core rules below.
3. Self-review against the checklist at the end of this file.
4. Run the linters on the files you changed:
   `bash ${CLAUDE_SKILL_DIR}/scripts/lint.sh <changed files>`
   It runs Biome and/or ESLint, whichever the project is configured for. Fix what
   it reports and re-run until it is clean.

When refactoring, change structure without changing behavior. If behavior must
change, say so explicitly. Keep refactors scoped to what was asked.

## Writing tests

Before writing or editing tests, run from the project root:
`bash ${CLAUDE_SKILL_DIR}/scripts/test-config.sh`
It prints the Vitest/Jest/Playwright config and global setup files. Anything
configured there applies to every test, so **do not repeat it inside test
files** — duplicated setup drifts out of sync and hides what a test is
actually about. In particular, don't repeat:

- Mock resets (`clearMocks`, `mockReset`, `restoreMocks`) → no
  `afterEach(() => vi.clearAllMocks())` / `jest.restoreAllMocks()`.
- Setup-file work: `@testing-library/jest-dom` imports, MSW
  `server.listen/resetHandlers/close`, RTL `cleanup()`, polyfills.
- `environment` / `testEnvironment` → no per-file `@vitest-environment` or
  `@jest-environment` docblocks that match the default.
- `globals: true` → follow the existing tests on whether to import
  `describe/it/expect`; don't mix styles.
- `testTimeout`, fake-timer config, `unstubGlobals`/`unstubEnvs`.
- Path aliases (`resolve.alias`, `moduleNameMapper`) → use the alias, not long
  relative imports.
- Playwright `use.baseURL` → `page.goto('/path')`, not full URLs;
  `storageState`/global setup auth → don't log in inside each test; don't
  override `retries`, `timeout`, or `viewport` per test without a reason.

Only add per-test setup for things that are genuinely specific to that test.
See `references/conventions.md` section 7 for test style rules.

## Core rules

**Variables**: `const` by default; `let` only when reassigned; never `var`.

**Control flow**: Use guard clauses and early returns instead of nested
`if/else`. Max nesting depth of 2 — deeper nesting hides the main path. No
nested ternaries; readers misparse them.

**Functions**: One job per function, roughly 30 lines max. More than 3
parameters → take a single options object so call sites are self-describing.
Prefer pure functions; push side effects (I/O, DOM, network) to the edges.

**Async**: `async/await` over `.then()` chains. Never leave a promise floating —
await it or handle it explicitly. Run independent work with `Promise.all`
instead of sequential awaits.

**Errors**: Never write an empty `catch`. Either handle the error meaningfully,
add context and rethrow (`throw new Error('Failed to load user', { cause: err })`),
or let it propagate. Throw `Error` objects, never strings.

**Naming**: Booleans read as questions (`isActive`, `hasAccess`, `canEdit`).
Functions are verbs (`fetchUsers`, `formatPrice`). Avoid abbreviations except
widely known ones (`id`, `url`, `db`). Magic numbers and strings become named
`UPPER_SNAKE_CASE` constants.

**Data**: Don't mutate function arguments or shared state; return new values
(spread, `map`, `filter`, `structuredClone`). Use optional chaining (`?.`) and
nullish coalescing (`??`) instead of long `&&` chains or `||` defaults that
break on `0` and `''`.

**Modules**: Named exports, not default exports — they keep names consistent
across imports and make refactoring safer. One main concern per file.

**Comments**: Explain *why*, not *what*. Delete commented-out code; git keeps
history.

For detailed rules on arrays, React, TypeScript, Node/Express, and testing,
read `references/conventions.md`. For before/after examples of these rules,
read `references/examples.md`. For design-level problems to avoid (duplicated
code, feature envy, speculative generality, prop drilling, and others), read
`references/code-smells.md` — these are judgement calls, not firm rules.

## Self-review checklist

- [ ] No `var`; `let` only where reassigned
- [ ] No nesting deeper than 2; no nested ternaries
- [ ] No function over ~30 lines or with more than 3 positional parameters
- [ ] No floating promises; independent awaits use `Promise.all`
- [ ] No empty `catch` blocks; only `Error` objects thrown
- [ ] No magic numbers/strings; names are descriptive
- [ ] No mutated arguments
- [ ] Named exports only
- [ ] Tests don't repeat anything from the test config or setup files
- [ ] Linters pass (or none were configured and you said so)
Files in this package (6)
  • SKILL.md 5 KB
  • references/code-smells.md 5 KB
  • references/conventions.md 4 KB
  • references/examples.md 3 KB
  • scripts/lint.sh 2 KB
  • scripts/test-config.sh 2 KB

Versions

The database has no other skills named writing-clean-javascript.

Database snapshot: 13.11.2026 · package version a92eee286e9c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100sota-javascript-typescript
    State-of-the-art JavaScript and TypeScript engineering (2026) for both writing and auditing code. Covers strict TypeScript configuration and type design, language idioms and pitfalls, async patterns, Node.js backends, JS/TS-specific security (XSS, prototype pollution, supply…
  • 100javascript-testing
    Write and run JavaScript/TypeScript tests using Vitest or Jest with mocking, component testing, and coverage. Use when writing JS/TS tests, testing Svelte/React components, or setting up test configuration.
  • 100typescript
    Idiomatic programming style, patterns, and conventions for TypeScript and JavaScript development. Trigger when: - Writing, refactoring, reviewing, or debugging TypeScript or JavaScript code. - Files matching the patterns **/*.ts, **/*.tsx, **/*.js, **/*.jsx, package.json are in…
  • 100js-google
    JavaScript style and best practices based on Google's official JavaScript Style Guide. This skill should be used when writing, reviewing, or refactoring JavaScript code to ensure consistent style and prevent common bugs. Triggers on tasks involving JavaScript, ES6, modules,…
  • 100javascript-typescript
    Professional JavaScript and TypeScript development skill covering modern ES6+, TypeScript, Node.js, Express, React, testing frameworks, and best practices. Use this skill when developing JavaScript/TypeScript applications, building React/Node.js projects, implementing RESTful…
  • 100javascript
    Guides JavaScript and TypeScript development with modern tooling and patterns. ALWAYS trigger on "typescript", "javascript", "tsconfig", "eslint", "prettier", "vitest", "jest", "react", "node.js", "express", "npm", "package.json", "type error", "ts error", "js project setup",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.