Agent Skills Best Practices

A condensed summary of the 25 most important Agent Skill practices for Node.js SME teams - drawn from every page in this section.

Skills are playbooks, not tutorials: SKILL.md tells agents how to execute - Agent Skills Basics defines structure; Fastify Basics teaches concepts.
Pin the stack in every skill: Node.js 24.18.0, TypeScript 5.6+, Fastify 5 / Nest 11 - unpinned skills hallucinate deprecated APIs.
One skill per decision domain: Scaffold, queue, upgrade, incident - never one mega-skill.
Declare inputs before acting: Framework ADR, service name, Redis URL, current Node version - agents guess without them.
Outputs must be verifiable: npm ci, npm run typecheck, npm test, curl /health - reject prose-only "done."
Guardrails are the highest-value section: No secrets in git, workers separate from HTTP, idempotent retries - see Queue Worker Skill.
Invoke skills at decision points: New service, LTS upgrade, 3am incident - not for reading introductory docs.
Human docs remain source of truth: Skills link to cookbooks; do not duplicate full framework guides.
Run npm audit --audit-level=high in skill verification: Mandatory for scaffold and upgrade outputs.
ESM default for new scaffolds: "type": "module" unless ADR says CommonJS.
API scaffold includes health + graceful shutdown: Before any domain route - API Scaffold Skill.
Queue skills enforce Zod on payloads: Poison messages hit DLQ with logged jobId, not silent corruption.
Workers as separate deployables: Never block the event loop with BullMQ in the HTTP process.
Node upgrade skills use ordered PR trains: Platform CI/Docker before per-service fixes - Node Upgrade Skill.
Rebuild native addons on LTS bump: bcrypt, sharp ABI errors mean npm ci on new Node, not code hacks.
Incident skills: contain before diagnose: Rollback, scale, flag off - then heap snapshot or query analysis.
Assign IC and scribe on incident skill runs: Timeline in Slack thread with UTC timestamps.
Pool exhaustion: fix app leaks before restarting Postgres: Incident Triage Skill.
Refresh skills after postmortems: Every missed guardrail becomes a new bullet with date.
Version skills when guardrails change: Semver or changelog in docs/skills/.
Team invocation policy in CONTRIBUTING.md: Name skill in prompt; human reviews all output.
No any in generated TypeScript without TODO ticket: Strict mode is default.
Dockerfile pins same Node patch as .nvmrc: 24.18.0, not floating 24-alpine.
CI scripts in skills match local package.json: Same command surface as GitHub Actions Integration.
Quarterly skill review after LTS announcements: Deprecate Node N-2 examples from all SKILL.md files.

FAQs

Where should SKILL.md files live?

.cursor/skills/ in the service repo for project-specific conventions; org git repo for shared upgrade and incident playbooks.

Can juniors invoke incident skills solo?

Yes for structure, but SEV1/2 requires staff engineer on thread. Skill does not replace escalation policy.

Skills vs internal CLI generators?

CLI generators (npm run create:service) encode one path; skills guide agents when requirements vary. Prefer CLI when 90% identical every time.

Agent Skills Basics - anatomy with 10 examples
API Scaffold Skill - Fastify/Nest bootstrap
Queue Worker Skill - BullMQ checklist
Node Upgrade Skill - LTS migration matrix
Incident Triage Skill - OOM and pool tree

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Agent Skills Best Practices

A condensed summary of the 25 most important Agent Skill practices for Node.js SME teams - drawn from every page in this section.

Skills are playbooks, not tutorials: SKILL.md tells agents how to execute - Agent Skills Basics defines structure; Fastify Basics teaches concepts.

Pin the stack in every skill: Node.js 24.18.0, TypeScript 5.6+, Fastify 5 / Nest 11 - unpinned skills hallucinate deprecated APIs.

One skill per decision domain: Scaffold, queue, upgrade, incident - never one mega-skill.

Declare inputs before acting: Framework ADR, service name, Redis URL, current Node version - agents guess without them.

Outputs must be verifiable: npm ci, npm run typecheck, npm test, curl /health - reject prose-only "done."

Guardrails are the highest-value section: No secrets in git, workers separate from HTTP, idempotent retries - see Queue Worker Skill.

Invoke skills at decision points: New service, LTS upgrade, 3am incident - not for reading introductory docs.

Human docs remain source of truth: Skills link to cookbooks; do not duplicate full framework guides.

Run npm audit --audit-level=high in skill verification: Mandatory for scaffold and upgrade outputs.

ESM default for new scaffolds: "type": "module" unless ADR says CommonJS.

API scaffold includes health + graceful shutdown: Before any domain route - API Scaffold Skill.

Queue skills enforce Zod on payloads: Poison messages hit DLQ with logged jobId, not silent corruption.

Workers as separate deployables: Never block the event loop with BullMQ in the HTTP process.

Node upgrade skills use ordered PR trains: Platform CI/Docker before per-service fixes - Node Upgrade Skill.

Rebuild native addons on LTS bump: bcrypt, sharp ABI errors mean npm ci on new Node, not code hacks.

Incident skills: contain before diagnose: Rollback, scale, flag off - then heap snapshot or query analysis.

Assign IC and scribe on incident skill runs: Timeline in Slack thread with UTC timestamps.

Pool exhaustion: fix app leaks before restarting Postgres: Incident Triage Skill.

Refresh skills after postmortems: Every missed guardrail becomes a new bullet with date.

Version skills when guardrails change: Semver or changelog in docs/skills/.

Team invocation policy in CONTRIBUTING.md: Name skill in prompt; human reviews all output.

No any in generated TypeScript without TODO ticket: Strict mode is default.

Dockerfile pins same Node patch as .nvmrc: 24.18.0, not floating 24-alpine.

CI scripts in skills match local package.json: Same command surface as GitHub Actions Integration.

Quarterly skill review after LTS announcements: Deprecate Node N-2 examples from all SKILL.md files.

FAQs

Where should SKILL.md files live?

.cursor/skills/ in the service repo for project-specific conventions; org git repo for shared upgrade and incident playbooks.

Can juniors invoke incident skills solo?

Yes for structure, but SEV1/2 requires staff engineer on thread. Skill does not replace escalation policy.

Skills vs internal CLI generators?

CLI generators (npm run create:service) encode one path; skills guide agents when requirements vary. Prefer CLI when 90% identical every time.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

Agent Skills Best Practices

FAQs

Related

Search Documentation

Agent Skills Best Practices

FAQs

Related