About

Imported from akillness/jeo-skills (.agent-skills/improve-codebase-architecture/SKILL.md). Install upstream with npx skills add akillness/jeo-skills --skill improve-codebase-architecture. Copyright stays with the author.

Improve Codebase Architecture

Name: improve-codebase-architecture
Author: akillness

Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. Goal: testability and AI-navigability.

Vocabulary (use these terms exactly)

Module — anything with an interface and implementation (function, class, package, slice)
Interface — everything a caller must know: types, invariants, error modes, ordering, config
Depth — leverage at the interface: much behavior behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation
Seam — where an interface lives; a place behavior can be altered without editing in place
Adapter — a concrete thing satisfying an interface at a seam
Leverage — what callers get from depth
Locality — what maintainers get from depth: change, bugs, knowledge concentrated in one place

Key principles:

Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
The interface is the test surface.
One adapter = hypothetical seam. Two adapters = real seam.

When to use this skill

User wants architectural improvement opportunities
Codebase is hard to navigate or test
Modules feel tightly coupled or shallow
Refactoring would improve testability

When not to use this skill

Quick targeted refactors → use code-refactoring
Design review of a plan → use grill-with-docs
Implementation tickets → use to-issues

Process

1. Explore

Read domain glossary (CONTEXT.md) and ADRs first. Then walk the codebase organically, noting friction:

Where does understanding one concept require bouncing between many small modules?
Where are modules shallow — interface nearly as complex as the implementation?
Where have pure functions been extracted for testability, but real bugs hide in how they're called?
Where do tightly-coupled modules leak across seams?
Which parts are untested or hard to test through their current interface?

Apply the deletion test to suspected shallow modules.

2. Present candidates

Numbered list of deepening opportunities. For each:

Files — which files/modules are involved
Problem — why the current architecture causes friction
Solution — plain English description of what would change
Benefits — in terms of locality, leverage, and test improvement

Use CONTEXT.md vocabulary for domain terms. Use the vocabulary above for architecture terms.

ADR conflicts: if a candidate contradicts an ADR, only surface it when friction is real enough to warrant revisiting. Mark clearly: "contradicts ADR-0007 — but worth reopening because…"

Ask: "Which of these would you like to explore?" — do NOT propose interfaces yet.

3. Grilling loop

Once user picks a candidate, drop into a grilling conversation. Walk the design tree: constraints, dependencies, module shape, what sits behind the seam, what tests survive.

Side effects as decisions crystallize:

New concept not in CONTEXT.md? Add the term immediately
Fuzzy term sharpened? Update CONTEXT.md right there
User rejects with a load-bearing reason? Offer an ADR (only when a future explorer would need it to avoid re-suggesting the same thing)

Instructions

Identify the task trigger and expected output.
Follow the workflow steps in this skill from top to bottom.
Validate outputs before moving to the next step.
Capture blockers and fallback path if any step fails.

Examples

Example: Apply this skill to a small scope first, then scale to full scope after validation passes.

Best practices

Keep outputs deterministic and auditable.
Prefer small reversible changes over broad risky edits.
Record assumptions explicitly.

References

Project standards: .agent-skills/skill-standardization/SKILL.md
Validator script: .agent-skills/skill-standardization/scripts/validate_skill.sh

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/akillness-jeo-skills-improve-codebase-architecture/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

akillness-jeo-skills-improve-codebase-architecture.ocm.jsonjson

{
  "ocm": "1",
  "id": "akillness-jeo-skills-improve-codebase-architecture",
  "kind": "skill",
  "name": "improve-codebase-architecture",
  "description": "Identify architectural friction and propose deepening opportunities for testability using deletion-test, seam, locality vocabulary",
  "publisher": "akillness",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "architecture",
      "refactoring",
      "deep-modules",
      "testability",
      "locality",
      "leverage",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Identify architectural friction and propose deepening opportunities for testability using deletion-test, seam, locality vocabulary"
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/akillness/jeo-skills",
      "path": ".agent-skills/improve-codebase-architecture/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/akillness/jeo-skills/blob/HEAD/.agent-skills/improve-codebase-architecture/SKILL.md",
      "key": "akillness/jeo-skills/.agent-skills/improve-codebase-architecture/SKILL.md"
    },
    "compatibility": "Works best in codebases with CONTEXT.md domain documentation. Creates CONTEXT.md lazily when absent. Pairs with grill-with-docs for terminology refinement and code-refactoring for implementation.\n",
    "allowed_tools": [
      "Read",
      "Grep",
      "Glob",
      "Bash",
      "Write",
      "Edit"
    ]
  },
  "instructions": "# Improve Codebase Architecture\n\nSurface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. Goal: testability and AI-navigability.\n\n## Vocabulary (use these terms exactly)\n\n- **Module** — anything with an interface and implementation (function, class, package, slice)\n- **Interface** — everything a caller must know: types, invariants, error modes, ordering, config\n- **Depth** — leverage at the interface: much behavior behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementati",
  "cost": {
    "context_tokens": 1011
  }
}

Fetch it by URL: GET /api/v1/registry/akillness-jeo-skills-improve-codebase-architecture/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.