NestJS Skills

Thoughtful engineering guidance for agents that work on real NestJS codebases.

Build, audit, refactor, scale, and publish with clear ownership—without turning every project into accidental architecture.

Documentation · Getting started · Choose a skill · Feature audit · Rules reference

_{A read-only audit turns TypeScript, lint, architecture, design, security, testing, and production evidence into one prioritized report.}

✨ What is this?

This repository contains seven focused Agent Skills for Claude Code, Codex, and other clients that support the Agent Skills open standard.

Each skill owns a distinct engineering decision. Together they help an agent inspect the actual repository, choose the smallest safe design, resolve conflicting instructions before mutation, and verify outcomes with evidence.

[!TIP]
Latest release: v2.2.0 adds standalone Code Audit guidance, three runnable NestJS examples, and an opt-in evaluation harness. See the changelog for changes and verification limits.

[!IMPORTANT]
Version 2 migration: professional-software-engineering is now nestjs-professional-software-engineering, and git-commit-pr-message is now nestjs-git-commit-pr-message. Reinstall the renamed skills and update explicit commands so every skill in this NestJS collection uses the nestjs- prefix.

[!NOTE]
These skills do not force Clean Architecture, CQRS, repositories, microservices, Kubernetes, or design patterns into every project. The repository and its real constraints come first.

🧭 Pick the right skill

How they fit together

Every skill carries a pre-execution conflict guard. If two active skills want incompatible file changes, commands, contracts, or architecture, the agent assigns one owner or stops for clarification before mutation.

⚡ Quick start

1. Install the collection

npx skills add amirtaherkhani/nestjs-skills

npx skills add amirtaherkhani/nestjs-skills \
  --skill nestjs-professional-software-engineering \
  --agent claude-code \
  --agent codex

npx skills add amirtaherkhani/nestjs-skills --list

The CLI installs project skills into the client-specific location, including .claude/skills/ for Claude Code and .agents/skills/ for Codex. Add --global for a user-level installation.

2. Invoke a skill

The descriptions support automatic activation. You can also invoke a skill explicitly:

3. Ask naturally

Implement this feature using the clearest syntax supported by the current
project. Preserve the public API and run the relevant checks.

💬 Copy-ready requests

Read-only audit actions

$nestjs-code-audit
$nestjs-code-audit full src/payments
$nestjs-code-audit static
$nestjs-code-audit security src/auth

Code Audit includes its own semantic review guide; sibling skills are optional.

The audit collector uses installed local ESLint and tsc --noEmit checks only. It does not install dependencies, fix files, run migrations, build images, or deploy.

Feature roadmap audit

$nestjs-feature-audit "payments"
$nestjs-feature-audit "payments" --branch "release/2026-q3"

Feature Audit safely prepares the target branch, requires a clear roadmap in docs/ or supplied by the user, and stops before code comparison when that roadmap is missing. It never treats audit findings as authorization to implement fixes.

See the Feature Audit workflow guide for roadmap eligibility, branch-safety behavior, evidence classification, and the required report format.

The optional Codex compatibility prompt accepts /prompts:audit_feature payments on branch release/2026-q3. Bare /audit_feature is supported only when the active client already routes that command to the installed skill.

[!TIP]
Codex CLI/IDE can also expose the deprecated custom-prompt alias /prompts:nestjs-audit. See the audit guide. Bare custom commands such as /Nestjs audit are not supported.

🧪 Runnable examples and evaluation

Three executable NestJS examples cover strict boolean query parsing, a module-boundary invariant bypass with a healthy control, and a measured local HTTP optimization. Run npm run test:fixtures to verify the intentionally failing inputs and corrected behavior.

The opt-in evaluation harness prepares three tasks × two skill versions in fresh contexts, records actual CLI usage when available, and keeps fixture correctness separate from agent impact. Ordinary CI never invokes a model. Initial pilot status: the CLI was blocked before a model turn, so no agent-quality or token-savings claim is established.

🤝 Optional project rules

This repository includes ready-to-adapt engineering rules for both clients:

• Codex AGENTS.md
• Claude Code CLAUDE.md

From this repository checkout:

# Codex
cp integrations/codex/AGENTS.md ./AGENTS.md

# Claude Code
cp integrations/claude/CLAUDE.md ./CLAUDE.md

[!IMPORTANT]
Merge these templates into an existing rules file instead of overwriting project-specific instructions.

• Progressive disclosure: compact SKILL.md instructions route to focused references only when needed.
• Context before rules: inspect the repository, installed versions, transport, persistence, tests, and runtime before prescribing.
• Architecture ladder: start with cohesive feature modules; add layers, ports, CQRS, or services only when real pressure earns the cost.
• Syntax from evidence: prefer repository conventions, installed types, official documentation, and focused experiments over fashionable syntax.
• Safe syntactic sugar: reduce real ceremony without hiding I/O, state, authorization, transactions, costs, or failures.
• Framework-aware OOP: use Nest modules and providers as real boundaries; do not recreate the framework lifecycle.
• Stable error contracts: keep application failure meaning separate from HTTP, GraphQL, RPC, gRPC, WebSocket, or worker representations.
• Measure before optimizing: distinguish event-loop, database, network, memory, and capacity bottlenecks before selecting a remedy.
• Production-aware delivery: verify built artifacts, effective configuration, live state, health, telemetry, drain, rollout, and rollback.
• Intentional publication: protect unrelated work, scan staged content, and perform only explicitly authorized Git/GitHub actions.

Install dependencies and run the full repository suite:

npm install
npm test
npx skills add . --list

Run individual workflows:

npm run validate
npm run test:audit
npm run test:fixtures
npm run test:eval
npm run docs:build
npm run docs:dev
npm run preview:gif

The validator checks frontmatter, naming, descriptions, cross-skill handoffs, references, evaluation JSON, client metadata, and recommended skill size. The documentation build generates the complete website reference directly from canonical skill sources.

See CONTRIBUTING.md for authoring rules and SOURCES.md for research and attribution.