encore-architecture — Claude Code skill: what it does, how to install
encore-architecture guides service boundaries, data ownership, and communication design for Encore.go and Encore.ts projects.
Apache-2.0 167 installs ★ 30 updated 2026-10-23
npx skills add encoredev/skills --skill encore-architecture -a claude-codeWhat encore-architecture does
This skill directs the assistant to structure logical application architecture before writing declarations or folder trees. It treats an Encore service strictly as a boundary for code and APIs rather than a static deployment container. Because the platform can host all services inside a single runtime process or distribute them across multiple nodes without rewriting logic, the skill keeps your architectural decisions focused on business domain seams.
Guidelines emphasize starting with a single service until clear domain seams emerge. The skill advises against building technical abstraction layers such as dedicated database-access microservices, cautioning against chatty sequential remote requests. It helps balance shared schemas via SQLDatabase.named or sqldb.Named against the complexity of new network APIs.
Encore forbids nested services, guiding larger codebases into top-level system folders instead. When synchronous request-response flow must be decoupled, the skill enforces idempotent consumers and highlights the transactional Pub/Sub outbox feature in Encore.go for atomic updates.
What it helps with
- define clear domain boundaries and database ownership across services
- plan the decomposition of a monolithic Encore backend
- decide between synchronous API endpoints and Pub/Sub event queues
- structure gateway authorization and private backend capabilities
Example prompts for the agent
- Review my Encore.ts backend boundaries and suggest where to split services
- Should we use direct API calls or Pub/Sub between checkout and notifications?
- Help design the database ownership model for our new Encore.go services
How to install encore-architecture
1Skills CLI (Vercel)
npx skills add encoredev/skills --skill encore-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/architecture/
1Skills CLI (Vercel)
npx skills add encoredev/skills --skill encore-architecture -a codex2Manually: put the files in place
.agents/skills/architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add encoredev/skills --skill encore-architecture -a cursor2Manually: put the files in place
.cursor/skills/architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install encoredev/skills encore/architecture/SKILL.md2Manually: put the files in place
.github/skills/architecture/SKILL.md1Skills CLI (Vercel)
npx skills add encoredev/skills --skill encore-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/encoredev/skills --path encore/architectureManually: put the files in place
.devin/skills/architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add encoredev/skills --skill encore-architecture -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about encore-architecture
How to install encore-architecture in Claude Code?
Run npx skills add encoredev/skills --skill encore-architecture -a claude-code in your terminal.
What does encore-architecture do?
It provides architectural rules to design service boundaries, communication patterns, and data responsibility for Encore.go and Encore.ts apps.
Does Encore require one database per service?
No, Encore supports shared databases through SQLDatabase.named in TypeScript and sqldb.Named in Go when shared access simplifies system complexity.
Source text
SKILL.md · Apache-2.0
--- name: encore-architecture description: Design or revise the service architecture of an Encore.go or Encore.ts application. Covers service boundaries, data ownership, synchronous calls versus Pub/Sub, process allocation, public and private interfaces, and evolving a monolith. when_to_use: >- User is deciding how many Encore services to create, where service boundaries belong, whether to split or merge services, which service owns data, or whether services should communicate through APIs or Pub/Sub. Also use for architecture reviews and plans to break up a monolith. Trigger phrases: "design the architecture", "service boundaries", "one service or several", "monolith vs microservices", "split this service", "who owns this database", "API or Pub/Sub", "distributed monolith", "chatty services". --- # Encore application architecture Design the logical application before choosing directories and declarations. Apply the same architectural reasoning to Encore.ts and Encore.go; use `encore-service` or `encore-go-service` for language-specific implementation. ## Read the application Inspect the existing code and the Encore application model when available. Identify: - User and system operations - APIs, cron jobs, and Pub/Sub handlers - Data models and the code that changes them - Infrastructure resources and the services that use them - Existing synchronous calls and event flows - Failure, scaling, deployment, and security requirements Preserve established application concepts unless the requested change requires redefining them. ## Separate services from processes Treat an Encore service as a code and API boundary, not a fixed deployment unit. The Encore platform can run all services in one process or place each service in a separate process, configured per environment without code changes. Use service boundaries to express application responsibilities. Use process allocation to change isolation and scaling without redesigning those responsibilities. Keep the backend in one Encore application where practical so the application model spans its services, resources, IAM, tracing, and Flow diagram. ## Choose service boundaries Start a new application with one service unless a stable boundary is already known. Organize code inside it with modules, directories, or Go subpackages. Consider a separate service for a cohesive business capability with its own operations and data. Failure isolation, independent scaling or deployment, a smaller security interface, or an existing external-system seam can strengthen the case. Account for the cost of the split: network failure, cross-service coordination, distributed consistency, and an interface that both sides must maintain. Keep behavior together when most changes affect both sides or neither side can complete useful work independently. Avoid services that represent technical layers such as handlers, business logic, or database access. Expose capability operations such as `ReserveInventory`, not generic access to another service's tables. Treat repeated sequential calls across one boundary and long chains of forwarding services as evidence that the proposed services may be too narrow. ## Assign data responsibility Assign one service responsibility for each data model, its business rules, and its schema changes. Prefer calls or events when another service needs the owning service to enforce those rules. Encore supports shared database access through `SQLDatabase.named` in TypeScript and `sqldb.Named` in Go. Use it deliberately for reporting, incremental migrations, or cases where another service interface would add more complexity than it removes. Define migration ownership and write access before sharing a database. Do not impose one database per service as an Encore requirement. Evaluate the coupling created by shared schema access against the coupling created by another service interface. ## Choose communication Use a typed service API when the caller needs a result before continuing, the operation must report success or failure, or one service owns the requested capability. Use Pub/Sub when the caller need not wait, several consumers react independently, or consumer retries should not repeat the originating request. Account for eventual consistency and make handlers idempotent where duplicate delivery would affect correctness. Keep immediate request/response workflows synchronous. Keep event consumers independent rather than recreating a synchronous call chain through ordered events. When a database change and event publication must remain consistent, design for failure between them. Encore.go provides a transactional Pub/Sub outbox; other cases require an application-specific consistency mechanism. ## Define interfaces and authorization Classify operations as public, authenticated, or private. Keep internal capability operations private unless an external client needs them. Place authentication and cross-origin policy at the gateway. Keep authorization decisions about a specific capability or record with the service that owns it. ## Organize and evolve Encore services cannot be nested. Group large sets of related services in system directories; systems organize source code and are not Encore resources or deployment units. When splitting a service, identify the operations and data moving together, add the new service, replace direct calls with APIs or events, and define data ownership during the transition. Inspect the resulting model in Encore Flow and test calls that now cross the service boundary. When recommending an architecture, name the proposed services, their responsibilities, owned resources, and communication paths. Explain the concrete reason for each service split and note important consistency or failure tradeoffs. Prefer the smallest architecture that satisfies the stated requirements. See [App Structure](https://encore.dev/docs/app-structure) for the full guide and language-specific examples.
© encoredev · Apache-2.0 · encoredev/skills