javascript-conventions

javascript-conventions1240 wordsMITRepo-owned

Configure and validate JS/TS tooling conventions. Enforce pnpm, TypeScript, ESLint, and Prettier defaults. Use when working on JS/TS files or package.json.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill javascript-conventions -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /javascript-conventions

Research context (evidence, not authority)

Problem: Configure and validate JS/TS tooling conventions. Enforce pnpm, TypeScript, ESLint, and Prettier defaults. Use when working on JS/TS files or package.json. NOT for Python, backend-only, or shell scripts. Stack / assumptions: portable skill scripts under scripts/; on-demand references; eval fixtures Comparable alternative: A general-purpose agent instruction without a scoped skill contract

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

Repo skill (hand-maintained)

Composed compose-custom-wave-4 from skills/javascript-conventions/SKILL.md with full SKILL disclosure. Do not run wagents docs generate on this file (HAND-MAINTAINED sentinel).

What It Does

Apply these conventions when JavaScript, TypeScript, Node.js tooling, or package.json is the primary workstream.

Note

This is an auto-invoke skill — it activates automatically when the agent detects relevant context. It is not visible in the / slash command menu.

Modes

$ARGUMENTS	Action
Active (auto-invoked when JS/TS work is primary)	Apply the operator contract below
Empty	Display the convention summary and routing guidance
check	Verify tooling compliance only

Critical Rules

1. Require pnpm for JS/TS dependency changes unless references/edge-cases.md justifies npm, yarn, or another manager.
2. Resolve the owning package root before running package commands; do not assume the repository root owns every JS/TS file.
3. Never mix pnpm-lock.yaml, package-lock.json, and yarn.lock in the same package root outside a dedicated migration.
4. Run CI installs with pnpm install --frozen-lockfile when a pnpm-lock.yaml is present.
5. Use pnpm exec for local binaries and pnpm dlx only for one-off packages fetched from the registry.
6. Do not assume Corepack is bundled with the active Node.js runtime; check references/edge-cases.md before recommending Corepack setup.
7. Keep Prettier responsible for formatting and ESLint responsible for code-quality rules.
8. Redirect mixed-language or non-JS-primary work through references/redirection-boundaries.md instead of force-fitting this skill onto the whole task.

Operator Contract

Active

1. Apply this skill only when JS/TS files, Node tooling, or package.json are the primary surface of the task.
2. Read references/redirection-boundaries.md when JS/TS appears alongside Python, shell, CI, or framework-specific work.
3. Enforce the hard requirements in references/tooling-contract.md for package management, package-root selection, command execution, lockfiles, workspaces, and CI installs.
4. Check references/edge-cases.md before recommending npm, yarn, global package managers, Corepack assumptions, or lockfile migrations.
5. Read references/typescript-patterns.md for TypeScript config or type-safety changes.
6. Read references/eslint-prettier.md for linting, typed linting, or formatting changes.
7. Use guided preferences only when starting new work or when the repo does not already have a stronger local convention.

Empty / Help

1. Summarize the hard requirements: pnpm, packageManager, pnpm-lock.yaml, pnpm install --frozen-lockfile, pnpm exec, pnpm dlx, tsc --noEmit, eslint, and prettier.
2. Show the difference between hard requirements and guided preferences.
3. Point to the exact reference files for tooling, exceptions, TypeScript, lint/format, and mixed-language routing.

check

1. Verify JS/TS tooling compliance only; do not widen into implementation advice unless the user asks.
2. Report whether the project uses the expected package root, pnpm, packageManager, pnpm-lock.yaml, workspace config, scripts, tsconfig.json, ESLint flat config, and Prettier.
3. Flag npm/yarn/Corepack/legacy deviations and require the reason to match references/edge-cases.md.
4. Reject recommendations that replace repo-required tooling with npm install, npx, or ad hoc global binaries unless an exception is documented.

Hard Requirements

• Package manager: use pnpm for JS/TS package operations unless an exception is documented.
• Package manager pin: honor the nearest owning package.json and its packageManager field.
• Lockfile: commit pnpm-lock.yaml; never mix lockfiles in one package root without a migration plan.
• Install: use pnpm install; use pnpm install --frozen-lockfile in CI.
• Dependencies: use pnpm add <pkg> or pnpm add -D <pkg> from the owning package root.
• Local binaries: use pnpm exec <cmd>; use pnpm dlx <pkg> only for one-off registry execution.
• Scripts: use pnpm run <script> or pnpm --filter <pkg> run <script>.
• Type checking: use pnpm exec tsc --noEmit or the repo’s package script.
• Linting: use ESLint flat config for new ESLint setup.
• Formatting: use Prettier for formatting and ESLint for code-quality rules.

