Agent skill

Scope Appropriate Architecture

by yonatangross in yonatangross/orchestkit

Right-sizes architecture to project scope, classifying projects into 6 tiers to prevent over-engineering.

MITAuto-check passedDevelopment

Install Scope Appropriate Architecture

skills CLI
$ npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install yonatangross/orchestkit scope-appropriate-architecture --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/yonatangross/orchestkit.git skills-src && mkdir -p .claude/skills && cp -r skills-src/src/skills/scope-appropriate-architecture .claude/skills/scope-appropriate-architecture && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
scope-appropriate-architecture
GitHub stars
290
Token cost
~1.7k tokens
SKILL.md length
641 words
Files
10 (incl. references)
Skills in repo
108
Repo updated
First seen
Licence
MIT

At a glance

Right-sizes architecture to project scope, classifying projects into 6 tiers to prevent over-engineering.

  • Designing architecture
  • SKILL.md covers The 6 Project Tiers, Auto-Detection Signals, Pattern Appropriateness Matrix and Technology Quick-Reference by…, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Selecting patterns

What it does

Scope Appropriate Architecture is an agent skill from yonatangross/orchestkit. Right-sizes architecture to project scope, classifying projects into 6 tiers to prevent over-engineering. Use when designing architecture, selecting patterns, or detecting a project tier.

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. The skill folder holds 11 other files, including reference files (for example `references/enterprise.md`, `references/interview-takehome.md` and `references/open-source.md`). Compatibility notes: Claude Code 2.1.277+

It sits in Development, covering Code simplification. It works with PostgreSQL. The repository describes itself as: The Complete AI Development Toolkit for Claude Code. 106 skills, 36 agents, 171 hooks. Install ork for stable (v9.x), or ork-alpha for the v10 line, which ships daily. The licence is MIT.

When your agent uses it

  • Designing architecture
  • Selecting patterns
  • Detecting a project tier

Example prompts

  • “/scope-appropriate-architecture”

Requirements

  • Docker
  • Compatibility (from SKILL.md): Claude Code 2.1.277+
  • Pre-approved tools (allowed-tools): Read, Glob, Grep, WebFetch, WebSearch

What it can do on your machine

Read from SKILL.md and the folder at commit 02bbf9a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Glob
    • Grep
    • WebFetch
    • WebSearch

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Claude Code 2.1.277+

    From compatibility in the SKILL.md frontmatter.

Context cost

Scope Appropriate Architecture loads about 1.7k tokens when it runs, and up to ~6.1k if it reads all its reference files. Until then it costs about 55 tokens; SKILL.md has 641 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~55
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~6.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from yonatangross/orchestkit at commit 02bbf9a, republished under its MIT licence (© yonatangross). 641 words, ~1,698 tokens.

