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

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
190,087 StarsApache-2.0

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
190,087 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
190,087 StarsApache-2.0

Spec Driven Development

addyosmani/agent-skills

Coding

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when drafting a PRD or requirements document with objectives and scope, or when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans sev...

reacttesting
114,322 StarsMIT

Deprecation And Migration

addyosmani/agent-skills

Coding

Manages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or suns...

typescriptsecurity
114,322 StarsMIT

Using Agent Skills

addyosmani/agent-skills

Coding

Discovers and invokes agent skills. Use when starting a session, or when you need to decide which skill or workflow applies to the piece of work at hand. This is the meta-skill that governs how all other skills are discovered and invoked.

frontendsecurity
114,322 StarsMIT