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 Survey

by Yeachan-Heo in Yeachan-Heo/oh-my-claudecode

Periodic survey that walks a repo's module graph and reports ranked candidates for deepening, without changing any code itself.

MITAuto-check passedDevelopment

Install Architecture Survey

skills CLI
$ npx skills add Yeachan-Heo/oh-my-claudecode --skill architecture-survey -a claude-code

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

GitHub CLI
$ gh skill install Yeachan-Heo/oh-my-claudecode architecture-survey --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/Yeachan-Heo/oh-my-claudecode.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/architecture-survey .claude/skills/architecture-survey && 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-survey
GitHub stars
40k
Token cost
~1.3k tokens
SKILL.md length
741 words
Files
1
Skills in repo
47
Repo updated
First seen
Licence
MIT

At a glance

Periodic survey that walks a repo's module graph and reports ranked candidates for deepening, without changing any code itself.

  • Works in 3 steps: Read the repo's architecture principles… → Walk the module graph of the target area… → Look for three finding classes
  • Checking where a repo is getting harder to change after several days of building
  • SKILL.md covers When to survey, The survey, The report and Handoff, plus 2 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

A survey fits every few days of active building or after a batch of tickets lands, and out of turn when edits start touching too many files or interfaces keep growing for a single caller. It reads the architecture principles in CLAUDE.md and ADRs plus the seam vocabulary in docs/standards/architecture.md, then walks the module graph of a chosen directory or the whole repo, weighting the walk toward areas that keep showing up in recent commit history.

It looks for three kinds of finding: shallow modules with wide interfaces and thin behavior, hypothetical seams crossed by one adapter and no second caller, and logic sitting behind a seam that does not own its data. A demolition test filters suspects: if removing a module makes its complexity vanish it was a pass-through, but if the complexity reappears across callers it is load-bearing. The report ranks candidates by expected payoff against risk, each with file and line evidence, a one-sentence deepening move and a risk note, and then the survey stops and hands them over.

When your agent uses it

  • Checking where a repo is getting harder to change after several days of building
  • Finding modules whose interfaces are nearly as complex as their implementation
  • Producing a ranked refactoring shortlist for one directory

Example prompts

  • “Survey the src/payments folder and rank the modules that deserve deepening.”
  • “Edits keep touching too many files lately, so run an architecture survey of the whole repo.”
  • “Find boundaries in our API layer that have only one adapter and no second caller.”

Workflow steps

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

  1. Read the repo's architecture principles (CLAUDE.md, ADRs) and the seeded seam vocabulary in docs/standards/architecture.md — the…
  2. Walk the module graph of the target area — and when no direction was given, weight the walk toward the yard's busy water: read a good…
  3. Look for three finding classes

What it can do on your machine

Read from SKILL.md and the folder at commit 454bae0. 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 Survey loads about 1.3k tokens when it runs. Until then it costs about 71 tokens; SKILL.md has 741 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~71
When it runs · the whole SKILL.md, loaded when a task matches
~1.3k

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 Yeachan-Heo/oh-my-claudecode at commit 454bae0, republished under its MIT licence (© Yeachan-Heo). 741 words, ~1,289 tokens.