Download SKILL.mdSave it as .claude/skills/scope-appropriate-architecture/SKILL.md (or your agent's skills folder). This skill also uses 9 other files; get the full folder from GitHub.
name
scope-appropriate-architecture
description
Right-sizes architecture to project scope, classifying projects into 6 tiers to prevent over-engineering. Use when designing architecture, selecting patterns, or detecting a project tier.
allowed-tools
Read, Glob, Grep, WebFetch, WebSearch
compatibility
Claude Code 2.1.277+
license
MIT
user-invocable
false
context
inherit
effort
low
model
haiku
metadata.category
architecture
metadata.version
1.0.0
metadata.author
OrchestKit
metadata.complexity
low
metadata.tags
architecture, yagni, over-engineering, scope, patterns

Scope-Appropriate Architecture

Right-size every architectural decision to the project's actual needs. Not every project needs hexagonal architecture, CQRS, or microservices.

Core principle: Detect the project tier first, then constrain all downstream pattern choices to that tier's complexity ceiling.


The 6 Project Tiers

TierLOC RatioArchitectureDBAuthTests
1. Interview/Take-home1.0-1.3xFlat files, no layersSQLite / JSONNone or basic8-15 focused
2. Hackathon/Prototype0.8-1.0xSingle file if possibleSQLite / in-memoryNoneZero
3. Startup/MVP1.0-1.5xMVC monolithManaged PostgresClerk/Supabase AuthHappy path + critical
4. Growth-stage1.5-2.0xModular monolithPostgres + RedisAuth serviceUnit + integration
5. Enterprise2.0-3.0xHexagonal/DDDPostgres + queuesOAuth2/SAMLFull pyramid
6. Open Source1.2-1.8xMinimal API surfaceConfigurableOptionalExhaustive public API

LOC Ratio = total lines / core business logic lines. Higher ratio = more infrastructure code relative to business value.


Auto-Detection Signals

SignalTier Indicator
README contains "take-home", "assignment", "interview"Tier 1
Time limit mentioned (e.g., "4 hours", "weekend")Tier 1-2
< 10 files, no CI, no DockerTier 1-2
.github/workflows/ presentTier 3+
package.json with 20+ dependenciesTier 3+
Kubernetes/Terraform files presentTier 4-5
CONTRIBUTING.md, CODE_OF_CONDUCT.mdTier 6
Monorepo with packages/ or apps/Tier 4-5

When confidence is low: Ask the user with AskUserQuestion.


Pattern Appropriateness Matrix

PatternInterviewHackathonMVPGrowthEnterprise
Repository patternOVERKILLOVERKILLBORDERLINEAPPROPRIATEREQUIRED
Event-driven archOVERKILLOVERKILLOVERKILLSELECTIVEAPPROPRIATE
DI containersOVERKILLOVERKILLLIGHT ONLYAPPROPRIATEREQUIRED
Separate DTO layersOVERKILLOVERKILL1 EXTRA2 LAYERSALL LAYERS
MicroservicesNEVERNEVERNEVEREXTRACT ONLYAPPROPRIATE
CQRSOVERKILLOVERKILLOVERKILLOVERKILLWHEN JUSTIFIED
Hexagonal architectureOVERKILLOVERKILLOVERKILLBORDERLINEAPPROPRIATE
DDD (bounded contexts)OVERKILLOVERKILLOVERKILLSELECTIVEAPPROPRIATE
Message queuesOVERKILLOVERKILLBORDERLINEAPPROPRIATEREQUIRED
API versioningSKIPSKIPURL prefixHeader-basedFull strategy
Error handlingtry/catchconsole.logError boundaryError serviceRFC 9457
Loggingconsole.lognoneStructured JSONCentralizedOpenTelemetry

Rule of thumb: If a pattern shows OVERKILL for the detected tier, do NOT use it. Suggest the simpler alternative instead.


Technology Quick-Reference by Tier

ChoiceInterviewHackathonMVPGrowthEnterprise
DatabaseSQLite / JSON fileIn-memory / SQLiteManaged PostgresPostgres + RedisPostgres + queues + cache
AuthHardcoded / noneNoneClerk / Supabase AuthAuth serviceOAuth2 / SAML / SSO
State mgmtuseStateuseStateZustand / ContextZustand + React QueryRedux / custom + cache
CSSInline / TailwindTailwindTailwindTailwind + design tokensDesign system
APIExpress routesSingle file handlerNext.js API routesFastAPI / ExpressGateway + services
DeploymentlocalhostVercel / RailwayVercel / RailwayDocker + managedK8s / ECS
CI/CDNoneNoneGitHub Actions basicMulti-stage pipelineFull pipeline + gates
MonitoringNoneNoneError tracking onlyAPM + logsFull observability stack

Show full SKILL.md (215 more words)Show less

Build vs Buy Decision Tree (Tiers 1-3)

For Interview, Hackathon, and MVP tiers, always prefer buying over building:

CapabilityBUY (use SaaS)BUILD (only if)
AuthClerk, Supabase Auth, Auth0Core product IS auth
PaymentsStripeCore product IS payments
EmailResend, SendGridCore product IS email
File storageS3, Cloudflare R2Compliance requires on-prem
SearchAlgolia, Typesense Cloud> 10M docs or custom ranking
AnalyticsPostHog, MixpanelUnique data requirements

Time savings: Auth alone is 2-4 weeks build vs 2 hours integrate.


Upgrade Path

When a project grows beyond its current tier, upgrade incrementally:

Tier 2 (Prototype) → Tier 3 (MVP)
  Add: Postgres, basic auth, error boundaries, CI

Tier 3 (MVP) → Tier 4 (Growth)
  Add: Redis cache, background jobs, monitoring, module boundaries

Tier 4 (Growth) → Tier 5 (Enterprise)
  Add: DI, bounded contexts, message queues, full observability
  Extract: First microservice (only the proven bottleneck)

Key insight: You can always add complexity later. You cannot easily remove it.


When This Skill Activates

This skill is loaded by:

  • brainstorm Phase 0 (context discovery)
  • implement Step 0 (context discovery)
  • quality-gates YAGNI check
  • Any skill that needs to right-size a recommendation

The detected tier is passed as context to constrain downstream decisions.


  • ork:brainstorm - Uses tier detection in Phase 0 to constrain ideas
  • ork:implement - Uses tier detection in Step 0 to constrain architecture
  • ork:quality-gates - YAGNI gate references this skill's tier matrix
  • ork:architecture-patterns - Architecture validation (constrained by tier)

References

Load on demand with Read("references/<file>"):

FileContent
interview-takehome.mdTiers 1-2 in detail
startup-mvp.mdTier 3 patterns and decisions
enterprise.mdTiers 4-5 patterns and justification criteria
open-source.mdTier 6 unique considerations

© yonatangross, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 9 other files (references) in src/skills/scope-appropriate-architecture of yonatangross/orchestkit.

  • SKILL.md
  • references/enterprise.md
  • references/interview-takehome.md
  • references/open-source.md
  • references/startup-mvp.md
  • rules/_sections.md
  • rules/deferred-debt-marker.md
  • rules/over-engineering-flag.md
  • rules/tier-detection-evidence.md
  • test-cases.json

Open the folder on GitHubat commit 02bbf9a

Compare with similar skills

Scope Appropriate Architecture next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Scope Appropriate Architecture compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Scope Appropriate Architecture this skillyonatangross/orchestkit290—~1.7kAutomated safety check: PassMIT
BackendInsForge/InsForge13k—~1.7kAutomated safety check: PassApache-2.0
Windmill Rust Backend Patternswindmill-labs/windmill18k—~869Automated safety check: PassCustom licence
Dhhmarckohlbrugge/37signals-skills724—~2.2kAutomated safety check: PassNone
Claimable Postgreshenryalouf/ruflow157—~2.4kAutomated safety check: NotesMIT
Architecturemanagedcode/dotnet-skills486—~659Automated safety check: PassMIT

Similar skills

  • Backend

    InsForge/InsForge

    A skill your agent uses when contributing to InsForge's backend package.

    13k GitHub stars~1.7k tokensUpdated 3 days ago
    DevelopmentAuto-check passed
  • Windmill Rust Backend Patterns

    windmill-labs/windmill

    Sets Rust conventions for the Windmill backend: error types, SQLx queries, JSON handling, async rules, module layout and rust-analyzer navigation.

    18k GitHub stars~869 tokensUpdated today
    DevelopmentAuto-check passed
  • Dhh

    marckohlbrugge/37signals-skills

    Review Ruby/Rails code like DHH would - direct, opinionated, allergic to over-engineering.

    724 GitHub stars~2.2k tokensUpdated 4 mo ago
    DevelopmentAuto-check passed
  • Claimable Postgres

    henryalouf/ruflow

    Provision instant temporary Postgres databases via Claimable Postgres by Neon (pg.new).

    157 GitHub stars~2.4k tokensUpdated 4 mo ago
    DevelopmentAuto-check: notes
  • Architecture

    managedcode/dotnet-skills

    Design or review .NET solution architecture across modular monoliths, clean architecture, vertical slices, microservices, DDD, CQRS, and cloud-native boundaries without over-engineering.

    486 GitHub stars~659 tokensUpdated today
    DevelopmentAuto-check passed
  • Ponytail

    DavidObando/gsharp

    Forces the laziest solution that actually works, simplest, shortest, most minimal.

    564 GitHub starsUsed in 8 repos~1.7k tokens
    DevelopmentAuto-check passed

More from yonatangross/orchestkit

All 108 skills in this repo
  • API Design

    yonatangross/orchestkit

    API contract design for REST and GraphQL, covering resource shape, URL and header versioning with deprecation windows, RFC 9457 Problem Details error handling, and OpenAPI specs.

    290 GitHub stars~2.9k tokensUpdated today
    Auto-check passed
  • Architecture Decision Record

    yonatangross/orchestkit

    ADR templates in the Nygard format with context, decision, consequences, and alternatives.

    290 GitHub stars~2k tokensUpdated today
    Auto-check passed
  • Audit Full

    yonatangross/orchestkit

    Single-pass codebase analysis leveraging a 1M-token context window for comprehensive security scanning, architecture review, and dependency auditing.

    290 GitHub stars~3.5k tokensUpdated today
    Auto-check: notes
  • Code Review Playbook

    yonatangross/orchestkit

    Structured review processes, conventional comments, language-specific checklists, and feedback templates.

    290 GitHub stars~2.2k tokensUpdated today
    Auto-check passed
  • Create PR

    yonatangross/orchestkit

    Creates GitHub pull requests with pre-flight validation, conventional title formatting, and structured summary generation.

    290 GitHub stars~4.5k tokensUpdated today
    Auto-check: notes
  • Explore

    yonatangross/orchestkit

    Multi-angle codebase exploration spawning 3-5 parallel agents for code structure, data flow, architecture patterns, and health assessment.

    290 GitHub stars~3.9k tokensUpdated today
    Auto-check: notes

Works with

Questions about Scope Appropriate Architecture

What does Scope Appropriate Architecture do?

Right-sizes architecture to project scope, classifying projects into 6 tiers to prevent over-engineering. Scope Appropriate Architecture is an agent skill from yonatangross/orchestkit. Right-sizes architecture to project scope, classifying projects into 6 tiers to prevent over-engineering.

When should I use Scope Appropriate Architecture?

Scope Appropriate Architecture fits situations like: designing architecture; selecting patterns; detecting a project tier.

How do I install Scope Appropriate Architecture in Claude Code?

Run `npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a claude-code`. Or copy the skill folder (src/skills/scope-appropriate-architecture in yonatangross/orchestkit) into .claude/skills/scope-appropriate-architecture in your project. Claude Code loads it when a task matches its description.

How do I install Scope Appropriate Architecture in Codex?

Run `npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a codex`. Or copy the skill folder (src/skills/scope-appropriate-architecture in yonatangross/orchestkit) into .agents/skills/scope-appropriate-architecture in your project. Codex loads it when a task matches its description.

Can I use Scope Appropriate Architecture in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/scope-appropriate-architecture, .gemini/skills/scope-appropriate-architecture, .github/skills/scope-appropriate-architecture and .opencode/skills/scope-appropriate-architecture in your project.

What does Scope Appropriate Architecture need to run?

SKILL.md names no scripts, command-line tools or credentials: Scope Appropriate Architecture is instructions for the agent only. Our summary lists: Docker. Its frontmatter pre-approves these tools: Read, Glob, Grep, WebFetch, WebSearch. Compatibility (from SKILL.md): Claude Code 2.1.277+.

Does Scope Appropriate Architecture access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Scope Appropriate Architecture safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Scope Appropriate Architecture use?

Scope Appropriate Architecture is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Scope Appropriate Architecture use?

About 1.7k tokens (SKILL.md is roughly 6.8k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 4.4k tokens, read only when the agent opens those files.

What are the alternatives to Scope Appropriate Architecture?

Skills that share tags, products or a category with Scope Appropriate Architecture: Backend (InsForge/InsForge, 13k stars), Windmill Rust Backend Patterns (windmill-labs/windmill, 18k stars), Dhh (marckohlbrugge/37signals-skills, 724 stars) and Claimable Postgres (henryalouf/ruflow, 157 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Scope Appropriate Architecture?

yonatangross (a GitHub user) maintains it in yonatangross/orchestkit, which has 290 GitHub stars. The repository holds 108 skills in this directory. The repository was last updated on October 9, 2026.

Source: yonatangross/orchestkit on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.