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

Codebase Design

by stevesolun in stevesolun/ctx

Design or improve module interfaces using deep-module heuristics.

MITAuto-check passed

Install Codebase Design

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

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

GitHub CLI
$ gh skill install stevesolun/ctx codebase-design --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/codebase-design .claude/skills/codebase-design && 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
codebase-design
GitHub stars
588
Token cost
~662 tokens
SKILL.md length
304 words
Files
4
Skills in repo
26
Repo updated
First seen
Licence
MIT

At a glance

Design or improve module interfaces using deep-module heuristics.

  • Works in 5 steps: Map representative callers,… → Look for coordination or policy that can… → Place seams where variation, ownership,… → …
  • Deciding where a seam belongs
  • SKILL.md covers Working vocabulary, Design workflow and Heuristics, not laws
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Codebase Design is an agent skill from stevesolun/ctx. Design or improve module interfaces using deep-module heuristics. Use when deciding where a seam belongs, reducing caller-facing complexity, improving testability or navigability, or comparing module designs.

Its SKILL.md is about 660 tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files (for example `DEEPENING.md`, `DESIGN-IT-TWICE.md` and `agents/openai.yaml`).

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

  • Deciding where a seam belongs
  • Reducing caller-facing complexity
  • Improving testability
  • Comparing module designs

Example prompts

  • “/codebase-design”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Map representative callers, responsibilities, dependencies, and existing
  2. Look for coordination or policy that can move behind a smaller interface.
  3. Place seams where variation, ownership, or test isolation justifies them.
  4. Compare alternatives when the choice is consequential.
  5. Validate the candidate with representative caller code and tests.

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

Codebase Design loads about 662 tokens when it runs. Until then it costs about 56 tokens; SKILL.md has 304 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
~662

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). 304 words, ~662 tokens.

Download SKILL.mdSave it as .claude/skills/codebase-design/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
name
codebase-design
description
Design or improve module interfaces using deep-module heuristics. Use when deciding where a seam belongs, reducing caller-facing complexity, improving testability or navigability, or comparing module designs.

Codebase Design

Seek deep modules: substantial useful behavior behind a small, stable interface. Use the concepts below as design lenses, while matching the repository's established domain language.

Working vocabulary

  • Module: a coherent unit with an interface and implementation, at any scale.
  • Interface: everything callers must know, including invariants and failure modes—not just a type signature.
  • Seam: a location where behavior can vary without editing its callers.
  • Adapter: an implementation that connects at a seam.
  • Depth: useful capability relative to interface complexity.
  • Leverage: capability gained by callers; locality: change and knowledge concentrated for maintainers.

Translate these terms to the project's vocabulary when that makes the design clearer. Consistency with the codebase is more valuable than enforcing a private lexicon.

Design workflow

  1. Map representative callers, responsibilities, dependencies, and existing contracts.
  2. Look for coordination or policy that can move behind a smaller interface.
  3. Place seams where variation, ownership, or test isolation justifies them.
  4. Compare alternatives when the choice is consequential.
  5. Validate the candidate with representative caller code and tests.

Heuristics, not laws

  • Reduce methods, parameters, ordering constraints, and configuration callers must understand.
  • Use the deletion test: if removing a module merely spreads its complexity across callers, it was likely earning its keep.
  • Treat pass-through layers skeptically, but keep them when they provide a real compatibility, ownership, policy, or navigation boundary.
  • Introduce dependency seams when actual variation or test isolation repays the indirection; avoid interfaces justified only by hypothetical futures.
  • Prefer tests through observable interfaces, while allowing focused internal tests when they provide cheaper or more precise feedback.
  • Favor explicit dependencies and returned results when they improve control and testability; side effects and internally created dependencies can still be appropriate at well-defined boundaries.

Read DEEPENING.md when consolidating a cluster across dependency boundaries. Read DESIGN-IT-TWICE.md when materially different interface designs can be explored independently.

