Improve Codebase Architecture

Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable.

Overview

The Improve Codebase Architecture skill, found within the mxyhi/ok-skills repository, enables AI agents to evaluate software structures for technical debt and design inconsistencies. By synthesizing information from domain-specific documentation in CONTEXT.md and historical architectural decision records in the docs/adr/ folder, the skill identifies specific areas for refactoring. It is particularly effective for consolidating tightly-coupled modules and improving the overall testability of a project. This tool helps ensure that codebases remain navigable for both developers and AI models. Part of a repository with 423 stars, this skill supports various agents including Claude, Cursor, and Codex, focusing on aligning implementation with established project standards.

Use Cases

Consolidating tightly-coupled modules to improve modularity and separation of concerns.
Identifying refactoring opportunities based on historical architectural decision records.
Enhancing codebase navigability and testability for automated AI development agents.

Install Notes

# Review source first
open https://github.com/mxyhi/ok-skills/blob/main/improve-codebase-architecture/SKILL.md

Copy or clone the skill folder into your agent skills directory after reviewing its instructions and scripts.

Security Notes

This skill requires read access to project documentation and architectural records to provide informed recommendations. Users should verify that CONTEXT.md and ADR files do not contain sensitive information or hardcoded credentials. The skill's functionality is limited to codebase analysis and does not specify additional external execution permissions.

Related Skills

MCP Builder

anthropics/skills

Coding

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

CodexClaude
typescriptpython
176,191 StarsApache-2.0

Claude API

anthropics/skills

Coding

Reference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthr...

Claude CodeClaude
typescriptpython
176,191 StarsApache-2.0

Skill Creator

anthropics/skills

Coding

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

Claude CodeClaude
pythondesign
176,191 StarsApache-2.0

Shipping And Launch

addyosmani/agent-skills

Coding

Prepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.

typescriptjavascript
94,159 StarsMIT

Source Driven Development

addyosmani/agent-skills

Coding

Grounds every implementation decision in official documentation. Use when you want to verify an approach against the official docs before implementing it, or when you want authoritative, source-cited code free from outdated patterns. Use when building with any framework or library where correctness matters.

typescriptpython
94,159 StarsMIT

Code Simplification

addyosmani/agent-skills

Coding

Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.

Claude CodeClaude
typescriptjavascript
94,159 StarsMIT