New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Architecture Review

by assafkip in assafkip/kipi-system

Surfaces architectural friction in real code — shallow modules, tight coupling, untested seams — and proposes deepening refactors using Ousterhout's deep-module principle (small interface hiding a…

MITAuto-check passedDevelopment

Install Architecture Review

skills CLI
$ npx skills add assafkip/kipi-system --skill architecture-review -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install assafkip/kipi-system architecture-review --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/assafkip/kipi-system.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/kipi-core/skills/architecture-review .claude/skills/architecture-review && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
architecture-review
GitHub stars
112
Token cost
~817 tokens
SKILL.md length
384 words
Files
2 (incl. references)
Skills in repo
14
Repo updated
First seen
Licence
MIT

At a glance

Surfaces architectural friction in real code — shallow modules, tight coupling, untested seams — and proposes deepening refactors using Ousterhout's deep-module principle (small interface hiding a…

  • Works in 5 steps: Explore. Spawn an Agent with… → Classify with the lens. For each module… → Propose, don't prescribe. For each real… → …
  • The founder says architecture review
  • SKILL.md covers Before running, Scope check (do this first), Process and Vocabulary discipline, plus 1 more section
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Architecture Review is an agent skill from assafkip/kipi-system. Surfaces architectural friction in real code — shallow modules, tight coupling, untested seams — and proposes deepening refactors using Ousterhout's deep-module principle (small interface hiding a large implementation). Use when the founder says 'architecture review', 'find shallow modules', 'architectural friction', 'deep module analysis', or asks for refactor recommendations on a directory of code. Scope it to actual code (plugins/, q-system/.q-system/scripts/) — not markdown rules, canonical files, or prose.

Its SKILL.md is about 820 tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including reference files (for example `references/deep-module-lens.md`).

It sits in Development, covering Software architecture and Refactoring. It works with Python. The repository describes itself as: Your AI brain, externalized. It remembers everything you do, then becomes whatever role you need. Same skeleton can run as your chief of staff, lawyer, PM, or investigator. Plain… The licence is MIT.

When your agent uses it

  • The founder says architecture review
  • Find shallow modules
  • Architectural friction
  • Deep module analysis

Example prompts

  • “architecture review”
  • “find shallow modules”
  • “architectural friction”
  • “/architecture-review”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. Explore. Spawn an Agent with subagent_type: Explore over the
  2. Classify with the lens. For each module the Explore pass surfaced,
  3. Propose, don't prescribe. For each real finding, sketch 1-2 concrete
  4. Write it up, don't file it. Output goes to
  5. No findings is a valid outcome. Say so plainly if the target directory

What it can do on your machine

Read from SKILL.md and the folder at commit 16d4724. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Architecture Review loads about 817 tokens when it runs, and up to ~1.5k if it reads all its reference files. Until then it costs about 134 tokens; SKILL.md has 384 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~134
When it runs · the whole SKILL.md, loaded when a task matches
~817
With references · SKILL.md plus every file in references/, read only if the agent opens them
~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from assafkip/kipi-system at commit 16d4724, republished under its MIT licence (© assafkip). 384 words, ~817 tokens.

Download SKILL.mdSave it as .claude/skills/architecture-review/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
architecture-review
description
Surfaces architectural friction in real code — shallow modules, tight coupling, untested seams — and proposes deepening refactors using Ousterhout's deep-module principle (small interface hiding a large implementation). Use when the founder says 'architecture review', 'find shallow modules', 'architectural friction', 'deep module analysis', or asks for refactor recommendations on a directory of code. Scope it to actual code (plugins/, q-system/.q-system/scripts/) — not markdown rules, canonical files, or prose.

Architecture Review Skill

Finds code that is hard to change and proposes a smaller-interface, bigger- implementation redesign. This is a judgment skill — no paired hook, same posture as research-mode in skill-hook-pairing.md.

Before running

Read references/deep-module-lens.md. It is the classification lens the review applies to every module it looks at — do not improvise a different one.

Scope check (do this first)

This lens is for software modules with interfaces: Python/shell scripts, plugin code, MCP servers. It does NOT fit markdown rules, canonical files, or prose content — those don't have "interfaces" in the Ousterhout sense. If the founder names a target that's mostly .md, say so and ask them to narrow to a code directory.

