New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Architecture First

by AnastasiyaW in AnastasiyaW/codex-claude-code-config

Decide module boundaries before the first file: what modules exist, which way dependencies point, who owns state, and what each module may know.

MITAuto-check passedDevelopment

Install Architecture First

skills CLI
$ npx skills add AnastasiyaW/codex-claude-code-config --skill architecture-first -a claude-code

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

GitHub CLI
$ gh skill install AnastasiyaW/codex-claude-code-config architecture-first --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/AnastasiyaW/codex-claude-code-config.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/development/architecture-first .claude/skills/architecture-first && 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
architecture-first
GitHub stars
154
Token cost
~2k tokens
SKILL.md length
1,016 words
Files
13 (incl. references)
Skills in repo
50
Repo updated
First seen
Licence
MIT

At a glance

Decide module boundaries before the first file: what modules exist, which way dependencies point, who owns state, and what each module may know.

  • Works in 8 steps: Name the modules by reason to change,… → Say what each module owns. Especially… → Draw the dependency arrows. Any cycle is… → …
  • Starting a project
  • SKILL.md covers Scope guard — read first, The one law, Pre-code checklist — before… and Stage contracts - when proof…, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Architecture First is an agent skill from AnastasiyaW/codex-claude-code-config. Decide module boundaries before the first file: what modules exist, which way dependencies point, who owns state, and what each module may know. Use when starting a project, service, site, API, or subsystem; adding a feature with no obvious home; resolving a circular import or inverted framework dependency; or writing an ARCHITECTURE.md or ADR. Do not use for a one-file script, throwaway experiment, bug fix inside an established seam, naming/function-shape cleanup (use code-complexity), an existing oversized…

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 15 other files, including reference files (for example `references/clean-architecture-original.md`, `references/clean-architecture/boundaries-and-layers.md` and `references/clean-architecture/details-and-code-organization.md`).

It sits in Development, covering Architecture decision records, Debugging and Refactoring. The repository describes itself as: Claude Code, Codex, and multi-agent configuration system: principles, hooks, skills, and workflow patterns for AI-assisted development. The licence is MIT.

When your agent uses it

  • Starting a project
  • Adding a feature with no obvious home
  • Resolving a circular import
  • Inverted framework dependency

Example prompts

  • “/architecture-first”

Workflow steps

8 steps, taken from the first numbered list in SKILL.md.

  1. Name the modules by reason to change, not by technical layer. queue, billing,
  2. Say what each module owns. Especially state: every piece of mutable state has
  3. Draw the dependency arrows. Any cycle is a design bug, not a build inconvenience.
  4. Establish the ubiquitous language. One term, one meaning, in code and in speech.
  5. Define the aggregates. What must be consistent in one step, and what may lag.
  6. Write one vertical slice end-to-end — UI to store to test — before broadening.
  7. Record it. One page: modules, ownership, data flow, external systems. Plus one
  8. Name the promotion boundaries. When one verified result becomes the input to

What it can do on your machine

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

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    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.

Context cost

Architecture First loads about 2k tokens when it runs, and up to ~85k if it reads all its reference files. Until then it costs about 176 tokens; SKILL.md has 1,016 words of instructions outside code blocks.

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

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 AnastasiyaW/codex-claude-code-config at commit 67709af, republished under its MIT licence (© AnastasiyaW). 1,016 words, ~1,999 tokens.

