code-with-best-practices

name

code-with-best-practices

description

This skill should be used when planning, writing, or reviewing code in TypeScript, JavaScript, Python, Go, Rust, SQL, or Bash, or when working with React, Node.js, Vitest, Playwright, Terraform, AWS CDK, pandas, NumPy, polars, marimo, or Jupyter notebooks. It applies to any implementation work in these stacks even when the user never says "best practices", and when the user says "add retries", "make this resilient", "handle upstream failures", "add timeouts", or "add a circuit breaker". It should not be used for API contract or database schema design (use spec) or UI visual design (use design).

Purpose

Consolidated entry point for language and framework best practices. Detect the stack in scope, then load only the reference files the task needs; the practices live in references/ precisely so that unrelated stacks never consume context. Loading every reference defeats the design.

Project discovery (always do first)

1. Detect frameworks and tooling from manifests and configs: package.json dependencies, vitest.config.*, playwright.config.*, cdk.json, *.tf files, go.mod, Cargo.toml, pyproject.toml.
2. Detect the language from the extensions of the files actually being touched.
3. Load references per the routing table below.

Routing table

Context	Load
React component or app work	React + TypeScript or JavaScript by file type
Node.js service, CLI, or module work	Node + TypeScript or JavaScript
Vitest unit or integration tests	Vitest + TypeScript or JavaScript
Playwright E2E tests	Playwright + TypeScript or JavaScript
AWS CDK infrastructure	CDK + TypeScript
Terraform infrastructure	Terraform
TypeScript, no framework match	TypeScript
JavaScript, no framework match	JavaScript
Python	Python
Go	Go
Rust	Rust
SQL queries or migrations	SQL
Bash or shell scripts	Bash
pandas data work	pandas + Python
NumPy numerical code	NumPy + Python
polars data work	polars + Python
marimo notebooks	marimo + Python
Resilience and fault-tolerance work (retries, timeouts, idempotency, circuit breakers, fallbacks, queue consumers, health checks)	Resilience + the language reference for the files touched
Jupyter notebooks	Jupyter + Python

Loading rules

1. When a framework applies, load its framework reference first, then exactly one language reference for the files being edited.
2. For mixed-language changes, load one language reference per touched language.
3. Never load references "just in case"; an unloaded reference costs nothing, an unused loaded one crowds out the task.

Precedence and boundaries

• On conflict, the project's own documented conventions win, then the global CLAUDE.md rules, then these references. A reference here never justifies diff noise in a codebase that does it differently.
• The SQL reference covers writing queries and migrations; designing tables, keys, and indexes belongs to the spec skill (schema reference).
• Endpoint and schema contracts belong to the spec skill (api reference); these references inform the implementation behind the contract.
• This skill informs how code is written, not the workflow around it: test-first discipline is follow-tdd, behavior-preserving cleanup is refactor, debugging is fix.