Process

  1. Explore. Spawn an Agent with subagent_type: Explore over the target directory. Ask it to walk the code and report, per file/module: what it does, its public surface (functions/classes/CLI flags other code calls), and its internal complexity. Don't apply the lens yet — just gather the shape.
  2. Classify with the lens. For each module the Explore pass surfaced, run the questions in references/deep-module-lens.md. Flag only modules that are genuinely shallow (interface complexity close to implementation complexity) — a small module with a small interface is fine, not a finding.
  3. Propose, don't prescribe. For each real finding, sketch 1-2 concrete redesigns using the vocabulary below. State the trade-off of each. Do not silently pick one — that's a founder/Sana call, same as quick-plan.md's name-options rule.
  4. Write it up, don't file it. Output goes to q-system/output/plans/architecture-review-<target-slug>-<YYYY-MM-DD>.md (per quick-plan.md), never a GitHub issue and never auto-filed to spillover — spillover is scoped to findings that interrupt an active PRD/issue's work, and linear-first.md already owns where real work gets tracked. If a finding is worth acting on, the next step is the founder or Sana deciding whether it becomes a Linear issue or a prd-os PRD.
  5. No findings is a valid outcome. Say so plainly if the target directory is already reasonably deep. Don't manufacture friction to justify the run.
Show full SKILL.md (54 more words)Show less

Vocabulary discipline

Use: module, interface, depth, seam, adapter, leverage, locality. Avoid: "component," "service" — too imprecise to carry the deep-module argument.

What this is not