Download SKILL.mdSave it as .claude/skills/architecture-first/SKILL.md (or your agent's skills folder). This skill also uses 12 other files; get the full folder from GitHub.
name
architecture-first
description
Decide module boundaries before the first file: what modules exist, which way dependencies point, who owns state, and what each module may know. Use when starting a project, service, site, API, or subsystem; adding a feature with no obvious home; resolving a circular import or inverted framework dependency; or writing an ARCHITECTURE.md or ADR. Do not use for a one-file script, throwaway experiment, bug fix inside an established seam, naming/function-shape cleanup (use code-complexity), an existing oversized module (use refactoring-safely), or capacity/data scaling decisions (use system-and-data-design). This defines earned boundaries; it does not license speculative layers.

Architecture first — the shape before the first file

Most bad structure is not a bad decision. It is an absent one: code goes where the smallest diff puts it, and the smallest diff is always "next to the last thing". This skill exists to make the layout an explicit, cheap, early decision.

Scope guard — read first

Match the ceremony to the problem. Over-applying this is its own failure mode.

SituationWhat this skill asks of you
Script, spike, one file, throwawayNothing. Skip.
One module, <500 lines, one reason to changeName the module and its one job. Stop.
Service / site / API, several concernsThe full pre-code checklist below.
Multiple teams or deployables, shared domainChecklist + bounded-context map + one ADR per boundary
Multi-stage work or external release prerequisiteChecklist + a small stage map before the first implementation boundary

The one law

Dependencies point inward, toward policy. Business rules must not import the web framework, the ORM, the queue, or the file layout. The reverse is required.

Violating it silently is the failure — a violation that is written down, with the reason and the cost, is a decision. A violation nobody named is erosion.

Practical test: could this module be exercised by a test with no network, no database and no framework? If not, something outer leaked inward.

Pre-code checklist — before the first file

  1. Name the modules by reason to change, not by technical layer. queue, billing, catalog — not controllers, models, utils. A module that changes for two unrelated reasons is two modules.
  2. Say what each module owns. Especially state: every piece of mutable state has exactly one owning module, and everyone else asks that module. Module-level mutable state shared across features is the coupling that later makes a split expensive.
  3. Draw the dependency arrows. Any cycle is a design bug, not a build inconvenience. Any arrow from domain to framework is inverted — fix it with an interface owned by the inner side.
  4. Establish the ubiquitous language. One term, one meaning, in code and in speech. If the same word means different things in two places, you have found a bounded context boundary — draw it there.
  5. Define the aggregates. What must be consistent in one step, and what may lag. Transaction boundaries follow this, not the other way round.
  6. Write one vertical slice end-to-end — UI to store to test — before broadening. A slice that works proves the seams; six half-built layers prove nothing.
  7. Record it. One page: modules, ownership, data flow, external systems. Plus one short ADR per decision that was genuinely a choice (context, options, decision, consequences). Both live in git, next to the code.
  8. Name the promotion boundaries. When one verified result becomes the input to another stage, name its contract, inputs, output, and invalidation keys before implementation. A missing signer, VM, account, or remote service is a future BLOCKED stage, not a reason to keep reopening already-proven code.

Stage contracts - when proof becomes an input

For multi-stage work, architecture includes delivery boundaries as well as module boundaries. Keep these states separate:

  • VERIFIED: the scoped behavior passed at one exact revision.
  • SEALED: the verified scope has an immutable receipt and may be consumed by a following stage.
  • BLOCKED: a named external prerequisite is absent; upstream proof remains valid.
  • SUPERSEDED: a contract, source, or input digest changed, so a successor must be verified instead of editing history.

The stage map is deliberately smaller than a release plan. For each boundary, name the owning scope, frozen contract, inputs, output, and what invalidates it. Use the machine-readable ledger only when there is a real hand-off between stages: ../proof-verify/references/proven-stage-contracts.md. Do not add it to a one-file change merely because the word "stage" exists.

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

Review checklist — once code exists

  • Does any inner module import an outer one? Name it or fix it.
  • Is there module-level mutable state touched by more than one feature?
  • Does one file hold routes/handlers for more than one reason to change?
  • Are there two names for the same concept, or one name for two?
  • Can each module's tests run without the framework?
  • Does the ARCHITECTURE.md still describe what is actually there?

Fast decision table

QuestionDefault answer
Layer folders or feature folders?Feature (vertical slices). Layer folders scatter one change across four directories.
Where does validation live?Input shape at the edge; business rules inside. Never only at the edge.
Interface for a single implementation?No — until a second caller or a test double actually needs it.
Microservices?Not yet. Modular monolith with real boundaries first; extract when a module needs its own deploy or scaling.
Where does the ORM model live?Outer. The domain object is not the row.
Shared "utils" module?A smell. Utils is where things go when nobody decided; name the reason instead.

References — load on demand

  • references/clean-architecture/boundaries-and-layers.md — boundaries, Humble Object
  • references/clean-architecture/solid-and-components.md — SOLID applied correctly, REP/CCP/CRP, ADP/SDP/SAP
  • references/clean-architecture/details-and-code-organization.md — DB/web/frameworks as details
  • references/clean-architecture/python-implementation.md — entities, use cases, repositories, wiring
  • references/domain-driven-design/bounded-contexts.md — context mapping
  • references/domain-driven-design/ubiquitous-language.md — one term, one meaning
  • references/domain-driven-design/building-blocks.md — entities, value objects, aggregates
  • references/domain-driven-design/domain-events.md, repositories-factories.md, strategic-design.md
  • *-original.md — the source skills' own framework prose, kept verbatim

Gotchas

  • "We'll structure it later." Later costs more per caller, and callers only grow. The cheapest moment is before the first file; the second cheapest is now.
  • Ceremony as architecture. Four layers around a CRUD endpoint is not architecture, it is cost. The scope guard above exists to stop this.
  • Folders instead of boundaries. Moving files without changing who imports whom changes nothing. The arrows are the architecture; folders only display it.
  • The domain importing the framework "just for a type". That is the whole violation, arriving politely.

Troubleshooting

SymptomCauseFix
Circular importTwo modules both own part of one conceptExtract the shared concept into a third module both depend on
One change touches six files across four foldersLayer folders, not feature foldersRe-cut by feature; keep the change local
Tests need a live database to assert a ruleRule lives outside the domainMove the rule inward, inject the store
Nobody can say which module owns XNobody decidedDecide now, write it in ARCHITECTURE.md, move the state

© AnastasiyaW, 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 12 other files (references) in skills/development/architecture-first of AnastasiyaW/codex-claude-code-config.

  • SKILL.md
  • references/clean-architecture-original.md
  • references/clean-architecture/boundaries-and-layers.md
  • references/clean-architecture/details-and-code-organization.md
  • references/clean-architecture/python-implementation.md
  • references/clean-architecture/solid-and-components.md
  • references/domain-driven-design-original.md
  • references/domain-driven-design/bounded-contexts.md
  • references/domain-driven-design/building-blocks.md
  • references/domain-driven-design/domain-events.md
  • references/domain-driven-design/repositories-factories.md
  • references/domain-driven-design/strategic-design.md
  • references/domain-driven-design/ubiquitous-language.md

Open the folder on GitHubat commit 67709af

Compare with similar skills

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

Architecture First compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Architecture First this skillAnastasiyaW/codex-claude-code-config154—~2kAutomated safety check: PassMIT
Gameplay Design Synctangziwen/CubeMiniGame359—~1.5kAutomated safety check: PassMIT
Improve Codebase Architectureywwynm/EverythingDone14415 repos~1.3kAutomated safety check: PassGPL-3.0
Learning OpportunitiesDrCatHicks/learning-opportunities2.5k—~2.5kAutomated safety check: PassCC-BY-4.0
Code ChangesJanDeDobbeleer/oh-my-posh24k—~1.1kAutomated safety check: PassMIT
Code Review Graph Navigatorhandsontable/handsontable22k—~939Automated safety check: PassCustom licence

Similar skills

  • Gameplay Design Sync

    tangziwen/CubeMiniGame

    Assess whether completed CubeGame gameplay changes should be reconciled into Doc/GameplayIntent design documents.

    359 GitHub stars~1.5k tokensUpdated 21 days ago
    DevelopmentAuto-check passed

  • Improve Codebase Architecture

    ywwynm/EverythingDone

    Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/.

    144 GitHub starsUsed in 15 repos~1.3k tokens
    DevelopmentAuto-check passed

  • Learning Opportunities

    DrCatHicks/learning-opportunities

    Facilitates deliberate skill development during AI-assisted coding.

    2.5k GitHub stars~2.5k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed

  • Code Changes

    JanDeDobbeleer/oh-my-posh

    Workflow for any task that ends in code changes: issue analysis or triage, pull request review comments, features, bug fixes, refactors.

    24k GitHub stars~1.1k tokensUpdated today
    DevelopmentAuto-check passed

  • Code Review Graph Navigator

    handsontable/handsontable

    Queries a pre-built, Tree-sitter-based code graph of the whole monorepo instead of grepping call chains, for exploring, debugging, refactoring or reviewing code.

    22k GitHub stars~939 tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Csharp Refactoring

    microsoft/testfx

    Official

    Safely refactors C/.NET code without changing behavior. An agent skill from microsoft/testfx.

    1k GitHub starsUsed in 2 repos~3.1k tokens
    DevelopmentAuto-check passed

More from AnastasiyaW/codex-claude-code-config

All 50 skills in this repo

  • Bug Reproducer

    AnastasiyaW/codex-claude-code-config

    Find likely software bugs in a codebase, rank concrete bug candidates, and prove or reject them with focused regression tests before proposing a fix.

    154 GitHub stars~4.1k tokensUpdated today
    Auto-check passed

  • Motion Framer

    AnastasiyaW/codex-claude-code-config

    A skill your agent uses when implementing Motion or Framer Motion in React/JavaScript: interactive UI components, micro-interactions, gestures, layout or page transitions, and scroll-based animation.

    154 GitHub starsUsed in 1 repo~5.2k tokens
    Auto-check passed

  • Proof Verify

    AnastasiyaW/codex-claude-code-config

    Plan-based verification - freeze acceptance criteria before building, then verify after with an independent fresh-context agent (the builder must not verify their own work).

    154 GitHub stars~2.6k tokensUpdated today
    Auto-check passed

  • Workflow Orchestration

    AnastasiyaW/codex-claude-code-config

    Написание и запуск Claude Code dynamic workflows (JS-оркестратор субагентов).

    154 GitHub stars~3.8k tokensUpdated today
    Auto-check passed

  • Notebooklm Grounded Research

    AnastasiyaW/codex-claude-code-config

    A skill your agent uses when: NotebookLM, notebooklm MCP, large documentation sets, courses, books, papers, or citation-backed research are mentioned.

    154 GitHub stars~2.4k tokensUpdated today
    Auto-check: warnings

  • Deepseek Provider Contract

    AnastasiyaW/codex-claude-code-config

    Validate a proposed DeepSeek API integration before any key or project context is sent: check thinking-mode tool-call history, strict-schema assumptions, bounded output, and provider data boundaries.

    154 GitHub stars~1.2k tokensUpdated today
    Auto-check passed

Categories

Questions about Architecture First

What does Architecture First do?

Decide module boundaries before the first file: what modules exist, which way dependencies point, who owns state, and what each module may know. Architecture First is an agent skill from AnastasiyaW/codex-claude-code-config. Decide module boundaries before the first file: what modules exist, which way dependencies point, who owns state, and what each module may know.

When should I use Architecture First?

Architecture First fits situations like: starting a project; adding a feature with no obvious home; resolving a circular import; inverted framework dependency.

How do I install Architecture First in Claude Code?

Run `npx skills add AnastasiyaW/codex-claude-code-config --skill architecture-first -a claude-code`. Or copy the skill folder (skills/development/architecture-first in AnastasiyaW/codex-claude-code-config) into .claude/skills/architecture-first in your project. Claude Code loads it when a task matches its description.

How do I install Architecture First in Codex?

Run `npx skills add AnastasiyaW/codex-claude-code-config --skill architecture-first -a codex`. Or copy the skill folder (skills/development/architecture-first in AnastasiyaW/codex-claude-code-config) into .agents/skills/architecture-first in your project. Codex loads it when a task matches its description.

Can I use Architecture First 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 AnastasiyaW/codex-claude-code-config --skill architecture-first -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/architecture-first, .gemini/skills/architecture-first, .github/skills/architecture-first and .opencode/skills/architecture-first in your project.

What does Architecture First need to run?

SKILL.md names no scripts, command-line tools or credentials: Architecture First is instructions for the agent only.

Does Architecture First 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 Architecture First 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 Architecture First use?

Architecture First is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Architecture First use?

About 2k tokens (SKILL.md is roughly 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 83k tokens, read only when the agent opens those files.

What are the alternatives to Architecture First?

Skills that share tags, products or a category with Architecture First: Gameplay Design Sync (tangziwen/CubeMiniGame, 359 stars), Improve Codebase Architecture (ywwynm/EverythingDone, 144 stars), Learning Opportunities (DrCatHicks/learning-opportunities, 2.5k stars) and Code Changes (JanDeDobbeleer/oh-my-posh, 24k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Architecture First?

AnastasiyaW (a GitHub user) maintains it in AnastasiyaW/codex-claude-code-config, which has 154 GitHub stars. The repository holds 50 skills in this directory. The repository was last updated on October 9, 2026.

Source: AnastasiyaW/codex-claude-code-config on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.