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

Improve Codebase Architecture

by sammcj in sammcj/agentic-coding

Find deepening opportunities in a codebase, informed by whatever domain language and architectural decisions are already documented in the repo.

Apache-2.0Auto-check passedDevelopment

Install Improve Codebase Architecture

skills CLI
$ npx skills add sammcj/agentic-coding --skill improve-codebase-architecture -a claude-code

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

GitHub CLI
$ gh skill install sammcj/agentic-coding 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/sammcj/agentic-coding.git skills-src && mkdir -p .claude/skills && cp -r skills-src/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
162
Token cost
~1.8k tokens
SKILL.md length
944 words
Files
5
Skills in repo
62
Repo updated
First seen
Licence
Apache-2.0

At a glance

Find deepening opportunities in a codebase, informed by whatever domain language and architectural decisions are already documented in the repo.

  • Works in 3 steps: Explore → Present candidates as an HTML report → Grilling loop
  • The user wants to improve architecture
  • SKILL.md covers Glossary and Process
  • Calls git

What it does

Improve Codebase Architecture is an agent skill from sammcj/agentic-coding. Find deepening opportunities in a codebase, informed by whatever domain language and architectural decisions are already documented in the repo. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.

Its SKILL.md is about 1.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files (for example `DEEPENING.md`, `HTML-REPORT.md` and `INTERFACE-DESIGN.md`).

It sits in Development, covering Refactoring. The repository describes itself as: Agentic Coding Rules, Templates etc... The licence is Apache-2.0.

When your agent uses it

  • The user wants to improve architecture
  • Find refactoring opportunities
  • Consolidate tightly-coupled modules
  • Make a codebase more testable and AI-navigable

Example prompts

  • “/improve-codebase-architecture”

Workflow steps

3 steps, taken from the step headings in SKILL.md.

  1. Explore
  2. Present candidates as an HTML report
  3. Grilling loop

What it can do on your machine

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

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    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 1.8k tokens when it runs. Until then it costs about 86 tokens; SKILL.md has 944 words of instructions outside code blocks.

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

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 sammcj/agentic-coding at commit 62ba5a2, republished under its Apache-2.0 licence (© sammcj). 944 words, ~1,765 tokens.

Download SKILL.mdSave it as .claude/skills/improve-codebase-architecture/SKILL.md (or your agent's skills folder). This skill also uses 4 other files; get the full folder from GitHub.
name
improve-codebase-architecture
description
Find deepening opportunities in a codebase, informed by whatever domain language and architectural decisions are already documented in the repo. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.
metadata.source
https://github.com/mattpocock/skills (adapted)

Improve Codebase Architecture

Surface architectural friction and propose deepening opportunities - refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Glossary

Use these terms exactly in every suggestion. Consistent language is the point - don't drift into "component," "service," "API," or "boundary." Full definitions in LANGUAGE.md.

  • Module - anything with an interface and an implementation (function, class, package, slice).
  • Interface - everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
  • Implementation - the code inside.
  • Depth - leverage at the interface: a lot of behaviour behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation.
  • Seam - where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.")
  • Adapter - a concrete thing satisfying an interface at a seam.
  • Leverage - what callers get from depth.
  • Locality - what maintainers get from depth: change, bugs, knowledge concentrated in one place.

Key principles (see LANGUAGE.md for the full list):

  • Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
  • The interface is the test surface.
  • One adapter = hypothetical seam. Two adapters = real seam.

This skill is informed by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.

Process

1. Explore

Scope before you scan - YAGNI. Deepening a module pays off by making future changes to it easier, so a deepening opportunity in code nobody touches is a refactor you never cash in. Decide where to look before you look:

  • If the user named a direction - a module, a subsystem, a pain point - take it and skip the inference below.
  • Otherwise, read back over the last ~20 commits (git log --oneline -20 --name-only) to find the hot spots - the files and areas that keep coming up - and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.

Read the project's domain glossary (GLOSSARY.md) and any ADRs in the area you're touching first.

Then spawn a read-only exploration sub-agent to walk the codebase (in Claude Code: the Agent tool with subagent_type=Explore). Don't follow rigid heuristics - explore organically and note where you experience friction:

  • Where does understanding one concept require bouncing between many small modules?
  • Where are modules shallow - interface 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 (no locality)?
  • Where do tightly-coupled modules leak across their seams?
  • Which parts of the codebase are untested, or hard to test through their current interface?

Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.

Show full SKILL.md (469 more words)Show less
2. Present candidates as an HTML report

Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from $TMPDIR, falling back to /tmp (or %TEMP% on Windows), and write to <tmpdir>/architecture-review-<timestamp>.html so each run gets a fresh file. Open it for the user - xdg-open <path> on Linux, open <path> on macOS, start <path> on Windows - and tell them the absolute path.

The report uses Tailwind via CDN for layout and styling, and Mermaid via CDN for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals - use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a before/after visualisation. Be visual.

For each candidate, the same template as before, but rendered as a card:

  • Files - which files/modules are involved
  • Problem - why the current architecture is causing friction
  • Solution - plain English description of what would change
  • Benefits - explained in terms of locality and leverage, and how tests would improve
  • Before / After diagram - side-by-side, custom-drawn, illustrating the shallowness and the deepening
  • Recommendation strength - one of Strong, Worth exploring, Speculative, rendered as a badge

End the report with a Top recommendation section: which candidate you'd tackle first and why.

Use GLOSSARY.md vocabulary for the domain, and LANGUAGE.md vocabulary for the architecture. If GLOSSARY.md defines "Order," talk about "the Order intake module" - not "the FooBarHandler," and not "the Order service."

ADR conflicts: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: "contradicts ADR-0007 - but worth reopening because..."). Don't list every theoretical refactor an ADR forbids.

