New: 97,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

Improve Codebase Architecture

by stevesolun in stevesolun/ctx

Analyze a codebase for high-leverage architectural improvements and explain evidence, tradeoffs, and next steps.

MITAuto-check passedDevelopment

Install Improve Codebase Architecture

skills CLI
$ npx skills add stevesolun/ctx --skill improve-codebase-architecture -a claude-code

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

GitHub CLI
$ gh skill install stevesolun/ctx improve-codebase-architecture --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/stevesolun/ctx.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/improve-codebase-architecture .claude/skills/improve-codebase-architecture && 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
improve-codebase-architecture
GitHub stars
588
Token cost
~621 tokens
SKILL.md length
311 words
Files
3
Skills in repo
26
Repo updated
First seen
Licence
MIT

At a glance

Analyze a codebase for high-leverage architectural improvements and explain evidence, tradeoffs, and next steps.

  • Tasks that involve Refactoring
  • SKILL.md covers Scope the investigation, Find evidence and Present candidates
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Improve Codebase Architecture is an agent skill from stevesolun/ctx. Analyze a codebase for high-leverage architectural improvements and explain evidence, tradeoffs, and next steps. Use explicitly for architecture audits or deep-module refactoring opportunities.

Its SKILL.md is about 620 tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files (for example `HTML-REPORT.md` and `agents/openai.yaml`).

It sits in Development, covering Refactoring. The repository describes itself as: CTX Fit finds the cheapest AI coding setup that reliably works on your repository, then applies the winner as a reviewable change. The licence is MIT.

When your agent uses it

  • Tasks that involve Refactoring

Example prompts

  • “/improve-codebase-architecture”

What it can do on your machine

Read from SKILL.md and the folder at commit 11b582a. 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

Improve Codebase Architecture loads about 621 tokens when it runs. Until then it costs about 56 tokens; SKILL.md has 311 words of instructions outside code blocks.

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

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 stevesolun/ctx at commit 11b582a, republished under its MIT licence (© stevesolun). 311 words, ~621 tokens.

Download SKILL.mdSave it as .claude/skills/improve-codebase-architecture/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
improve-codebase-architecture
description
Analyze a codebase for high-leverage architectural improvements and explain evidence, tradeoffs, and next steps. Use explicitly for architecture audits or deep-module refactoring opportunities.

Improve Codebase Architecture

Look for architectural friction that a focused structural change could reduce. Favor improvements that shrink interfaces, concentrate related complexity, and make important behavior easier to test and understand.

Scope the investigation

Follow the user's named subsystem or pain point. Otherwise use recent changes, repeated maintenance friction, test difficulty, or dependency structure to select a useful area. Read relevant domain language and ADRs when present so recommendations respect intentional boundaries.

Use the codebase-design skill when its deep-module vocabulary will sharpen the analysis. Explore independently in parallel only when the repository is large enough to benefit and the lanes do not duplicate work.

Find evidence

Consider:

  • interfaces that expose nearly as much complexity as their implementations;
  • behavior spread across modules that change together;
  • dependency seams that leak internal details;
  • testing that bypasses the real call path because no stable seam exists; and
  • repeated wrappers or indirection that add little leverage.

Treat these as prompts for investigation, not violations. Apply the deletion test where useful: would removing a layer concentrate complexity behind a better interface, or merely move it elsewhere?

Present candidates

For each material candidate, cite the affected code and explain:

  • the observed friction;
  • the structural change being considered;
  • expected benefits and tradeoffs;
  • evidence that the seam is real rather than hypothetical;
  • test impact and migration risk; and
  • conflicts with existing decisions.

Rank recommendations by evidence and likely leverage. Keep speculative ideas clearly labeled and avoid proposing a wide refactor solely for aesthetic consistency.

Use prose, a compact table, or diagrams according to what best communicates the relationships. When a visual HTML artifact is useful and authorized, load the HTML report guide.

Explore a selected candidate further only when the user requests it or the current task includes design. Update domain records or ADRs only when those artifacts are in scope and the decision is durable enough to justify them.

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

Files

SKILL.md and 2 other files in .agents/skills/improve-codebase-architecture of stevesolun/ctx.

  • SKILL.md
  • HTML-REPORT.md
  • agents/openai.yaml

Open the folder on GitHubat commit 11b582a

Compare with similar skills

Improve Codebase Architecture 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.

Improve Codebase Architecture compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Improve Codebase Architecture this skillstevesolun/ctx588—~621Automated safety check: PassMIT
Guidelinesakash-network/node1.1k22 repos~577Automated safety check: PassMIT
Component Refactoringlangflow-ai/langflow156k—~3.5kAutomated safety check: PassMIT
Migrate Core Code to Submodulestinyhumansai/openhuman41k—~2.6kAutomated safety check: PassGPL-3.0
ast-grep Structural Searchcode-yeongyu/oh-my-openagent70k—~3.3kAutomated safety check: PassMIT
Systematic Code Refactoringluongnv89/claude-howto42k—~3kAutomated safety check: PassMIT

