Guide · Agent skill
How to use the Architecture Survey agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Architecture Survey skill is a report-only agent skill that walks a codebase's module structure and lists where it is getting harder to change, with file-level evidence for each finding. It is aimed at developers and tech leads who want a prioritized list of structural candidates before planning work. After following this guide you will know what the skill does, how to install it, how to ask for a survey, and how to read the report it produces.
Architecture SurveyYeachan-Heo/oh-my-claudecode · MIT Download the skill Quick start
- 1Download the ZIP. Download the skill ZIP from this page and unzip it so the SKILL.md file is available.
- 2Place the skill folder. Put the unzipped folder in ~/.claude/skills/ for personal use, or in the project's .claude/skills/ for one repository. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Prepare the repository. Make sure the repo has a commit history and, if you have them, CLAUDE.md, ADRs, and docs/standards/architecture.md.
- 4Ask for a survey. Request a survey in plain language, optionally naming a directory or area to narrow the scope.
- 5Review the ranked report. Read each candidate's evidence, deepening move and risk note, starting with the top recommendation.
- 6Decide on candidates. File the candidates for planning or start a design interview on the top one. The survey itself makes no edits.
What an agent skill is and what this one does
An agent skill is a folder containing a SKILL.md file that gives a compatible AI agent extra instructions for a specific kind of task. The agent loads the instructions when they are relevant. This skill is described as a periodic architecture survey: the agent walks the module graph of a codebase and reports ranked deepening candidates.
It looks for three kinds of design trouble: shallow modules with wide interfaces and thin behavior, boundaries crossed by only one real caller, and logic sitting on the wrong side of a boundary. Each suspect is put through a demolition test: if the module were removed, would its complexity disappear or reappear across its callers? Only load-bearing shallowness is reported.
- Output: a ranked report with file:line evidence, a suggested deepening move, and a risk note for each candidate.
- Each candidate also gets a severity, a confidence level (kept low by design, since findings are heuristic), and an actionable rating.
- The report ends with one top recommendation: the single candidate to deepen first.
- The skill is report-only. It does not refactor or modify files.
Install the Architecture Survey skill
Download the skill ZIP from this page and unzip it. The skill folder contains SKILL.md. Place it in one of these locations, depending on how you want to use it.
You can install it for yourself across projects in ~/.claude/skills/, or only for one repository in that project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/ so it is available in any project.
- Project install: unzip into the project's .claude/skills/ so it applies only to that repository.
- Claude apps: upload the skill under Settings → Capabilities → Skills.
Check what you need before running it
The skill needs a repository for the agent to read, including its module graph and commit history. It is designed for Claude Code or another SKILL.md-compatible agent runtime.
Optional files make the reasoning stronger. The skill reads architecture principles from CLAUDE.md and ADRs, and the seam definitions in docs/standards/architecture.md. Without these conventions, the reasoning becomes weaker. The skill also refers to a diagram skill and a drydock audit that are not included in this file.
- Required: a repository to read, with a commit history.
- Required: Claude Code or another SKILL.md-compatible runtime.
- Optional but helpful: CLAUDE.md, ADRs, and docs/standards/architecture.md.
- Not included: the diagram skill and the drydock audit the skill mentions.
Trigger a survey with a natural request
Ask the agent to survey the architecture in plain language. The skill accepts an optional argument that narrows the survey to a directory or area. With no argument, it surveys the whole repository.
The skill is meant to be used periodically, for example after a batch of tickets lands, or sooner when changes start touching more files than they should, interfaces grow to satisfy one caller, or tests must be updated together for unrelated reasons.
- Whole repo: "Run an architecture survey of this repository."
- Narrowed: "Survey the architecture of the billing module."
- After a batch of work: "Survey the repo now that this sprint's tickets have landed."
- When the repo feels harder to change: "Check where this codebase is getting harder to change and what would deepen it."
Read the report and decide what to do
Each candidate in the report gives you the evidence, the deepening move in one sentence, and a risk note. Use the ranking to decide which candidates are worth planning. The top recommendation is the one to deepen first.
The report is decision input, not work. The skill does not edit code. If you want to act on a candidate right away, you can ask the agent to interview you on the top candidate in the same session. Any actual changes go through your normal planning and delivery process.
- Check the evidence lines against the code before acting on a candidate.
- Treat confidence as low by default; the findings are heuristic judgments.
- Declined candidates with a clear reason can be recorded as an ADR so future surveys do not nominate them again.
Safety notes: scripts and network
The skill runs no scripts and uses no network access, according to its description. Its only job is to read the repository and write a report. It is explicitly forbidden from modifying files, so it does not refactor code on its own.
Because findings are heuristic, do not use the survey as a pass/fail check. The mechanical checks belong to a separate audit tool, which is not part of this file.
- No scripts are run by this skill.
- No network use is declared.
- No file edits are permitted, by design.
Tips for useful surveys
Run the survey on a repo that has CLAUDE.md, ADRs, and docs/standards/architecture.md, because the reasoning depends on those conventions. When you give no directory, the agent weights its walk toward areas with frequent recent changes, since deepening pays off where future edits land.
Narrow the survey when you already suspect a problem area. A scattered commit history with no hot spot makes the survey widen its net.
- Add the conventions files before the first run.
- Start with a narrowed directory if you have a specific suspicion.
- Use a survey as planning input, not as a merge gate.
What people use it for
- Running a periodic maintenance survey after several feature tickets have merged.
- Finding shallow modules that callers must understand in too much detail before planning a refactor.
- Spotting boundaries with only one real caller so the team can decide whether to simplify them.
- Reviewing a repo that has become harder to change, focusing on a single folder such as a billing or auth module.
- Building a prioritized list of structural candidates to feed into the next planning session.
Frequently asked questions
How do I install the Architecture Survey agent skill?
Download the skill ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ to use it across projects, or in a project's .claude/skills/ folder to use it in one repository. In the Claude apps, you can upload it under Settings → Capabilities → Skills.
What do I need to run the architecture survey skill?
You need a repository for the agent to read, including its module graph and commit history, and Claude Code or another SKILL.md-compatible agent runtime. CLAUDE.md, ADRs and docs/standards/architecture.md are optional but improve the results.
Is the Architecture Survey skill free?
This page does not state a price or licence terms beyond the item's MIT licence listing, so check the licence file in the source repository for the terms that apply to you.
Does the skill change my code?
No. The skill is report-only. It is explicitly designed not to refactor or modify files, and its completion definition requires that no file was modified.
Does the skill run scripts or use the internet?
According to this listing, it runs no scripts and uses no network access. It reads the repository and writes a report.
Why are the findings marked low confidence?
The skill treats its findings as heuristic judgments, so confidence is low by construction. Mechanically checkable findings belong to a separate drydock audit tool, which is not included in this file.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if your team does periodic maintenance on a codebase that is getting harder to change, or if you want a prioritized list of structural refactoring candidates before planning work. Pick something else if you need automated enforcement or pass/fail checks, or if you expect the agent to fix code for you, since the skill is report-only by design.
Download the skill