Guided Preferences

When starting new JS/TS work and no stronger local constraint exists, prefer these tools. These are defaults, not absolute law; check references/edge-cases.md before overriding an established project choice.

Purpose	Tool	Notes
Package manager	pnpm	Pin through packageManager when the package root owns package.json
Bundler	vite or esbuild	Respect framework-owned builders first
Linting	eslint	Use flat config for new setup
Formatting	prettier	Keep formatting separate from linting
Testing	vitest or framework-native runner	Prefer existing repo scripts
Type checking	tsc --noEmit	Run through pnpm exec or package scripts

Typescript Type Safety

1. Step — Prefer unknown over any; do not weaken established strictness to make code compile.

2. Step — Prefer interface for object shapes and type for unions, intersections, and mapped types.

3. Step — Use discriminated unions for state machines and tagged variants.

4. Step — Use as const and satisfies to preserve literal inference without unsafe assertions.

5. Step — Avoid type assertions (as); prefer type guards, assertion functions, and schema validation at boundaries.

6. Step — Enable strict in new TypeScript projects and add stricter options when the repo can absorb them.

7. Step — Test negative type behavior with @ts-expect-error or a type-test tool when type contracts are public.

8. Step — See references/typescript-patterns.md for TSConfig, module-resolution, and narrowing patterns.

Scaling Strategy

• Incidental JS/TS file in a broader non-JS task: enforce only the hard requirements that touch the JS/TS-owned surface, then route mixed-workflow questions through references/redirection-boundaries.md.
• JS/TS-primary feature or refactor work: apply the full operator contract, including tooling, TypeScript, linting, formatting, and test guidance where relevant.
• Repo-wide JS/TS tooling or migration work: use check, references/tooling-contract.md, and references/edge-cases.md to separate hard violations from documented transition paths.

Progressive Disclosure

• Do not load every reference by default.
• Read references/tooling-contract.md first for command, dependency, package-root, workspace, lockfile, or CI questions.
• Read references/redirection-boundaries.md when Python, shell, CI, infra, or framework-specific work is mixed into the request.
• Read references/edge-cases.md only when the task appears to require npm, yarn, Corepack setup, generated app scaffolding, or lockfile migration exceptions.
• Read references/typescript-patterns.md only when TypeScript code, tsconfig.json, public types, or type tests are active.
• Read references/eslint-prettier.md only when the task touches linting, typed linting, or formatting.

Scope Boundaries

IS for: JS/TS tooling conventions, Node package commands, dependency-management rules, TypeScript type-safety defaults, lint/format/test command guidance, and exception-aware repo guidance.

NOT for: Python conventions, shell conventions, CI pipeline design, framework architecture, backend-only implementation strategy, or broad frontend UX/design guidance.

Canonical terms (use these exactly):

• pnpm — the required package manager for JS/TS package operations
• package root — the nearest directory whose package.json owns the command or dependency
• packageManager — the package.json field that pins the package manager and version
• pnpm-lock.yaml — the canonical JS/TS lockfile for pnpm package roots
• workspace — pnpm workspace declared by pnpm-workspace.yaml
• frozen-lockfile — CI install mode that prevents lockfile mutation
• pnpm exec — local project binary execution
• pnpm dlx — one-off package execution from the registry

Validation Contract

Run from this skill directory before declaring changes complete:

python scripts/check.py
git diff --check

Completion criteria:

1. scripts/check.py exits 0.
2. git diff --check exits 0.
3. No portable-CLI violations remain under this skill directory.

After changing skill definitions, public descriptions, reference files, or eval behavior, invoke docs-steward if available.

Public Metadata

Field	Value
Source Type	repo-owned
Display Source	github:wyattowalsh/agents
Source Kind	repo
Installability	portable command
Review State	reviewed
Target Agents	antigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, grok, opencode

General

Field	Value
Name	javascript-conventions
License	MIT
Version	1.0.0
Author	wyattowalsh

Claude Code

Field	Value
User Invocable	No

Related Skills

python-conventions Enforce Python tooling conventions for uv, ty, Ruff, pytest, and pyproject.toml. Use when working on .py files or Python project config.

View Full SKILL.md

SKILL.md

---
name: javascript-conventions
description: >-
  Configure and validate JS/TS tooling conventions. Enforce pnpm, TypeScript,
  ESLint, and Prettier defaults. Use when working on JS/TS files or
  package.json. NOT for Python, backend-only, or shell scripts.