© 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 3 other files in .agents/skills/codebase-design of stevesolun/ctx.

  • SKILL.md
  • DEEPENING.md
  • DESIGN-IT-TWICE.md
  • agents/openai.yaml

Open the folder on GitHubat commit 11b582a

Compare with similar skills

Codebase Design 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.

Codebase Design compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Codebase Design this skillstevesolun/ctx588—~662Automated safety check: PassMIT
Network Interface Healthaffaan-m/ECC275k1 repos~1.4kAutomated safety check: PassMIT
Es Modulesthedaviddias/Front-End-Checklist74k—~482Automated safety check: PassMIT
Make Interfaces Feel Betteraffaan-m/ECC275k1 repos~1.2kAutomated safety check: PassMIT
Skill Improversickn33/agentic-awesome-skills47k2 repos~1.5kAutomated safety check: PassMIT
Splitting Oversized ModulesPostHog/posthog40k—~2.2kAutomated safety check: PassCustom licence

Similar skills

  • Network Interface Health

    affaan-m/ECC

    Diagnose interface errors, drops, CRCs, duplex mismatches, flapping, speed negotiation issues, and counter trends on routers, switches, and Linux hosts.

    275k GitHub starsUsed in 1 repo~1.4k tokens
    Auto-check passed

  • Es Modules

    thedaviddias/Front-End-Checklist

    A skill your agent uses when reviewing scripts, client components, bundles, or runtime behavior related to Use ES modules (import/export).

    74k GitHub stars~482 tokensUpdated yesterday
    Auto-check passed

  • Make Interfaces Feel Better

    affaan-m/ECC

    Apply concrete design-engineering details that make interfaces feel polished.

    275k GitHub starsUsed in 1 repo~1.2k tokens
    Frontend & DesignAuto-check passed

  • Skill Improver

    sickn33/agentic-awesome-skills

    Iteratively improve a Claude Code skill using the skill-reviewer agent until it meets quality standards.

    47k GitHub starsUsed in 2 repos~1.5k tokens
    Agent WorkflowsAuto-check passed

  • Splitting Oversized Modules

    PostHog/posthog

    Official

    Split an oversized Python module (a thousand-plus-line logic.py, models.py, api.py, or its test file) into a package of one module per concern, mechanically and provably without changing behavior.

    40k GitHub stars~2.2k tokensUpdated today
    Frontend & DesignAuto-check passed

  • Abp Module

    abpframework/abp

    ABP reusable Module solution template - EF Core + MongoDB dual support, virtual methods for extensibility, DbTablePrefix, module options pattern, entity extension, separate connection string.

    14k GitHub stars~1.6k tokensUpdated today
    DatabasesAuto-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

  • Lat Md Knowledge Graph

    stevesolun/ctx

    Design or audit a repo-local markdown knowledge graph with wiki links, source-code backlinks, drift checks, and searchable sections.

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

Questions about Codebase Design

What does Codebase Design do?

Design or improve module interfaces using deep-module heuristics. Codebase Design is an agent skill from stevesolun/ctx. Design or improve module interfaces using deep-module heuristics.

When should I use Codebase Design?

Codebase Design fits situations like: deciding where a seam belongs; reducing caller-facing complexity; improving testability; comparing module designs.

How do I install Codebase Design in Claude Code?

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

How do I install Codebase Design in Codex?

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

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

What does Codebase Design need to run?

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

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

Codebase Design 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 Codebase Design use?

About 662 tokens (SKILL.md is roughly 2.6k 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 Codebase Design?

Skills that share tags, products or a category with Codebase Design: Network Interface Health (affaan-m/ECC, 275k stars), Es Modules (thedaviddias/Front-End-Checklist, 74k stars), Make Interfaces Feel Better (affaan-m/ECC, 275k stars) and Skill Improver (sickn33/agentic-awesome-skills, 47k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Codebase Design?

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.