new-domain
Provides a consistent structure for adding new features to the backend API.
Install
mkdir -p .claude/skills/new-domain && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/10244" && unzip -o skill.zip -d .claude/skills/new-domain && rm skill.zipInstalls to .claude/skills/new-domain
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Scaffold a new backend domain (feature module) in the GitGazer AWS Lambda API under apps/api/src/domains/. Use when adding a new REST resource, feature area, or set of API endpoints. Covers the routes/controller/middleware/test file layout, registering the router in the app, the AWS Powertools Router + middleware chain, role-based access with requireRole, RLS-scoped data access via withRlsTransaction, and the @/ and @gitgazer/db/* import conventions.Key capabilities
- →Scaffold REST resources
- →Create feature modules
- →Register API routes
How it works
It creates a self-contained feature folder with routes, controllers, and tests following project conventions.
Inputs & outputs
When to use new-domain
- →Add new rest resource
- →Create new backend feature module
- →Add api endpoints
About this skill
New Backend Domain — GitGazer
Scaffold a new feature module in the Lambda API following the project's controller-centric domain layout. Each domain is a self-contained folder under apps/lambdas/api/src/domains/.
When to Use
- Adding a new REST resource or feature area (e.g.
/api/<thing>) - Grouping a set of related endpoints + business logic + tests
Not for: a single extra route on an existing resource (just add it to that domain's *.routes.ts).
File Layout
Create apps/lambdas/api/src/domains/<domain>/ with:
| File | Purpose | Template |
|---|---|---|
<domain>.routes.ts | HTTP endpoints on a Hono<AppEnv> router | assets/domain.routes.template.ts |
<domain>.routes.test.ts | Route tests through testRequest (controller mocked) | assets/domain.routes.test.template.ts |
<domain>.controller.ts | Business logic + RLS-scoped DB access | assets/domain.controller.template.ts |
<domain>.controller.test.ts | Vitest unit tests (AWS + DB mocked) | assets/domain.controller.test.template.ts |
<domain>.middleware.ts | Optional — only if the domain needs request-context middleware | see integrations.middleware.ts |
Reference implementations to copy patterns from: apps/lambdas/api/src/domains/metrics/ (read-only routes) and apps/lambdas/api/src/domains/notifications/ (role-gated writes).
Procedure
-
Create the folder and files from the templates above. Rename
things/Thingto your resource. -
Register the router in
createApiRouter()in apps/lambdas/api/src/app.ts. Mount it at its own path when all its routes share one prefix; its paths are relative to that mount (/is served as/api/integrations/:integrationId/things). A domain whose routes span several prefixes stays atapi.route('/', ...)with paths relative to/api:import thingsRoutes from '@/domains/things/things.routes'; // ...inside createApiRouter(), with the other api.route calls: api.route('/integrations/:integrationId/things', thingsRoutes);The global middleware chain (
compress→setContentLength→cors→authenticate→originCheck→authorize) is applied bycreateApp— do not re-add it per domain. Routes that must skip authentication go in apublicPrefixesexport of the routes file, listed in public-routes.ts. -
Write controllers that wrap every tenant-scoped query in
withRlsTransaction(see therefactorskill for the boundary rules). Default role is reader; passuserName: gitgazerWriter.namefor writes. -
Add the permission-table entries first (see Authorization below);
testRequestrunsauthorize, so route tests get 403 until they exist. -
Add tests colocated as
*.test.ts. Route tests calltestRequest(app, method, path, {appContext, cookies?, headers?, body?})from @/shared/hono/test-request, which puts the app's error and not-found handlers around the router; mount the router wherecreateApiRouter()does, e.g.new Hono<AppEnv>().route('/api/integrations/:integrationId/things', router). Mock@gitgazer/db/clientand all AWS clients — never hit real services. -
Verify:
cd apps/lambdas/api && pnpm run test:unit && pnpm run lint.
Conventions (enforced — see backend.instructions.md)
- Imports:
@/forapps/lambdas/api/src,@gitgazer/db/*for the shared package. Never../../../. - Auth context: handlers read the authenticated user from
c.var.appContext; add theaddUserIntegrationsToCtxmiddleware from integrations.middleware.ts to populateappContext.integrations/integrationRoles. - Authorization: add every route to
ROUTESand its operation toOPERATIONSin permissions/table.ts ('public','authenticated'or{minRole: 'admin' | ...}). Theauthorizemiddleware enforces it, reading the path segment at the pattern's:integrationIdposition; a route without an entry gets 403 andtable.test.tsfails. - Responses: return
c.json(...); throwBadRequestError/ForbiddenError/NotFoundError/ etc. from @/shared/errors for errors (details go in the second constructor argument). - Logging:
getLogger()from@gitgazer/backend-core/logger(AWS Powertools structured logging). - AWS clients: import pre-configured clients from
@/shared/clients/— never instantiate SDK clients in a controller.
Checklist
-
<domain>.routes.tsexportsdefaultaHono<AppEnv>router and is mounted at its own path viaapi.route('/<domain>', ...)increateApiRouter() - All tenant-scoped DB access goes through
withRlsTransactionwith the correct role - Every route has an entry in the permission table (
ROUTES+OPERATIONS) - Inputs validated; errors thrown from
@/shared/errors - Colocated
*.test.ts: routes throughtestRequest, controllers with@gitgazer/db/client+ AWS mocked -
pnpm run test:unitandpnpm run lintpass
When not to use it
- →Single route additions
Prerequisites
Limitations
- →Requires adherence to project conventions
How it compares
It enforces standardized domain layout and middleware chains.
Compared to similar skills
new-domain side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| new-domain (this skill) | 0 | 5mo | No flags | Intermediate |
| moai-domain-backend | 1 | 6mo | Review | Advanced |
| web-server-architecture | 0 | 7mo | No flags | Intermediate |
| bullmq-specialist | 25 | 10mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
moai-domain-backend
modu-ai
Backend development specialist covering API design, database integration, microservices architecture, and modern backend patterns.
web-server-architecture
develsvai
`web/src/server/**`의 router, service, 공통 계층을 건드릴 때 사용하는 스킬이다. tRPC router와 service 책임 분리, 도메인 구조, Prisma 사용 경계를 맞춘다.
bullmq-specialist
davila7
BullMQ expert for Redis-backed job queues, background processing, and reliable async execution in Node.js/TypeScript applications. Use when: bullmq, bull queue, redis queue, background job, job queue.
agentdb-advanced-features
ruvnet
Master advanced AgentDB features including QUIC synchronization, multi-database management, custom distance metrics, hybrid search, and distributed systems integration. Use when building distributed AI systems, multi-agent coordination, or advanced vector search applications.
senior-backend
davila7
Comprehensive backend development skill for building scalable backend systems using NodeJS, Express, Go, Python, Postgres, GraphQL, REST APIs. Includes API scaffolding, database optimization, security implementation, and performance tuning. Use when designing APIs, optimizing database queries, implementing business logic, handling authentication/authorization, or reviewing backend code.
database-migration
wshobson
Execute database migrations across ORMs and platforms with zero-downtime strategies, data transformation, and rollback procedures. Use when migrating databases, changing schemas, performing data transformations, or implementing zero-downtime deployment strategies.