Download SKILL.mdSave it as .claude/skills/architecture-survey/SKILL.md (or your agent's skills folder).
name
architecture-survey
description
Periodic architecture survey — walks the module graph and reports ranked deepening candidates (shallow modules, hypothetical seams, logic behind the wrong seam). Survey, not rescue: it finds candidates and hands them to the captain; it never refactors on its own.
argument-hint
[optional directory or area to survey]
level
3
disable-model-invocation
true

A surveyor charts the reef; the captain decides whether to dredge. The survey reads the water, reports what it found with evidence, and stops. It is the maintenance twin of the loft: where the loft answers one design question before building, the survey answers "where is this repo getting harder to change, and what would deepen it" after building.

When to survey

  • Periodically — every few days of active building, or after a batch of tickets lands.
  • Out of turn, when the repo starts feeling harder to change than it was last week: edits touching more files than they should, interfaces growing to satisfy one caller, tests that must be updated in lockstep for unrelated reasons.

Optional argument narrows the survey to a directory or area; with no argument, survey the whole repo.

The survey

  1. Read the repo's architecture principles (CLAUDE.md, ADRs) and the seeded seam vocabulary in docs/standards/architecture.md — the definitions of seam and deep module.
  2. Walk the module graph of the target area — and when no direction was given, weight the walk toward the yard's busy water: read a good stretch of the commit history first and let the areas that keep coming up pull the survey, because deepening pays off where future edits will land. A scattered history with no hot spot widens the net.
  3. Look for three finding classes:
    • Shallow modules — wide interface, thin behavior; callers know more than the module hides.
    • Hypothetical seams — a boundary crossed by exactly one adapter with no second caller; checkable by counting callers.
    • Logic behind the wrong seam — behavior living on the far side of a boundary that does not own its data.

Apply the demolition test to every suspect: if the module were removed, would its complexity vanish (a pass-through wearing a uniform) or reappear across its callers (load-bearing)? Only load-bearing shallowness is a finding.

The report

Rank candidates by leverage against risk. Each candidate carries:

  • Evidence — file:line for the interface, its callers, and the behavior.
  • The deepening move — what to deepen, merge, or move, in one sentence.
  • The risk note — what the move touches and what could break.

Every candidate states the yard's shared findings vocabulary — severity (how much friction the shallowness causes), confidence (a survey finding is heuristic-class and therefore low by construction; the mechanically checkable end of the scale belongs to the drydock --check audit), and actionable (whether the deepening move is specific enough to start from the report alone). End the report with the top recommendation: the one candidate to deepen first, and why — the captain reads one card, not the whole reef.

Logbook conflicts. A candidate that contradicts an existing ADR is nominated only when the friction is real: the card names the ADR and why the water has changed. Theoretical conflicts stay off the report — the logbook's rejections are not re-litigated by default.

The report may be rendered visually with the repo's diagram skill when the yard has one; the prose report stays the source of truth either way.

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

Handoff

The report is decision input, not work. Candidates feed the mission brief (launch Phase 1) or grilling material for the next effort. Survey proposes; the captain disposes.

Grill the top candidate on the spot. When the captain wants to act on the survey immediately rather than filing it, the report's top recommendation becomes the first question of a design-tree interview in the same session — launch Phase 1's frontier protocol, run right here: what would deepening this candidate involve, what does it cost, what does it unblock. The evidence is fresh and the captain is present; a finding worked now is a decided effort, not a report waiting to go stale. The survey still makes no edits — the interview decides, and delivery goes through launch's own gates.

A candidate the captain declines with a load-bearing reason is offered as an ADR — the same ADR test launch applies (hard to reverse, surprising without context, a real tradeoff) — so the next survey does not re-nominate the same reef. Declined without one, it simply sinks.

Non-goals

  • No code edits. The survey never refactors, not even "while it's fresh."
  • Not a gate. Nothing blocks on the report.
  • Not merged into the drydock drift audit. --check stays strictly mechanically checkable — high-confidence findings only. Architecture judgment is a low-confidence heuristic; mixing it in dilutes the contract.

Completion definition

The survey is done when the report exists with evidence, rankings, and risk notes for every finding — and no file was modified.

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

Files

Just SKILL.md in skills/architecture-survey of Yeachan-Heo/oh-my-claudecode.

Open the folder on GitHubat commit 454bae0

Compare with similar skills

Architecture Survey 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 Survey compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Architecture Survey this skillYeachan-Heo/oh-my-claudecode40k—~1.3kAutomated safety check: PassMIT
Vanity Engineering Reviewbencium/bencium-marketplace446—~2.4kAutomated safety check: PassMIT
Systematic Code Refactoringluongnv89/claude-howto42k—~3kAutomated safety check: PassMIT
Code Simplification for ego-litecitrolabs/ego-lite17k—~1.2kAutomated safety check: PassMIT
Code Refactoring Workflowluongnv89/claude-howto42k—~3.1kAutomated safety check: PassMIT
Architecture PatternsKartikLabhshetwar/better-shot2.4k2 repos~1.4kAutomated safety check: PassCustom licence

Similar skills

  • Vanity Engineering Review

    bencium/bencium-marketplace

    Reviews codebases, architectures, PRs, and technical plans for vanity engineering — code and systems built for the developer's ego, resume, or intellectual pleasure rather than delivering user or…

    446 GitHub stars~2.4k tokensUpdated 7 days ago
    DevelopmentAuto-check passed

  • Systematic Code Refactoring

    luongnv89/claude-howto

    Guides refactoring in phases based on Martin Fowler's method: research, test coverage check, planning and small tested steps, with your approval at each phase.

    42k GitHub stars~3k tokensUpdated today
    DevelopmentAuto-check passed

  • Code Simplification for ego-lite

    citrolabs/ego-lite

    Finds and implements evidence-backed simplifications in the ego-lite repository, such as dead code, duplicated state and speculative abstractions, without hiding behavior changes.

    17k GitHub stars~1.2k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Code Refactoring Workflow

    luongnv89/claude-howto

    Guides systematic, test-backed refactoring in the style of Martin Fowler, moving through research, planning and small incremental changes with your approval at each phase.

    42k GitHub stars~3.1k tokensUpdated today
    DevelopmentAuto-check passed

  • Architecture Patterns

    KartikLabhshetwar/better-shot

    Deep dive into software architecture for macOS. An agent skill from KartikLabhshetwar/better-shot.

    2.4k GitHub starsUsed in 2 repos~1.4k tokens
    DevelopmentAuto-check passed

  • FIXME Resolver

    tailcallhq/forgecode

    Finds every FIXME comment in a codebase, groups related ones across files into one task, implements the work they describe and removes the comments once it is done.

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

More from Yeachan-Heo/oh-my-claudecode

All 47 skills in this repo

  • Ask Advisor Routing

    Yeachan-Heo/oh-my-claudecode

    Sends a question or task to another locally installed agent CLI, such as Codex or Gemini, through omc ask and saves the answer as a file.

    40k GitHub stars~572 tokensUpdated 3 days ago
    Auto-check passed

  • Ask Navigator

    Yeachan-Heo/oh-my-claudecode

    Charts a foggy effort into a map of decision tickets on the repo's issue tracker and works through them one per session, producing decisions rather than deliverables.

    40k GitHub stars~4.1k tokensUpdated 3 days ago
    Auto-check passed

  • Self-Improve Evolutionary Loop

    Yeachan-Heo/oh-my-claudecode

    Runs an autonomous improvement loop on a repository: agents propose and execute plans, a tournament picks the winner by benchmark, and each round is recorded and plotted.

    40k GitHub stars~5.3k tokensUpdated 3 days ago
    Auto-check: warnings

  • Autopilot

    Yeachan-Heo/oh-my-claudecode

    Takes a short product idea through requirements, design, planning, parallel implementation, QA cycles and multi-reviewer validation to produce working code.

    40k GitHub stars~4.4k tokensUpdated 3 days ago
    Auto-check passed

  • OMC Mode Cancellation

    Yeachan-Heo/oh-my-claudecode

    Detects and gracefully cancels whichever OMC mode, autopilot, ralph, swarm, pipeline, or team, is currently active, then clears its state.

    40k GitHub stars~4.6k tokensUpdated 3 days ago
    Auto-check passed

  • Hierarchical AGENTS.md Generator

    Yeachan-Heo/oh-my-claudecode

    Maps a codebase directory by directory and writes linked AGENTS.md files, each pointing to its parent, to document what each area contains.

    40k GitHub stars~2.3k tokensUpdated 3 days ago
    Auto-check passed

Categories

Questions about Architecture Survey

What does Architecture Survey do?

Periodic survey that walks a repo's module graph and reports ranked candidates for deepening, without changing any code itself. A survey fits every few days of active building or after a batch of tickets lands, and out of turn when edits start touching too many files or interfaces keep growing for a single caller.md, then walks the module graph of a chosen directory or the whole repo, weighting the walk toward areas that keep showing up in recent commit history.

When should I use Architecture Survey?

Architecture Survey fits situations like: checking where a repo is getting harder to change after several days of building; finding modules whose interfaces are nearly as complex as their implementation; producing a ranked refactoring shortlist for one directory.

How do I install Architecture Survey in Claude Code?

Run `npx skills add Yeachan-Heo/oh-my-claudecode --skill architecture-survey -a claude-code`. Or copy the skill folder (skills/architecture-survey in Yeachan-Heo/oh-my-claudecode) into .claude/skills/architecture-survey in your project. Claude Code loads it when a task matches its description.

How do I install Architecture Survey in Codex?

Run `npx skills add Yeachan-Heo/oh-my-claudecode --skill architecture-survey -a codex`. Or copy the skill folder (skills/architecture-survey in Yeachan-Heo/oh-my-claudecode) into .agents/skills/architecture-survey in your project. Codex loads it when a task matches its description.

Can I use Architecture Survey 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 Yeachan-Heo/oh-my-claudecode --skill architecture-survey -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-survey, .gemini/skills/architecture-survey, .github/skills/architecture-survey and .opencode/skills/architecture-survey in your project.

What does Architecture Survey need to run?

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

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

Architecture Survey 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 Survey use?

About 1.3k tokens (SKILL.md is roughly 5.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Architecture Survey?

Skills that share tags, products or a category with Architecture Survey: Vanity Engineering Review (bencium/bencium-marketplace, 446 stars), Systematic Code Refactoring (luongnv89/claude-howto, 42k stars), Code Simplification for ego-lite (citrolabs/ego-lite, 17k stars) and Code Refactoring Workflow (luongnv89/claude-howto, 42k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Architecture Survey?

Yeachan-Heo (a GitHub user) maintains it in Yeachan-Heo/oh-my-claudecode, which has 39,751 GitHub stars. The repository holds 47 skills in this directory. The repository was last updated on October 8, 2026.

Source: Yeachan-Heo/oh-my-claudecode on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.