javascript-conventions
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.
How do I install this agent skill?
npx skills add https://github.com/wyattowalsh/agents --skill javascript-conventionsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides standard JavaScript and TypeScript development conventions, focusing on enforcing the use of the pnpm package manager and promoting type-safe coding patterns. No security risks, malicious patterns, or suspicious behaviors were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
4 files scanned · No issues
What does this agent skill do?
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
- Apply this skill only when JS/TS files, Node tooling, or
package.jsonare the primary surface of the task. - Read
references/redirection-boundaries.mdwhen JS/TS appears alongside Python, shell, CI, or framework-specific work. - Enforce the hard requirements in
references/tooling-contract.mdfor package management, package-root selection, command execution, lockfiles, workspaces, and CI installs. - Check
references/edge-cases.mdbefore recommending npm, yarn, global package managers, Corepack assumptions, or lockfile migrations. - Read
references/typescript-patterns.mdfor TypeScript config or type-safety changes. - Read
references/eslint-prettier.mdfor linting, typed linting, or formatting changes. - Use guided preferences only when starting new work or when the repo does not already have a stronger local convention.
Empty / Help
- Summarize the hard requirements:
pnpm,packageManager,pnpm-lock.yaml,pnpm install --frozen-lockfile,pnpm exec,pnpm dlx,tsc --noEmit,eslint, andprettier. - Show the difference between hard requirements and guided preferences.
- Point to the exact reference files for tooling, exceptions, TypeScript, lint/format, and mixed-language routing.
check
- Verify JS/TS tooling compliance only; do not widen into implementation advice unless the user asks.
- Report whether the project uses the expected package root,
pnpm,packageManager,pnpm-lock.yaml, workspace config, scripts,tsconfig.json, ESLint flat config, and Prettier. - Flag npm/yarn/Corepack/legacy deviations and require the reason to match
references/edge-cases.md. - 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
pnpmfor JS/TS package operations unless an exception is documented. - Package manager pin: honor the nearest owning
package.jsonand itspackageManagerfield. - Lockfile: commit
pnpm-lock.yaml; never mix lockfiles in one package root without a migration plan. - Install: use
pnpm install; usepnpm install --frozen-lockfilein CI. - Dependencies: use
pnpm add <pkg>orpnpm add -D <pkg>from the owning package root. - Local binaries: use
pnpm exec <cmd>; usepnpm dlx <pkg>only for one-off registry execution. - Scripts: use
pnpm run <script>orpnpm --filter <pkg> run <script>. - Type checking: use
pnpm exec tsc --noEmitor 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
- Prefer
unknownoverany; do not weaken established strictness to make code compile. - Prefer
interfacefor object shapes andtypefor unions, intersections, and mapped types. - Use discriminated unions for state machines and tagged variants.
- Use
as constandsatisfiesto preserve literal inference without unsafe assertions. - Avoid type assertions (
as); prefer type guards, assertion functions, and schema validation at boundaries. - Enable
strictin new TypeScript projects and add stricter options when the repo can absorb them. - Test negative type behavior with
@ts-expect-erroror a type-test tool when type contracts are public. - See
references/typescript-patterns.mdfor TSConfig, module-resolution, and narrowing patterns.
Critical Rules
- Require
pnpmfor JS/TS dependency changes unlessreferences/edge-cases.mdjustifies npm, yarn, or another manager. - Resolve the owning package root before running package commands; do not assume the repository root owns every JS/TS file.
- Never mix
pnpm-lock.yaml,package-lock.json, andyarn.lockin the same package root outside a dedicated migration. - Run CI installs with
pnpm install --frozen-lockfilewhen apnpm-lock.yamlis present. - Use
pnpm execfor local binaries andpnpm dlxonly for one-off packages fetched from the registry. - Do not assume Corepack is bundled with the active Node.js runtime; check
references/edge-cases.mdbefore recommending Corepack setup. - Keep Prettier responsible for formatting and ESLint responsible for code-quality rules.
- Redirect mixed-language or non-JS-primary work through
references/redirection-boundaries.mdinstead 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, andreferences/edge-cases.mdto separate hard violations from documented transition paths.
Progressive Disclosure
- Do not load every reference by default.
- Read
references/tooling-contract.mdfirst for command, dependency, package-root, workspace, lockfile, or CI questions. - Read
references/redirection-boundaries.mdwhen Python, shell, CI, infra, or framework-specific work is mixed into the request. - Read
references/edge-cases.mdonly when the task appears to require npm, yarn, Corepack setup, generated app scaffolding, or lockfile migration exceptions. - Read
references/typescript-patterns.mdonly when TypeScript code,tsconfig.json, public types, or type tests are active. - Read
references/eslint-prettier.mdonly 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 operationspackage root-- the nearest directory whosepackage.jsonowns the command or dependencypackageManager-- thepackage.jsonfield that pins the package manager and versionpnpm-lock.yaml-- the canonical JS/TS lockfile for pnpm package rootsworkspace-- pnpm workspace declared bypnpm-workspace.yamlfrozen-lockfile-- CI install mode that prevents lockfile mutationpnpm exec-- local project binary executionpnpm 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:
scripts/check.pyexits 0.git diff --checkexits 0.- 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.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/wyattowalsh/agents/javascript-conventions">View javascript-conventions on skillZs</a>