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
Install Notes
# Review source first
open https://github.com/mxyhi/ok-skills/blob/main/improve-codebase-architecture/SKILL.mdCopy 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
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 API
anthropics/skills
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...
MCP Builder
anthropics/skills
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).
Source Driven Development
addyosmani/agent-skills
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.
Incremental Implementation
addyosmani/agent-skills
Delivers changes incrementally in thin, verifiable slices. Use when implementing any feature or change that touches more than one file, or when picking up the next task from a plan. Use when rolling a change out behind a feature flag, when you're about to write a large amount of code at once, or when a task feels to...
Using Agent Skills
addyosmani/agent-skills
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.