✨ 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.1.0 adds nestjs-feature-audit for branch-specific roadmap validation with a hard documentation gate and evidence-backed status reporting.

[!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

Skill Reach for it when you need to…
🧠 nestjs-professional-software-engineering Implement a NestJS feature, fix, refactor, API, or library using clear version-compatible syntax and proportionate verification
🏗️ nestjs-architecture-principles Decide module, capability, dependency, data, transaction, ORM, or service boundaries
🧩 nestjs-oop-design-patterns Improve responsibilities, invariants, SOLID trade-offs, test seams, or pattern selection without over-engineering
⚡ nestjs-features-performance Design errors, security, APIs, queues, caching, observability, delivery, performance, reliability, or scale
🔎 nestjs-code-audit Audit a whole NestJS repository for static and semantic problems without modifying it
🗺️ nestjs-feature-audit Compare one feature on a named branch with its documented roadmap and classify implementation, gaps, legacy code, bugs, and blockers
🚀 nestjs-git-commit-pr-message Stage NestJS changes intentionally, scan for secrets, write commits and PRs, push safely, and follow CI or GitHub Pages

How they fit together

Workflow Recommended path
Build or change a feature 🧠 Professional Engineering → 🏗️ Architecture → 🧩 Object Design → ⚡ Runtime → 🚀 Git Publication
Review the whole codebase 🔎 Code Audit → one deduplicated, evidence-backed report
Validate a feature roadmap 🗺️ Feature Audit → one branch-specific roadmap traceability report
Diagnose a focused problem Start with the narrowest owning skill; add another only when the decision crosses boundaries

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-agent-skills

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

npx skills add amirtaherkhani/nestjs-agent-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:

Claude Code Codex
/nestjs-professional-software-engineering $nestjs-professional-software-engineering
/nestjs-code-audit $nestjs-code-audit
/nestjs-feature-audit $nestjs-feature-audit
/nestjs-git-commit-pr-message $nestjs-git-commit-pr-message

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

Goal Example request
Implement “Implement this feature using the clearest syntax supported by the current project, then verify it.”
Audit “Audit this NestJS repository and return one evidence-backed report without changing code.”
Validate roadmap “Audit the payments feature on main against its documented roadmap and report implemented, missing, legacy, bug, and blocker items.”
Architecture “Review this module graph and recommend the smallest change that removes the cycle.”
Refactor “Refactor this provider using SOLID and a pattern only if the observed variation justifies it.”
Performance “Trace this slow endpoint, identify the limiting resource, and propose a measured fix.”
Publish “Commit and push this verified change, open a draft PR, and report the matching CI and Pages status.”

Read-only audit actions

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

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.

🤝 Optional project rules

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

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 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.