architect
Run /architect when choosing between approaches, designing a feature or page, picking a tech stack, or when /develop says a decision is owed, anytime a load bearing technical decision is unmade. Asks deep questions, recommends an answer, and writes a build spec to docs/specs/. Owns all spec files.
Install / Use
npx skills add jsmastery-pro/skills --skill architectInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Our assessment of architect
architect scores 82/100 on our quality scale, 3373rd of 4,698 Development & Engineering skills we index.
Its SKILL.md is 27 KB long, well organised into 15 sections and no code examples: a thorough specification that gives an agent plenty to work with.
With 1,318 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 3 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-07 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
architect compared with similar skills
All 4 of these similar skills score higher than architect; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| architect (this skill)by jsmastery-pro | 82 | 1.3k | 3mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
Frequently asked questions
- How do I install architect?
- Run
npx skills add jsmastery-pro/skills --skill architect. The install tabs above show the steps for each supported agent. - Which AI agents does architect work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is architect safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is architect still maintained?
- The repository was last updated about 3 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: architect allowed-tools: Bash, Read, Grep, Glob, Write, Edit, Agent, AskUserQuestion description: "Run /architect when choosing between approaches, designing a feature or page, picking a tech stack, or when /develop says a decision is owed, anytime a load bearing technical decision is unmade. Asks deep questions, recommends an answer, and writes a build spec to docs/specs/. Owns all spec files."
Output style (plain words, no dashes, no hyphens)
<!-- OUTPUT-STYLE:START -->Write everything this skill produces, files and messages alike, in plain simple language. Talk to the reader as you, warm and direct like a colleague, and present every step as a recommendation they may run or skip, never an order. Keep technical terms that carry real meaning; explain each in plain words. Never use a dash or a hyphen as punctuation: no em dash, no en dash, and no hyphenated compounds. Write read only, not read-only. Say it in simple words, or reword the sentence. Code, file paths, command flags, and values other skills match on keep their hyphens. Use short sentences, commas, or parentheses. Clear beats clever.
What this skill does
Runs structured discovery, weighs options, and writes or updates a build spec in docs/specs/. The main thread writes; it offloads only reading the codebase or fetching the web to a cheap subagent (see Subagents). Four modes:
| Mode | When | Design behaviour |
|---|---|---|
| FEATURE | Designing a new feature from scratch, with or without existing code | First principles design, best practices, minimal code reading |
| ARCHITECTURE | Choosing a tech stack or foundational architecture for a new project | Comprehensive stack evaluation, industry patterns, no code to read |
| ENHANCEMENT | Improving, replacing, or scaling something that already exists | Read existing code + specs, focused option comparison |
| CROSS-CUTTING | Standardising a pattern across the whole codebase (error handling, logging, auth, naming) | Sample current state, define the standard precisely, recommend enforcement |
- Create: new decision → new spec with status
Proposed - Update: evolving an existing decision → edit existing spec in place
- Supersede: replacing a past decision → new spec + update old spec's status line
- Ratify: deliberating an
Assumedspec that/developrecorded when the engineer chose to build before deciding → see Ratify an assumed decision below
Spec status behaves one of two ways, decided by whether a buildable scope feature links the spec (a docs/scope/ row whose spec cell points to it):
- Feature linked spec (typical FEATURE/ENHANCEMENT, or an ARCHITECTURE foundation that has a scope row): status mirrors the feature lifecycle. /architect creates it as
Proposedand owns its content but never advances the status; /develop advances it toIn Progresswhen the feature goes in-progress, thenAcceptedwhen built and verified (scopedone). Engineer confirmation ratifies content only;Acceptedmeans shipped. - Standalone decision spec (foundational/stack or cross cutting standard, no scope row links it): decision status.
Proposedwhen written,Acceptedonce the engineer ratifies it on confirmation (the decision is then in force). /develop does not advance it.
A spec documenting already shipped work (the "already built" path, or a linked feature already existing) is born Accepted.
The Assumed status. /develop may create a spec in status Assumed when the engineer chooses to build before a load bearing decision is deliberated. It records the assumption the build used, not a deliberated decision. The feature can still be marked done; the Assumed spec stays flagged as owing ratification and does not block it. Only /architect clears the Assumed status, by ratifying (below). /architect never creates an Assumed spec; it only deliberates one that already exists.
Writes no code. Never updates AGENTS.md/CLAUDE.md (/sync owns that).
Subagents (main thread writes; subagents only read, fetch, or cross check)
The main thread runs the conversation and writes the spec; it never hands the writing or any fix to a subagent. Every subagent it spawns is read only and never inherits the session model:
- Read the codebase (cheapest model, Claude Code
haiku): a read only scan of existing code when the repo is large (ENHANCEMENT/CROSS-CUTTING). Claude Code: thescouttype. Returns a compact map, never file dumps. - Fetch from the web (cheapest model, Claude Code
haiku): the current tool landscape check and the Agent Skill / MCP discovery, both during the design conversation (Stage c), when a decision needs current facts. Claude Code: theresearchertype. Returns a compact summary, never raw pages. - Cross check the drafted spec (its primary job is decision completeness: finding values an action must produce whose source the spec never names, and decisions the builder would otherwise invent): a read only pass that reads the finished spec and returns a critique, writing nothing.
/architectalways asks whether to run it (never runs or skips it on the engineer's behalf), recommendingAnother modelstrongly atGA/Beta(the tiers where these bugs live), offering it atAlpha, and recommendingSkipatPrototype; any gap it finds is presented to the engineer with a recommended fix for them to decide, not auto resolved. See After the spec is written.
Web fetching happens once, when a decision needs it (the Stage (c) landscape and tool discovery checks). The links it returns go into the spec's References for a human to follow; the AI never fetches them again (not in the cross check, /develop, or /audit).
Asks vs acts
Ask targeted questions before you write the spec (and before spawning any read/fetch helper); spend the budget on substance. Sort every question:
- INFER: anything the prompt or codebase reveals (feature vs architecture, the stack, UI in scope, an already chosen provider). Derive, never ask.
- ASK: only what the engineer alone knows (requirements, preferences, business rules, compliance scope).
- RECOMMEND: anything expertise settles (which provider/library/pattern fits). State the pick, a one line why, and the runner up; they may override. Never a neutral menu, never a silent decision.
Never bundle a complete data model, full stack, or ready made acceptance criteria set into one accept or change panel, and never silently decide a tool, provider, or setup choice for them.
Recommendations align with the stack in use (on a BaaS, prefer its auth/storage over new external tools; reuse beats sprawl). Web or mobile alike: infer the platform, never assume web.
That is the intent, not the procedure. How to run the questioning lives in internal/design-conversation.md, which Execution below makes you read in full before you ask a single design question.
Artifact ownership
Spec files in docs/specs/, created or updated by this skill only, plus any supporting evidence it produces (inventories, audits), which lives in the spec's rationale.md (directory spec) or inline (single file spec), never in the scope folder (docs/scope/ is owned by /scope, not a spec).
Two independent choices, location (repo shape) and shape (decision size):
-
Location = repo shape. Single repo →
docs/specs/. Monorepo →docs/specs/<workspace>/for a workspace decision,docs/specs/_root/for a repo wide one (mirrors the scope). Numbering is per location (scan that dir for the nextNNNN). Call the resolved location$SPEC_DIR. -
Shape = decision size, the same in any repo shape. Simple decision: one file
$SPEC_DIR/NNNN-title.md(everything inline, written tight). An umbrella (related sub decisions), a heavy or foundational decision, or one that warrants averify.mduses the directory shape:$SPEC_DIR/NNNN-title/withindex.mdas its top file plus arationale.mdbeside it (and child specsNNNN-<child>.mdfor an umbrella). Never double the name (NNNN-title/NNNN-title.md); the directory carries the number, the top file isindex.md. Default to a single file.A directory spec always has exactly two core files (plus optional
verify.mdand child specs):index.md: the build spec/developreads:## Summary,## Requirements,## Decision, the design/spec section,## Build plan,## Consequences,## Follow-up, and a one line## Rationalepointer torationale.md. For an umbrella it also opens with a## Structuremanifest listing and linking every child spec (one line each: what it is plus which decision it supports), and holds any cross child contract.rationale.md: the decision record/developskips:## Context,## Options considered,## Rationale, the## Referencessection, and any bulky evidence (inventories, audits) under its own subheading. There is noresearch/folder; all evidence lives here.- Child specs (umbrella only) are flat
NNNN-<child>.mdfiles, each complete enough to build from on its own with a short inline rationale (not its ownrationale.md); promote a child to its own directory only when it grows heavy. Cross child contracts live in the umbrellaindex.md.
-
One narrow exception into the scope: after the spec is confirmed, update the matching feature to the ready to build shape (exact edits in After the spec is written, step 3). Never dump the atomic task list into the scope. No matching feature: offer to enroll one (see the derive tasks step).
Artifact base. specs live under docs/ by default. If docs/ is a published docs site (docusaurus.config.*, .vitepress/, mkdocs.yml, Astro Starlight, or Nextra detected), use .workflow/ instead (.workflow/specs/). Always follow whichever base already exists (paths here assume docs/).
Portability (any OS, any agent)
- Commands:
gitis the only required CLI, same on every OS. Other shell snippets (mkdir -p,date,find,ls,cat,wc) are POSIX reference, not literal scripts; use your agent's cross platform file tools (read, search/glob, write, create dir) and your knowledge of today's date. Createdocs/specs/with your write tool, notmkdir. - Bundled files:
agent-prompt.md,agent-modes/*.md, andspec-template.mdlive at paths relative to this skill's folder. The main thread reads these itself right before it writes the spec (see Write the spec):agent-prompt.md(the persona, rules, and report format), the one matchingagent-modes/<mode>.md, andspec-template.md(the section structure). Read them only at write time, not during pre-flight, so they don't sit in context through the whole interview. - No interactive question support? Use whatever your agent provides (an options picker) and fall back only where missing: ask the question rounds as plain text with the same options.
Execution
Step 0: Topic check (before pre-flight)
If no design topic was provided (/architect with no argument or an empty description), stop and ask before doing anything else:
"What design decision do you want to work through? Describe the feature, system, or choice you need to design in one or two sentences."
Wait for the answer; use it as the design topic before pre-flight.
Pre-flight (main model)
Run these steps (the git commands are literal; everything else uses your agent's file tools):
- Freshness (teams):
git fetchquietly, pick the base branch (mainifgit rev-parse --verify mainsucceeds, elsemaster), count commits behind withgit rev-list --count HEAD..origin/<base>. If >0, warn "pull first" before deciding (a teammate may have added specs or changed this feature). - Resolve the spec location (
SPEC_DIR) = the scope workspace mirrored intodocs/specs/: single repo →docs/specs/; monorepo workspace →docs/specs/<workspace>/; repo wide → `docs/specs/
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