user-invocable: false
disable-model-invocation: false
license: MIT
metadata:
  author: wyattowalsh
  version: "1.0.0"
---

# JavaScript/TypeScript Conventions

Apply these conventions when JavaScript, TypeScript, Node.js tooling, or
`package.json` is the primary workstream.

## Dispatch

| $ARGUMENTS | Action |
|------------|--------|
| Active (auto-invoked when JS/TS work is primary) | Apply the operator contract below |
| Empty | Display the convention summary and routing guidance |
| `check` | Verify tooling compliance only |

## Reference File Index

| File | Purpose | When to Read |
|------|---------|--------------|
| `references/tooling-contract.md` | Required package-manager, command, CI, workspace, and package-root rules | Package commands, scripts, dependencies, lockfiles, or CI |
| `references/redirection-boundaries.md` | When JS/TS conventions should yield to Python, shell, CI, or framework-specific skills | Mixed-language or ambiguous work |
| `references/edge-cases.md` | Exception gates for npm/yarn, Corepack, generated apps, and migrations | Deviations from pnpm defaults |
| `references/typescript-patterns.md` | TypeScript config, narrowing, type guards, unions, and type-test patterns | TypeScript code or `tsconfig.json` |
| `references/eslint-prettier.md` | ESLint flat config, typed linting, and Prettier separation | Linting or formatting changes |

## Operator Contract

### Active

1. Apply this skill only when JS/TS files, Node tooling, or `package.json` are the primary surface of the task.
2. Read `references/redirection-boundaries.md` when JS/TS appears alongside Python, shell, CI, or framework-specific work.
3. Enforce the hard requirements in `references/tooling-contract.md` for package management, package-root selection, command execution, lockfiles, workspaces, and CI installs.
4. Check `references/edge-cases.md` before recommending npm, yarn, global package managers, Corepack assumptions, or lockfile migrations.
5. Read `references/typescript-patterns.md` for TypeScript config or type-safety changes.
6. Read `references/eslint-prettier.md` for linting, typed linting, or formatting changes.
7. Use guided preferences only when starting new work or when the repo does not already have a stronger local convention.

### Empty / Help

1. Summarize the hard requirements: `pnpm`, `packageManager`, `pnpm-lock.yaml`, `pnpm install --frozen-lockfile`, `pnpm exec`, `pnpm dlx`, `tsc --noEmit`, `eslint`, and `prettier`.
2. Show the difference between hard requirements and guided preferences.
3. Point to the exact reference files for tooling, exceptions, TypeScript, lint/format, and mixed-language routing.

### `check`

1. Verify JS/TS tooling compliance only; do not widen into implementation advice unless the user asks.
2. Report whether the project uses the expected package root, `pnpm`, `packageManager`, `pnpm-lock.yaml`, workspace config, scripts, `tsconfig.json`, ESLint flat config, and Prettier.
3. Flag npm/yarn/Corepack/legacy deviations and require the reason to match `references/edge-cases.md`.
4. Reject recommendations that replace repo-required tooling with `npm install`, `npx`, or ad hoc global binaries unless an exception is documented.

## Hard Requirements

- **Package manager**: use `pnpm` for JS/TS package operations unless an exception is documented.
- **Package manager pin**: honor the nearest owning `package.json` and its `packageManager` field.
- **Lockfile**: commit `pnpm-lock.yaml`; never mix lockfiles in one package root without a migration plan.
- **Install**: use `pnpm install`; use `pnpm install --frozen-lockfile` in CI.
- **Dependencies**: use `pnpm add <pkg>` or `pnpm add -D <pkg>` from the owning package root.
- **Local binaries**: use `pnpm exec <cmd>`; use `pnpm dlx <pkg>` only for one-off registry execution.
- **Scripts**: use `pnpm run <script>` or `pnpm --filter <pkg> run <script>`.
- **Type checking**: use `pnpm exec tsc --noEmit` or the repo's package script.
- **Linting**: use ESLint flat config for new ESLint setup.
- **Formatting**: use Prettier for formatting and ESLint for code-quality rules.

## Guided Preferences

When starting new JS/TS work and no stronger local constraint exists, prefer
these tools. These are defaults, not absolute law; check
`references/edge-cases.md` before overriding an established project choice.

| Purpose | Tool | Notes |
|---------|------|-------|
| Package manager | `pnpm` | Pin through `packageManager` when the package root owns `package.json` |
| Bundler | `vite` or `esbuild` | Respect framework-owned builders first |
| Linting | `eslint` | Use flat config for new setup |
| Formatting | `prettier` | Keep formatting separate from linting |
| Testing | `vitest` or framework-native runner | Prefer existing repo scripts |
| Type checking | `tsc --noEmit` | Run through `pnpm exec` or package scripts |

