Agent Skills Basics
What a Node SME Agent Skill contains and when to invoke it - ten examples for teams using AI assistants on Node.js 24.18.0, TypeScript 5.6+, Fastify 5, and NestJS 11. These pages document skills, not application tutorials.
Prerequisites
Skills live beside the services they govern:
.cursor/skills/
├── api-scaffold/
│ └── SKILL.md
├── queue-worker/
│ └── SKILL.md
├── node-upgrade/
│ └── SKILL.md
└── incident-triage/
└── SKILL.mdPin the stack in every skill header:
## Stack pin
- Node.js 24.18.0 (Active LTS)
- TypeScript 5.6+
- Fastify 5 / NestJS 11 / Express 5 (per service ADR)
- npm 10+Scope: Skills orchestrate how an agent should work. Human cookbooks in Fastify Basics, BullMQ, and CI/CD Basics remain authoritative.
Basic Examples
1. What an Agent Skill Is
An Agent Skill is a structured SKILL.md file that tells an AI assistant what to do, what to ask for, and what not to do on a backend task.
| Artifact | Purpose |
|---|---|
SKILL.md | Triggers, inputs, outputs, guardrails |
references/ | Links to ADRs, runbooks, internal templates |
examples/ | Prompts that passed staff review |
- Skills are operational contracts, not feature tutorials
- Skills must be version-pinned - agents suggest deprecated APIs without LTS context
- One skill = one decision domain (scaffold, queue, upgrade, incident)
2. Minimum SKILL.md Structure
# API Scaffold Skill
## What this skill does
Bootstraps Fastify 5 + TypeScript + tests + Dockerfile.
## When to invoke
- New microservice in monorepo
- Replacing legacy Express stub
## Inputs (required)
- Framework ADR (Fastify vs Nest)
- Service name, port, health route path
- Whether Postgres/Redis required day one
## Outputs
- File tree checklist
- package.json scripts matching CI
- Verification: npm run typecheck && npm test
## Guardrails
- Never commit .env with real secrets
- ESM default: "type": "module"
- Health route before business routes
## Stack pin
Node.js 24.18.0 · TypeScript 5.6+ · Fastify 5
## Example prompts
See §10 below.- Inputs prevent guessing
DATABASE_URLor framework choice - Outputs must be verifiable commands, not prose
- Guardrails block unsafe automation (secrets, wrong module system)
3. When to Invoke vs When to Read Docs
| Situation | Use a skill | Read human docs |
|---|---|---|
| "Scaffold orders-api with tests" | API Scaffold Skill | Fastify Basics |
| "Add BullMQ email worker" | Queue Worker Skill | bullmq / ioredis |
| "Upgrade Node 20 → 24" | Node Upgrade Skill | Node.js Release & LTS Policy |
| "API OOM at 3am" | Incident Triage Skill | OOM Killer Response |
| "Learn what Zod is" | Read zod | Not a skill invocation |
4. Stack Pinning Prevents Hallucinations
## Stack pin (required)
- Node.js 24.18.0 - NOT Node 18 examples with `require()`
- "type": "module" - NOT CommonJS `__dirname` patterns
- Fastify 5 `await app.listen()` - NOT Fastify 3 callback listen- Agents default to training data from older Node versions
- Pin npm scripts names your CI already runs:
typecheck, nottscalone - Reference engines and engine-strict
5. Invocation Rules for the Team
## Team invocation policy
1. Name the skill in the prompt: "Use API Scaffold Skill for billing-api"
2. Attach ADR or service.yaml if it exists
3. Agent must output verification commands before claiming done
4. Human runs npm ci && npm test locally before merge
5. Never auto-merge skill-generated PRs without review- Skills assist engineers; they do not replace code review
- Pair skills with Pairing on API PRs for first-time outputs
- Log skill failures in
#backendto improve guardrails
6. Guardrails Are the Highest-Value Section
## Guardrails
- No secrets in generated files - use .env.example placeholders
- No `any` in generated TypeScript without explicit TODO
- Workers must not share HTTP server process
- Graceful shutdown handlers on API and workers
- npm audit --audit-level=high must pass before "done"- Copy guardrails from postmortems - each incident becomes a bullet
- See Agent Skills Best Practices for team-wide rules
7. Verifiable Outputs Only
Bad output: "The service is ready for production."
Good output:
cd services/orders-api
npm ci
npm run typecheck
npm test
npm run build
docker build -t orders-api:local .
curl -sf http://localhost:3000/health- Every skill ends with a command block the human can paste
- Include expected success signals (
exit 0, JSON{"status":"ok"})
Intermediate Examples
8. Skill Registry in Monorepo
docs/skills/README.md # index with invoke triggers
.cursor/skills/ # Cursor-native paths
.github/skills/ # optional: shared via submodule# Node SME Skills Index
| Skill | Trigger | Owner |
|-------|---------|-------|
| api-scaffold | new service | platform team |
| queue-worker | async job | platform team |
| node-upgrade | LTS bump | infra |
| incident-triage | SEV1/2 API | on-call |- Version skills with semver in filename or frontmatter when guardrails change
- Review skills quarterly after LTS bumps
9. Composing Multiple Skills
Prompt: "Use API Scaffold Skill for notifications-api, then Queue Worker Skill for email queue"
Order:
1. Scaffold HTTP + health + logger
2. Add Redis URL to .env.example
3. Add worker entry in package.json "worker:email"
4. Verify API and worker separately- Do not merge unrelated domains into one mega-skill
- Sequential skills share
Stack pinandGuardrailssections
10. Example Prompts That Work
Use API Scaffold Skill:
- Service: inventory-api
- Framework: Fastify 5 per ADR-012
- Needs: Postgres, no Redis day one
- Output: full tree + Dockerfile + GitHub Actions job stubUse Node Upgrade Skill:
- Current: Node 20.18.0 in Docker and .nvmrc
- Target: Node 24.18.0 Active LTS
- Monorepo: 6 services, npm workspaces
- Output: breaking-change matrix + ordered migration PRsUse Incident Triage Skill:
- Symptom: 502 from ingress, p95 latency 12s, Postgres connections maxed
- Service: orders-api v2.4.1 deployed 40m ago
- Output: T+0 to T+60 checklist with rollback decisionFAQs
Where should SKILL.md files live?
Project repo .cursor/skills/ for service-specific conventions; org registry for shared upgrade and incident playbooks. Always pin Node LTS version.
Skills vs Cursor rules?
Rules are always-on constraints. Skills are invoked playbooks with inputs/outputs. Use both: rules say "TypeScript strict"; skills say "how to scaffold Fastify 5."
Should agents run npm install automatically?
Skill may suggest commands; human approves install in untrusted networks. CI uses npm ci only.
Related
- Agent Skills Best Practices - 25-item team summary
- API Scaffold Skill - new service bootstrap
- Queue Worker Skill - BullMQ worker checklist
- Node Upgrade Skill - LTS migration
- Incident Triage Skill - OOM and pool exhaustion
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.