Improve architecture

Skill arndvs/ctrlshft/skills/improve-architecture

Explore the codebase for architectural improvements using deep module analysis. Use when asked to 'improve architecture', 'improve codebase', 'find shallow modules', 'refactor architecture', or for periodic codebase health checks.From its SKILL.md

Install

npx -y skills add arndvs/ctrlshft --skill improve-architecture

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.2 KB, 399 tokens by cl100k_base, as published. Nobody here has run it

Improve Codebase Architecture

If running interactively (human present), output "Read Improve Codebase Architecture skill." to acknowledge. If running with --dangerously-skip-permissions (AFK/unattended), skip acknowledgement and proceed directly.

A deep module has a small interface hiding a large implementation. This skill finds opportunities to deepen your codebase.

Process

1. Explore

Use subagents to explore the codebase organically. Note where you experience friction:

Where does understanding one concept require bouncing between multiple small files?
Where are modules so shallow that the interface is nearly as complex as the implementation?
Where have pure functions been extracted just for testability, but the real bugs hide in how they're called?
Where do tightly coupled modules create integration risk at the seams between them?

2. Present Candidates

Present 3-5 clusters of shallow modules that should be deepened. For each candidate, explain:

Which files/modules are involved
Why they're coupled together
What friction they create

Do not propose interface designs yet. Let the user pick which candidate to explore.

3. Design Multiple Interfaces

Once the user picks a candidate, spawn multiple subagents in parallel. Each should produce a radically different interface design for the deepened module. Aim for 3 diverse options that trade off complexity, testability, and caller convenience differently.

4. Recommend

Present all designs. Recommend which design is strongest and why. If elements from different designs combine well, propose a hybrid.

5. Create RFC

Once the user accepts a design, create a GitHub issue as a refactor RFC describing the current state, proposed interface, migration path, and affected files.

Handoff

If context is high at any step, follow the standard handoff protocol (@~/dotfiles/instructions/handoff.instructions.md) — persist analysis and current progress to working/ and provide the pickup command.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most architecture codebase skills give in 399 tokens

Counted across 811 of the 1,134 authors here whose files we hold, read 2026-08-07

Ask the user which candidate to explorein 45 of 811, across 15 files
Apply the deletion test to suspected shallow modulesin 43 of 811, across 15 files
Read any relevant architecture decision records firstin 31 of 811, across 8 files
Use exact glossary terms in every suggestionin 30 of 811, across 10 files
Accept dependencies instead of creating themin 24 of 811, across 5 files
Include before and after visualisations for each candidatein 24 of 811, across 5 files
Read the domain glossary before exploringin 24 of 811, across 6 files
Return results instead of producing side effectsin 23 of 811, across 4 files
Explore the codebase for shallow modules and frictionin 23 of 811, across 3 files
Introduce seams only where things varyin 22 of 811, across 3 files
Reduce the number of methodsin 21 of 811, across 2 files
Design deep modules with small interfacesin 21 of 811, across 3 files

Said here and by no other author read

acknowledge the skill when running interactively
skip acknowledgement when running unattended
present three to five shallow module candidates
generate multiple diverse interface designs in parallel
create a refactor RFC issue after design approval
follow handoff protocol if context is high

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.