Similar skills

  • Guidelines

    akash-network/node

    Behavioral guidelines to reduce common LLM coding mistakes. An agent skill from akash-network/node.

    1.1k GitHub starsUsed in 22 repos~577 tokens
    DevelopmentAuto-check passed

  • Component Refactoring

    langflow-ai/langflow

    Refactor high-complexity React components in Langflow frontend.

    156k GitHub stars~3.5k tokensUpdated today
    DevelopmentAuto-check passed

  • Migrate Core Code to Submodules

    tinyhumansai/openhuman

    Plans and carries out moving non-host-specific code and its tests from the OpenHuman core into vendored tiny submodule libraries, then releases the submodule and re-pins the host.

    41k GitHub stars~2.6k tokensUpdated yesterday
    DevelopmentAuto-check passed

  • ast-grep Structural Search

    code-yeongyu/oh-my-openagent

    Searches and rewrites code by syntax-tree shape across 25 languages with ast-grep, for codemods, structural queries and YAML lint rules, using a Python wrapper script.

    70k GitHub stars~3.3k tokensUpdated yesterday
    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 7 days ago
    DevelopmentAuto-check passed

  • Codex

    skills-directory/skill-codex

    A skill your agent uses when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing

    1.5k GitHub starsUsed in 3 repos~1.8k tokens
    DevelopmentAuto-check passed

More from stevesolun/ctx

All 26 skills in this repo

  • Diagnosing Bugs

    stevesolun/ctx

    Diagnose hard bugs and performance regressions with reproducible evidence, focused hypotheses, and proportional instrumentation.

    588 GitHub stars~596 tokensUpdated 4 days ago
    Auto-check passed

  • Repo Stats Autoupdate

    stevesolun/ctx

    Keeps README badge + inline counts in sync with the real number of skills, agents, graph nodes/edges, communities, converted pipelines, and test inventory.

    588 GitHub stars~724 tokensUpdated 4 days ago
    Auto-check passed

  • Code Review

    stevesolun/ctx

    Review a Git diff against repository standards and its originating requirements.

    588 GitHub stars~466 tokensUpdated 4 days ago
    Auto-check passed

  • No Mistakes

    stevesolun/ctx

    Validate committed feature-branch changes through the no-mistakes pipeline: intent, rebase, review, test, docs, lint, push, PR, and CI.

    588 GitHub stars~458 tokensUpdated 4 days ago
    Auto-check passed

  • Skill Router

    stevesolun/ctx

    Repo-aware recommendation manager for ctx. An agent skill from stevesolun/ctx.

    588 GitHub stars~2.4k tokensUpdated 4 days ago
    Auto-check passed

  • Codebase Design

    stevesolun/ctx

    Design or improve module interfaces using deep-module heuristics.

    588 GitHub stars~662 tokensUpdated 4 days ago
    Auto-check passed

Categories

Questions about Improve Codebase Architecture

What does Improve Codebase Architecture do?

Analyze a codebase for high-leverage architectural improvements and explain evidence, tradeoffs, and next steps. Improve Codebase Architecture is an agent skill from stevesolun/ctx. Analyze a codebase for high-leverage architectural improvements and explain evidence, tradeoffs, and next steps.

When should I use Improve Codebase Architecture?

Improve Codebase Architecture fits situations like: tasks that involve Refactoring.

How do I install Improve Codebase Architecture in Claude Code?

Run `npx skills add stevesolun/ctx --skill improve-codebase-architecture -a claude-code`. Or copy the skill folder (.agents/skills/improve-codebase-architecture in stevesolun/ctx) into .claude/skills/improve-codebase-architecture in your project. Claude Code loads it when a task matches its description.

How do I install Improve Codebase Architecture in Codex?

Run `npx skills add stevesolun/ctx --skill improve-codebase-architecture -a codex`. Or copy the skill folder (.agents/skills/improve-codebase-architecture in stevesolun/ctx) into .agents/skills/improve-codebase-architecture in your project. Codex loads it when a task matches its description.

Can I use Improve Codebase Architecture 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 stevesolun/ctx --skill improve-codebase-architecture -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/improve-codebase-architecture, .gemini/skills/improve-codebase-architecture, .github/skills/improve-codebase-architecture and .opencode/skills/improve-codebase-architecture in your project.

What does Improve Codebase Architecture need to run?

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

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

Improve Codebase Architecture 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 Improve Codebase Architecture use?

About 621 tokens (SKILL.md is roughly 2.5k 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 Improve Codebase Architecture?

Skills that share tags, products or a category with Improve Codebase Architecture: Guidelines (akash-network/node, 1.1k stars), Component Refactoring (langflow-ai/langflow, 156k stars), Migrate Core Code to Submodules (tinyhumansai/openhuman, 41k stars) and ast-grep Structural Search (code-yeongyu/oh-my-openagent, 70k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Improve Codebase Architecture?

stevesolun (a GitHub user) maintains it in stevesolun/ctx, which has 588 GitHub stars. The repository holds 26 skills in this directory. The repository was last updated on October 4, 2026.

Source: stevesolun/ctx on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.