## TypeScript Type Safety

1. Prefer `unknown` over `any`; do not weaken established strictness to make code compile.
2. Prefer `interface` for object shapes and `type` for unions, intersections, and mapped types.
3. Use discriminated unions for state machines and tagged variants.
4. Use `as const` and `satisfies` to preserve literal inference without unsafe assertions.
5. Avoid type assertions (`as`); prefer type guards, assertion functions, and schema validation at boundaries.
6. Enable `strict` in new TypeScript projects and add stricter options when the repo can absorb them.
7. Test negative type behavior with `@ts-expect-error` or a type-test tool when type contracts are public.
8. See `references/typescript-patterns.md` for TSConfig, module-resolution, and narrowing patterns.

## Critical Rules

1. Require `pnpm` for JS/TS dependency changes unless `references/edge-cases.md` justifies npm, yarn, or another manager.
2. Resolve the owning package root before running package commands; do not assume the repository root owns every JS/TS file.
3. Never mix `pnpm-lock.yaml`, `package-lock.json`, and `yarn.lock` in the same package root outside a dedicated migration.
4. Run CI installs with `pnpm install --frozen-lockfile` when a `pnpm-lock.yaml` is present.
5. Use `pnpm exec` for local binaries and `pnpm dlx` only for one-off packages fetched from the registry.
6. Do not assume Corepack is bundled with the active Node.js runtime; check `references/edge-cases.md` before recommending Corepack setup.
7. Keep Prettier responsible for formatting and ESLint responsible for code-quality rules.
8. Redirect mixed-language or non-JS-primary work through `references/redirection-boundaries.md` instead of force-fitting this skill onto the whole task.

## Scaling Strategy

- Incidental JS/TS file in a broader non-JS task: enforce only the hard requirements that touch the JS/TS-owned surface, then route mixed-workflow questions through `references/redirection-boundaries.md`.
- JS/TS-primary feature or refactor work: apply the full operator contract, including tooling, TypeScript, linting, formatting, and test guidance where relevant.
- Repo-wide JS/TS tooling or migration work: use `check`, `references/tooling-contract.md`, and `references/edge-cases.md` to separate hard violations from documented transition paths.

## Progressive Disclosure

- Do not load every reference by default.
- Read `references/tooling-contract.md` first for command, dependency, package-root, workspace, lockfile, or CI questions.
- Read `references/redirection-boundaries.md` when Python, shell, CI, infra, or framework-specific work is mixed into the request.
- Read `references/edge-cases.md` only when the task appears to require npm, yarn, Corepack setup, generated app scaffolding, or lockfile migration exceptions.
- Read `references/typescript-patterns.md` only when TypeScript code, `tsconfig.json`, public types, or type tests are active.
- Read `references/eslint-prettier.md` only when the task touches linting, typed linting, or formatting.

## Scope Boundaries

**IS for:** JS/TS tooling conventions, Node package commands, dependency-management rules, TypeScript type-safety defaults, lint/format/test command guidance, and exception-aware repo guidance.

**NOT for:** Python conventions, shell conventions, CI pipeline design, framework architecture, backend-only implementation strategy, or broad frontend UX/design guidance.

**Canonical terms** (use these exactly):
- `pnpm` -- the required package manager for JS/TS package operations
- `package root` -- the nearest directory whose `package.json` owns the command or dependency
- `packageManager` -- the `package.json` field that pins the package manager and version
- `pnpm-lock.yaml` -- the canonical JS/TS lockfile for pnpm package roots
- `workspace` -- pnpm workspace declared by `pnpm-workspace.yaml`
- `frozen-lockfile` -- CI install mode that prevents lockfile mutation
- `pnpm exec` -- local project binary execution
- `pnpm dlx` -- one-off package execution from the registry

## Validation Contract

Run from this skill directory before declaring changes complete:

```bash
python scripts/check.py
git diff --check
```

Completion criteria:

1. `scripts/check.py` exits 0.
2. `git diff --check` exits 0.
3. No portable-CLI violations remain under this skill directory.

After changing skill definitions, public descriptions, reference files, or eval behavior, invoke `docs-steward` if available.

Download from GitHub

Resources

Skill Catalog Browse custom and external skills.

CLI Reference Install and manage skills.

agentskills.io The open ecosystem for cross-agent skills.

---

View source on GitHub