architectural-analysis — Claude Code skill: what it does
Audits a codebase for design problems: dead exports, duplicated duties, tangled types, dependency cycles. Read-only unless you've already allowed fixes.
npx skills add pedronauck/skills --skill architectural-analysis -a claude-codeWhat architectural-analysis does
The skill works inside the scope you give it. It first maps entry points and dependencies with rg --files and targeted searches, then sorts candidates against the signal catalog in references/detection-catalog.md. Treat the thresholds there as hints, not verdicts.
Nothing gets called dead until dynamic imports, reflection, framework hooks, tests and published APIs have been checked. A public export with no consumer in this checkout stays. Every serious finding is tied to source: path, line, the maintenance cost it causes, and the smallest change worth making.
Broad audits follow assets/report-template.md and land in .audits/architectural-analysis-<timestamp>.md, with inspected and uninspected areas kept apart. Formatting, performance profiling, security work and feature-level review sit outside this scope. On its own the audit changes nothing in your project; applying findings needs authorization you gave up front.
What it helps with
- locate dead exports and responsibilities that overlap
- untangle dependency cycles between modules
- spot where type ownership has gone wrong
- get a report citing paths and lines instead of vague complaints
Example prompts for the agent
- Run an architecture audit on the
billingpackage and point out the overlapping responsibilities - Write the audit report into
.auditsand say which areas you skipped - Check whether the export in
src/legacy/index.tsis used anywhere
How to install architectural-analysis
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill architectural-analysis -a claude-code2Manually: put the files in place
~/.claude/skills/architectural-analysis/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/architectural-analysis/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill architectural-analysis -a codex2Manually: put the files in place
.agents/skills/architectural-analysis/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill architectural-analysis -a cursor2Manually: put the files in place
.cursor/skills/architectural-analysis/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pedronauck/skills architectural-analysis2Manually: put the files in place
.github/skills/architectural-analysis/SKILL.md1Skills CLI (Vercel)
npx skills add pedronauck/skills --skill architectural-analysis -a gemini-cli2Platform CLI
gemini skills install https://github.com/pedronauck/skills --path skills/mine/architectural-analysisManually: put the files in place
.devin/skills/architectural-analysis/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pedronauck/skills --skill architectural-analysis -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about architectural-analysis
How do I install architectural-analysis in Claude Code?
Run npx skills add pedronauck/skills --skill architectural-analysis -a claude-code. The skill ends up in ~/.claude/skills/architectural-analysis/SKILL.md.
What does architectural-analysis do?
It audits design: dead code, duplication, type confusion and costly change patterns. Findings are verified in source, each with a minimal suggested fix.
Does it delete dead code on its own?
An audit only reads. Remediation happens if explicit authorization already exists.