Not a bug finder (that's /code-review). Not a cleanup pass (that's /simplify). Not gated, receipted work (that's prd-os) — this produces a proposal doc for a human decision, not shipped code.

© assafkip, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in plugins/kipi-core/skills/architecture-review of assafkip/kipi-system.

  • SKILL.md
  • references/deep-module-lens.md

Open the folder on GitHubat commit 16d4724

Compare with similar skills

Architecture Review next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Architecture Review compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Architecture Review this skillassafkip/kipi-system112—~817Automated safety check: PassMIT
Py Rigmudrii/hermesd118—~6.3kAutomated safety check: PassMIT
cmux Swift Package Architecturemanaflow-ai/cmux28k1 repos~4.2kAutomated safety check: PassCustom licence
Senior Architect Toolkitmaslennikov-ig/claude-code-orchestrator-kit2608 repos~1.2kAutomated safety check: NotesCustom licence
Dignified Python Standardsdocling-project/docling69k—~1.5kAutomated safety check: PassApache-2.0
Code Review Skillawesome-skills/code-review-skill2.1k—~2.8kAutomated safety check: NotesMIT

Similar skills

  • Py Rig

    mudrii/hermesd

    A skill your agent uses when building, reviewing, or refactoring Python code that requires strong maintainability discipline: SRP, DRY, OCP, explicit dependency injection, TDD/ATDD workflow, strict…

    118 GitHub stars~6.3k tokensUpdated 3 days ago
    DevelopmentAuto-check passed

  • cmux Swift Package Architecture

    manaflow-ai/cmux

    Architecture rules for cmux's move to Swift Packages: acyclic whole-domain packages, minimal public API, group folders, Xcode project wiring and Swift 6 concurrency.

    28k GitHub starsUsed in 1 repo~4.2k tokens
    DevelopmentAuto-check passed

  • Senior Architect Toolkit

    maslennikov-ig/claude-code-orchestrator-kit

    Comprehensive software architecture skill for designing scalable, maintainable systems using ReactJS, NextJS, NodeJS, Express, React Native, Swift, Kotlin…

    260 GitHub starsUsed in 8 repos~1.2k tokens
    DevelopmentAuto-check: notes

  • Dignified Python Standards

    docling-project/docling

    Applies opinionated production Python conventions chosen by the project's Python version: modern type syntax, pathlib, explicit checks and interface guidance.

    69k GitHub stars~1.5k tokensUpdated today
    DevelopmentAuto-check passed

  • Code Review Skill

    awesome-skills/code-review-skill

    Provides comprehensive code review guidance for React 19, Vue 3, Angular 17+, Svelte 5, Rust, TypeScript, Java, Java 8, PHP, Ruby, Rails, Python, Django, FastAPI, Go, C/.NET, Kotlin, Swift, Dart…

    2.1k GitHub stars~2.8k tokensUpdated 1 mo ago
    DevelopmentAuto-check: notes

  • Readable Py

    crazyguitar/pysheeet

    Readable Python code rules inspired by The Art of Readable Code.

    8.2k GitHub stars~2.4k tokensUpdated 4 days ago
    DevelopmentAuto-check passed

More from assafkip/kipi-system

All 14 skills in this repo

  • Deck AI

    assafkip/kipi-system

    Turns a markdown file into a themed, image-rich slide deck exported as PDF, using Slidev for layouts and Unsplash for photos, all run locally.

    112 GitHub stars~1.5k tokensUpdated yesterday
    Auto-check: notes

  • Unified Design Router

    assafkip/kipi-system

    Routes visual design requests to built-in logo, corporate identity, slide, banner, social photo and icon workflows, backed by style data and AI image generation.

    112 GitHub stars~2.9k tokensUpdated yesterday
    Auto-check passed

  • Improve Idea Critique

    assafkip/kipi-system

    Judges a pasted tip, post or video summary against what the kipi system already has, and returns adopt, skip or already-built with the files that back the verdict.

    112 GitHub stars~729 tokensUpdated yesterday
    Auto-check passed

  • Fable Discipline

    assafkip/kipi-system

    Teaches staged, verifiable coding habits for multi-file tasks and ships a hook that blocks tests from touching live data.

    112 GitHub stars~2.9k tokensUpdated yesterday
    Auto-check passed

  • Root-Cause Analysis Writer

    assafkip/kipi-system

    Writes a structured, blameless root-cause analysis for a defect that escaped a test or gate, separating surface from structural causes and linting the result.

    112 GitHub stars~796 tokensUpdated yesterday
    Auto-check passed

  • Audhd Executive Function

    assafkip/kipi-system

    AUDHD executive function accommodations. An agent skill from assafkip/kipi-system.

    112 GitHub stars~3.3k tokensUpdated yesterday
    Auto-check passed

Works with

Categories

Questions about Architecture Review

What does Architecture Review do?

Surfaces architectural friction in real code — shallow modules, tight coupling, untested seams — and proposes deepening refactors using Ousterhout's deep-module principle (small interface hiding a…. Architecture Review is an agent skill from assafkip/kipi-system. Surfaces architectural friction in real code — shallow modules, tight coupling, untested seams — and proposes deepening refactors using Ousterhout's deep-module principle (small interface hiding a large implementation).

When should I use Architecture Review?

Architecture Review fits situations like: the founder says architecture review; find shallow modules; architectural friction; deep module analysis.

How do I install Architecture Review in Claude Code?

Run `npx skills add assafkip/kipi-system --skill architecture-review -a claude-code`. Or copy the skill folder (plugins/kipi-core/skills/architecture-review in assafkip/kipi-system) into .claude/skills/architecture-review in your project. Claude Code loads it when a task matches its description.

How do I install Architecture Review in Codex?

Run `npx skills add assafkip/kipi-system --skill architecture-review -a codex`. Or copy the skill folder (plugins/kipi-core/skills/architecture-review in assafkip/kipi-system) into .agents/skills/architecture-review in your project. Codex loads it when a task matches its description.

Can I use Architecture Review in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add assafkip/kipi-system --skill architecture-review -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/architecture-review, .gemini/skills/architecture-review, .github/skills/architecture-review and .opencode/skills/architecture-review in your project.

What does Architecture Review need to run?

SKILL.md names no scripts, command-line tools or credentials: Architecture Review is instructions for the agent only.

Does Architecture Review access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Architecture Review safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Architecture Review use?

Architecture Review is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Architecture Review use?

About 817 tokens (SKILL.md is roughly 3.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 640 tokens, read only when the agent opens those files.

What are the alternatives to Architecture Review?

Skills that share tags, products or a category with Architecture Review: Py Rig (mudrii/hermesd, 118 stars), cmux Swift Package Architecture (manaflow-ai/cmux, 28k stars), Senior Architect Toolkit (maslennikov-ig/claude-code-orchestrator-kit, 260 stars) and Dignified Python Standards (docling-project/docling, 69k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Architecture Review?

assafkip (a GitHub user) maintains it in assafkip/kipi-system, which has 112 GitHub stars. The repository holds 14 skills in this directory. The repository was last updated on October 9, 2026.

Source: assafkip/kipi-system on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.