team-architecture — Claude Code skill: design and install
team-architecture is a Claude Code skill for planning software architecture, from data models and API contracts to module boundaries and risks. It activates for architecture design requests.
MIT ★ 71 updated 2026-11-13
npx skills add sametcelikbicak/opencode-team --skill team-architecture -a claude-codeWhat team-architecture does
team-architecture structures an architecture document in Markdown, with sections for technology choices, data, APIs, modules, scaling, security, and risks. Each technology decision needs a rationale tied to the project; language and editor choices are excluded.
It helps define entity fields and relationships, deletion rules, API methods and responses, and dependency direction between modules. Scaling plans use concrete thresholds. A schema change that breaks backward compatibility requires a migration and rollback plan.
What it helps with
- justify technology choices using project context
- define data entities, relationships, and constraints
- document API methods, responses, and errors
- separate domain rules from application flows and adapters
- set scaling thresholds and plan schema rollbacks
Example prompts for the agent
- Design this project's architecture and justify the technology choices using its constraints.
- Document the data model, API contract, and module boundaries for this application.
- Create an architecture document covering risks, security boundaries, and scaling thresholds.
How to install team-architecture
1Skills CLI (Vercel)
npx skills add sametcelikbicak/opencode-team --skill team-architecture -a claude-code2Manually: put the files in place
~/.claude/skills/team-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/team-architecture/
1Skills CLI (Vercel)
npx skills add sametcelikbicak/opencode-team --skill team-architecture -a codex2Manually: put the files in place
.agents/skills/team-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add sametcelikbicak/opencode-team --skill team-architecture -a cursor2Manually: put the files in place
.cursor/skills/team-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install sametcelikbicak/opencode-team skills/team-architecture2Manually: put the files in place
.github/skills/team-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add sametcelikbicak/opencode-team --skill team-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/sametcelikbicak/opencode-team --path skills/team-architectureManually: put the files in place
.devin/skills/team-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.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 team-architecture
How do I install team-architecture in Claude Code?
Run npx skills add sametcelikbicak/opencode-team --skill team-architecture -a claude-code. The skill file is at ~/.claude/skills/team-architecture/SKILL.md.
What does team-architecture do?
It guides the creation of a Markdown architecture document covering technology decisions, data models, API contracts, module boundaries, scaling, security, and risks.
When does team-architecture require a schema rollback plan?
A migration and rollback plan is mandatory when a schema change is not backward compatible.
Source text
SKILL.md · MIT
---
name: team-architecture
description: Technical architecture design methodology. Data model, API contract, module boundaries, technology selection rationale, scalability. The playbook of the architect role.
---
# Technical Architecture Design
## Core principle: the smallest working architecture
In an MVP, the architecture is the simplest structure that gets the job done. Every layer, every service, every abstraction must be a **proven need**.
Question: "What would happen without this?" → If the answer is "nothing would happen", delete that layer.
## 1. Technology selections
A table for each selection:
| Selection | Rationale | Alternative | Why the alternative was rejected |
|---|---|---|---|
| PostgreSQL | relational integrity, flexibility with JSONB | MongoDB | schema is less explicit, queries are not relational |
The rationale must come from **the project context**: "it will run on a single server, there will be 5 users, relational data integrity is essential". "Most popular" is not a rationale.
List only the selections that **require a decision**. Do not write decisions like the language choice, the editor, formatters.
## 2. Data model
- Entities, fields (type + requiredness + default), relationships, constraints
- For each table: delete behavior (cascade or restrict)
- **Enums**: free text or a controlled list?
- **Time**: UTC or local? Timestamp format?
- **Money**: decimal, or integer cents? Which currency, and how is currency conversion handled?
- **Schema history**: backward compatible from the first version? If not, a migration + rollback plan is mandatory
Identity: UUID or auto-incrementing integer? Use UUID if there is a privacy requirement.
## 3. API contract
For each endpoint:
| Method | Path | Body | Response | Errors | Authentication |
|---|---|---|---|---|---|
Rules:
- Resources use plural naming (`/invoices`, `/users`)
- The response envelope should be consistent (the same shape in every response)
- Pagination, sorting and filtering semantics should be defined
- Standard error body: `{ error: { code, message, details? } }` — `message` is shown to the user, `details` is logged
- **Idempotency**: is a repeated POST safe? If not, `Idempotency-Key` support is required
- Versioning: a `/v1` path or a header? What is the breaking change policy?
Show an example request/response for one endpoint. The contract is where the frontend will work from — leave no ambiguity.
## 4. Module boundaries
```
domain/ → business rules, framework independent
application/→ use cases, calls the domain
adapters/ → framework, DB, HTTP
```
The dependency direction must be **inward**: `adapters → application → domain`. The domain does not depend on anything outside itself.
Write a one-sentence responsibility for each module. If a module has a two-sentence responsibility, it should be split.
## 5. Scalability
When does it become a problem? Give concrete thresholds:
| Resource | Today | Problem threshold | Mitigation |
|---|---|---|---|
| DB connections | 5 | 50+ concurrent | connection pool |
| Single server CPU | 10% | 70% | horizontal scaling |
| File storage | 2 GB | 50 GB | CDN |
Write a mitigation **only** if the threshold is genuinely close. Hypothetical scale-out design is the most common waste in an MVP.
## 6. Security boundaries
- Where is the authentication boundary? (session, token, OAuth provider)
- Authorization model: role, resource ownership, or both?
- Where do secrets live, who can access them, and how are they rotated?
- Which data is personal data, and which regulation applies (KVKK, GDPR)?
## 7. Risks
| Risk | Impact | Early signal | Mitigation |
|---|---|---|---|
## Common mistakes
| Mistake | The right way |
|---|---|
| Extracting microservices | Monolith + clean module boundaries |
| "It might change in the future" abstraction | No abstract class without a concrete need |
| Listing technologies without writing a decision | A rationale for every selection |
| A schema change without a rollback plan | A rollback plan is mandatory |
| Solving a scale problem that does not exist | Write a concrete threshold |
## Output format
Markdown. Sections: Overview / Technology selections / Data model / API contract / Module boundaries / Scalability / Security boundaries / Risks.
Explanations in the user's language (Turkish or English), schema/SQL/type definitions in English.
© sametcelikbicak · MIT · sametcelikbicak/opencode-team