See HTML-REPORT.md for the full HTML scaffold, diagram patterns, and styling guidance.

Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"

3. Grilling loop

Once the user picks a candidate, drop into a grilling conversation. Walk the decision tree with them - constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.

Side effects happen inline as decisions crystallize:

  • Naming a deepened module after a concept not in GLOSSARY.md? Add the term to GLOSSARY.md (create it if missing).
  • Sharpening a fuzzy term during the conversation? Update GLOSSARY.md right there.
  • User rejects the candidate with a load-bearing reason? Offer an ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing - skip ephemeral reasons ("not worth it right now") and self-evident ones.
  • Want to explore alternative interfaces for the deepened module? See INTERFACE-DESIGN.md.

© sammcj, Apache-2.0. 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 4 other files in Skills/improve-codebase-architecture of sammcj/agentic-coding.

  • SKILL.md
  • DEEPENING.md
  • HTML-REPORT.md
  • INTERFACE-DESIGN.md
  • LANGUAGE.md

Open the folder on GitHubat commit 62ba5a2

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 skillsammcj/agentic-coding162—~1.8kAutomated safety check: PassApache-2.0
Guidelinesakash-network/node1.1k22 repos~577Automated safety check: PassMIT
Component Refactoringlangflow-ai/langflow156k—~3.5kAutomated safety check: PassMIT
Migrate Core Code to Submodulestinyhumansai/openhuman42k—~2.6kAutomated safety check: PassGPL-3.0
Systematic Code Refactoringluongnv89/claude-howto42k—~3kAutomated safety check: PassMIT
Codexskills-directory/skill-codex1.5k3 repos~1.8kAutomated 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.

    42k GitHub stars~2.6k tokensUpdated today
    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 8 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

  • Ponytail

    DavidObando/gsharp

    Forces the laziest solution that actually works, simplest, shortest, most minimal.

    565 GitHub starsUsed in 8 repos~1.7k tokens
    DevelopmentAuto-check passed

More from sammcj/agentic-coding

All 62 skills in this repo

  • Yue2 Music

    sammcj/agentic-coding

    A skill your agent uses when generating songs with YuE2, covering a recording via SheetSage2 audio-to-ABC, editing a score or lyrics with melody preservation, or building a reproducible listening…

    162 GitHub stars~2.3k tokensUpdated today
    Auto-check passed

  • Bento Slides

    sammcj/agentic-coding

    A skill your agent uses when creating or editing Bento (.bento.html) slide decks, including any request for a single-file HTML slide deck.

    162 GitHub stars~2.9k tokensUpdated today
    Auto-check passed

  • Idrive Backup

    sammcj/agentic-coding

    A skill your agent uses whenever the user wants you to manage, discuss or diagnose iDrive Backup configuration on macOS

    162 GitHub stars~1.7k tokensUpdated today
    Auto-check: notes

  • Piper Tts Training

    sammcj/agentic-coding

    Train custom TTS voices for Piper (ONNX format) using fine-tuning or from-scratch approaches.

    162 GitHub stars~1.4k tokensUpdated today
    Auto-check passed

  • PPTX To Md

    sammcj/agentic-coding

    Convert a PPTX slide deck into per-slide markdown that preserves both the verbatim text and the meaning of embedded screenshots, diagrams and charts in their original layout positions.

    162 GitHub stars~1.8k tokensUpdated today
    Auto-check passed

  • Skill Creator Primer

    sammcj/agentic-coding

    You MUST load this skill before the skill-creator skill AND before making ANY change to, or conducting a review of ANY Agent Skill.

    162 GitHub stars~9.8k tokensUpdated today
    Auto-check passed

Categories

Questions about Improve Codebase Architecture

What does Improve Codebase Architecture do?

Find deepening opportunities in a codebase, informed by whatever domain language and architectural decisions are already documented in the repo. Improve Codebase Architecture is an agent skill from sammcj/agentic-coding. Find deepening opportunities in a codebase, informed by whatever domain language and architectural decisions are already documented in the repo.

When should I use Improve Codebase Architecture?

Improve Codebase Architecture fits situations like: the user wants to improve architecture; find refactoring opportunities; consolidate tightly-coupled modules; make a codebase more testable and AI-navigable.

How do I install Improve Codebase Architecture in Claude Code?

Run `npx skills add sammcj/agentic-coding --skill improve-codebase-architecture -a claude-code`. Or copy the skill folder (Skills/improve-codebase-architecture in sammcj/agentic-coding) 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 sammcj/agentic-coding --skill improve-codebase-architecture -a codex`. Or copy the skill folder (Skills/improve-codebase-architecture in sammcj/agentic-coding) 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 sammcj/agentic-coding --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?

Going by SKILL.md and its folder, Improve Codebase Architecture needs the command-line tools its instructions call (git).

Does Improve Codebase Architecture access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. 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 Apache-2.0 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 1.8k tokens (SKILL.md is roughly 7.1k 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, 42k stars) and Systematic Code Refactoring (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 Improve Codebase Architecture?

sammcj (a GitHub user) maintains it in sammcj/agentic-coding, which has 162 GitHub stars. The repository holds 62 skills in this directory. The repository was last updated on October 7, 2026.

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