{
  "id": "improve-codebase-architecture",
  "handle": "improve-codebase-architecture",
  "canonicalUrl": "https://bestskillsforclaude.com/en/skills/improve-codebase-architecture",
  "language": "en",
  "alternates": {
    "en": "https://bestskillsforclaude.com/en/skills/improve-codebase-architecture",
    "es": "https://bestskillsforclaude.com/es/skills/improve-codebase-architecture",
    "pt-BR": "https://bestskillsforclaude.com/pt-br/skills/improve-codebase-architecture",
    "ja": "https://bestskillsforclaude.com/ja/skills/improve-codebase-architecture"
  },
  "category": {
    "id": "build-and-ship",
    "name": "Build and ship"
  },
  "publisher": {
    "name": "Matt Pocock",
    "url": "https://github.com/mattpocock"
  },
  "source": "https://github.com/mattpocock/skills",
  "documentation": null,
  "licenseAsStated": "MIT",
  "runtime": "Claude Code and agents that support the skills CLI",
  "lastReviewed": "2026-08-05",
  "headline": "Can an agent tell you where your architecture actually hurts?",
  "summary": "It can produce candidates. Choosing which ones matter is still your call.",
  "verdict": "The improve-codebase-architecture skill scans a codebase for opportunities to simplify and deepen modules, presents the findings as a report, and only then explores the candidates you select. The staged shape is the point: it is a diagnosis tool that refuses to start rewriting before you have chosen.",
  "bestFor": "Codebases that grew fast and now leak details between modules.",
  "skipIf": "The project is small enough that you already know exactly where the problems are.",
  "keyTakeaways": [
    "Report first, change later. That order is what makes it safe to run.",
    "Scope it to a subsystem, because a whole repository report is too big to act on.",
    "Findings are candidates, not verdicts. Some will be wrong for reasons only your team knows.",
    "It pairs with grill-me when you want the reasoning stress tested before you commit."
  ],
  "quickStart": [
    "Install it with the skills CLI from mattpocock/skills, published under MIT.",
    "Run it on one area rather than the whole repository, so the report stays reviewable.",
    "Pick one or two candidates. A list of thirty findings is a way of choosing nothing."
  ],
  "sections": [
    {
      "heading": "What it changes in practice",
      "paragraphs": [
        "Architecture work usually fails for social rather than technical reasons: nobody can agree on where to start, so nothing starts. A concrete list of candidates with reasons attached turns that argument into a decision.",
        "Presenting findings as a report also keeps the agent from doing the most dangerous thing available, which is refactoring several modules at once while you watch."
      ]
    },
    {
      "heading": "Where it disappoints",
      "paragraphs": [
        "It sees the code, not the history. Some awkward boundaries exist because of a constraint that is not written down anywhere, and the skill will confidently propose removing them.",
        "Large reports also invite scope creep. The discipline of picking one candidate is entirely on you."
      ]
    }
  ],
  "faq": [
    {
      "question": "Does it change code automatically?",
      "answer": "It reports first and explores the candidates you select, rather than refactoring on sight."
    },
    {
      "question": "How large a codebase can it handle?",
      "answer": "Scope it to a subsystem. Whole repository reports tend to be too large to act on."
    },
    {
      "question": "Who maintains it?",
      "answer": "Matt Pocock, in his public skills repository under the MIT license."
    }
  ],
  "sources": [
    {
      "label": "mattpocock/skills on GitHub",
      "url": "https://github.com/mattpocock/skills",
      "kind": "repository"
    },
    {
      "label": "Agent skills directory listing",
      "url": "https://skills.sh",
      "kind": "directory"
    }
  ],
  "machineReadable": {
    "markdown": "https://bestskillsforclaude.com/en/skills/improve-codebase-architecture/content.md",
    "json": "https://bestskillsforclaude.com/en/skills/improve-codebase-architecture/skill.json"
  },
  "disclosure": "Editorial desk review based on the publisher's own repository. Not a security audit, a benchmark or a guarantee of maintenance."
}