# Clairvoyance > ESP for AI Coding — Agent skills on the philosophy of software design, grounded in decades of engineering experience. Good software isn't written. It's designed. Clairvoyance is a collection of software design skills for AI coding agents. Each skill is a lens grounded in decades of engineering experience to help your agent see through complexity and write code with intent. Clairvoyance works with Claude Code, Codex, Cursor, OpenCode, Antigravity, and any agent platform that supports the Agent Skills open standard. ## When to use Clairvoyance Reach for a Clairvoyance skill when the job is judging or improving the design of code, not just whether it works: - Reviewing a file, module or pull request for design quality before it ships (design-review, red-flags, code-evolution) - Working out why code feels hard to change or understand (complexity-recognition, diagnose) - Checking whether an interface is deep enough, too specialized, or leaking its internals (deep-modules, general-vs-special, information-hiding) - Choosing between designs, or writing a design doc or RFC (design-it-twice) - Deciding where module boundaries, configuration and error handling belong (module-boundaries, pull-complexity-down, error-design) - Making names and comments carry the design (naming-obviousness, comments-docs) How to load one: with the plugin installed, skills load on their own when their description matches, or run one directly as /clairvoyance:. Over the MCP server, call the tool named after the skill. Without either, read the skill's Markdown from the links below. Not for: fixing a specific bug or failing test, style and lint rules, performance tuning, or choosing libraries and frameworks. ## Skills - [Deep Modules](https://clairvoyance.fyi/skills/deep-modules.md): Measures module depth: whether the interface is simple relative to the implementation behind it. Use when an interface has too many parameters or methods, many small classes each do too little, or methods just forward calls. Not for whether adjacent layers provide different abstractions (use abstraction-quality) or merging/splitting modules (use module-boundaries). - [Module Boundaries](https://clairvoyance.fyi/skills/module-boundaries.md): Evaluates where module boundaries are drawn and whether modules should be merged or split. Use when deciding whether to combine or separate two modules, when modules are tightly coupled, or when a change to one forces changes to another. Not for depth within a single module (use deep-modules) or abstraction-layer quality (use abstraction-quality). - [Information Hiding](https://clairvoyance.fyi/skills/information-hiding.md): Checks for information leakage across module boundaries, including temporal decomposition and false encapsulation. Use when modules change together, implementation details leak across boundaries, or structure follows execution order rather than knowledge ownership. Not for merge/split decisions (use module-boundaries) or interfaces over-specialized for one caller (use general-vs-special). - [Pull Complexity Downwards](https://clairvoyance.fyi/skills/pull-complexity-down.md): Checks whether complexity is pushed to callers or absorbed by implementations — the direction complexity flows. Use when callers must do significant setup, handle errors the module could resolve, or configure things they don't understand. Not for module depth (use deep-modules), knowledge leakage (use information-hiding), or exception strategy once an error must surface (use error-design). - [General vs. Special-Purpose](https://clairvoyance.fyi/skills/general-vs-special.md): Evaluates whether interfaces are appropriately general-purpose. Use when checking interface generality, when if-branches or parameters serve only one caller, or when getters/setters expose internal representation. Not for information leakage across boundaries (use information-hiding) or auditing configuration parameters (use pull-complexity-down). - [Error Design](https://clairvoyance.fyi/skills/error-design.md): Reviews error handling and exception design, applying the "define errors out of existence" principle. Use when reviewing error handling, when a module throws too many exceptions, or when callers must handle errors they shouldn't need to know about. Not for general caller-burden complexity (use pull-complexity-down); this skill is specifically for exception and error-condition strategy. - [Abstraction Quality](https://clairvoyance.fyi/skills/abstraction-quality.md): Evaluates whether abstractions provide a genuinely different way of thinking or are structurally shallow. Use when adjacent layers feel redundant, wrappers add boilerplate without depth, or an abstraction feels leaky. Not for a single module's interface-to-implementation ratio (use deep-modules) or information leakage across boundaries (use information-hiding). - [Naming & Obviousness](https://clairvoyance.fyi/skills/naming-obviousness.md): Reviews naming quality and code obviousness via the isolation test, scope-length principle, and consistency audit. Use when names feel vague, something is hard to name (a design signal, not a vocabulary problem), or behavior isn't obvious on first read. Not for comment quality or documentation (use comments-docs). - [Comments & Documentation](https://clairvoyance.fyi/skills/comments-docs.md): Reviews comment quality and documentation practices: the four comment types, comments-first workflow, and comment rot. Use when reviewing comments or docs, when comments just repeat the code, or when something is hard to describe in a sentence. Not for naming or code obviousness (use naming-obviousness). - [Strategic Mindset](https://clairvoyance.fyi/skills/strategic-mindset.md): Assesses whether code reflects strategic or tactical thinking, including the 10-20% investment rule and tactical-tornado patterns. Use when evaluating design investment, when code was written under time pressure, or when working code consistently degrades the system. Not for judging whether a specific diff looks designed-in or bolted-on (use code-evolution). - [Design It Twice](https://clairvoyance.fyi/skills/design-it-twice.md): Generates and compares at least two fundamentally different design alternatives on concrete criteria before committing. Use when the user asks to design something twice, or before committing to any significant design of classes, modules, APIs, or architecture. Also use when asked how to structure or architect a feature, or when writing the design or alternatives section of an RFC, design doc, or ADR. Not for judging strategic vs. tactical investment in existing code (use strategic-mindset) or whether a change degrades design (use code-evolution). - [Code Evolution](https://clairvoyance.fyi/skills/code-evolution.md): Evaluates whether changes to existing code maintain or degrade design quality. Use when the user asks to review a diff or PR (for example before merging it), or asks about recently modified files, to judge whether each change looks designed-in or bolted-on. Not for scanning design smells (use red-flags) or assessing overall design investment (use strategic-mindset). - [Complexity Recognition](https://clairvoyance.fyi/skills/complexity-recognition.md): Diagnoses whether complexity exists and where it comes from, using the three-symptom, two-root-cause framework. Use when code feels harder to work with than it should but the specific problem is unclear. Not for scanning known design smells (use red-flags) or evaluating a module's depth (use deep-modules). - [Red Flags Diagnostic](https://clairvoyance.fyi/skills/red-flags.md): Scans code against 17 design smells (the book's 14 named Red Flags plus 3 process-stage signals) and produces a structured diagnostic report. Use when the user asks for a red flags or design smell scan, asks to check code against a checklist, is evaluating unfamiliar code, or asks open-endedly whether anything is off in a named or pasted file, class, or function, or asks you to look it over. Not for a specific bug, error, or failing test the user has already identified. Not for a plain diff or PR review before merge, or whether a PR maintains design trajectory (use code-evolution for both), or diagnosing why code feels complex (use complexity-recognition). - [Design Review Orchestrator](https://clairvoyance.fyi/skills/design-review.md): Orchestrates a structured design review, running the other skills as a diagnostic funnel from complexity triage to a full red-flags sweep. Use when the user asks for a comprehensive or prioritized design assessment of a file, module, or PR. Not for an open-ended "anything off here?" or "take a look at this" prompt that names no review goal (use red-flags), a plain diff review before merge or analyzing how code changed over time (use code-evolution), or applying one specific lens (use that skill directly). - [Diagnose](https://clairvoyance.fyi/skills/diagnose.md): Routes a vague symptom or complaint to the most relevant Clairvoyance skill via a decision tree. Use when someone describes a problem but doesn't know which skill to reach for. Not for a comprehensive review (use design-review) or a checklist scan (use red-flags). ## Which Skill Do I Need? Start with what bothers you: - Something smells but I can't pinpoint it ↳ It works, but I'd hate to maintain it → [/complexity-recognition](https://clairvoyance.fyi/skills/complexity-recognition) (+ [/red-flags](https://clairvoyance.fyi/skills/red-flags)) ↳ Every small change breaks something unexpected → see "structure" below - Every change turns into a scavenger hunt ↳ I end up editing five files for one feature ↳ The same internal details are hardcoded everywhere → [/information-hiding](https://clairvoyance.fyi/skills/information-hiding) ↳ I keep copying the same logic around → [/code-evolution](https://clairvoyance.fyi/skills/code-evolution) ↳ Things that belong together live in different places → [/module-boundaries](https://clairvoyance.fyi/skills/module-boundaries) ↳ There are layers that just pass data through → [/abstraction-quality](https://clairvoyance.fyi/skills/abstraction-quality) (+ [/deep-modules](https://clairvoyance.fyi/skills/deep-modules)) ↳ I can't tell which module owns what → [/module-boundaries](https://clairvoyance.fyi/skills/module-boundaries) - This API is painful to use ↳ Callers need too much boilerplate to use it → [/pull-complexity-down](https://clairvoyance.fyi/skills/pull-complexity-down) ↳ It only works for one specific use case → [/general-vs-special](https://clairvoyance.fyi/skills/general-vs-special) ↳ The abstraction isn't saving me any work → [/deep-modules](https://clairvoyance.fyi/skills/deep-modules) - The code is hard to read or understand ↳ I can't come up with a good name for this → [/naming-obviousness](https://clairvoyance.fyi/skills/naming-obviousness) (+ [/design-it-twice](https://clairvoyance.fyi/skills/design-it-twice)) ↳ The comments are useless or nonexistent → [/comments-docs](https://clairvoyance.fyi/skills/comments-docs) ↳ There are try/catch blocks and error paths everywhere → [/error-design](https://clairvoyance.fyi/skills/error-design) - I'm starting fresh or need a second opinion ↳ I don't know where to begin → [/diagnose](https://clairvoyance.fyi/skills/diagnose) ↳ I'm designing something from scratch → [/design-it-twice](https://clairvoyance.fyi/skills/design-it-twice) (+ [/comments-docs](https://clairvoyance.fyi/skills/comments-docs)) ↳ This was hacked together and it shows → [/strategic-mindset](https://clairvoyance.fyi/skills/strategic-mindset) (+ [/code-evolution](https://clairvoyance.fyi/skills/code-evolution)) ↳ I need to review this before it ships → [/design-review](https://clairvoyance.fyi/skills/design-review) ## Links - [GitHub](https://github.com/codybrom/clairvoyance) - [Installation](https://clairvoyance.fyi/install.md) - [Agent setup](https://clairvoyance.fyi/agent-setup.md): instructions your agent can follow to install Clairvoyance for you - [MCP server](https://clairvoyance.fyi/mcp): every skill as an MCP tool, for clients that can't install the plugin - [Skills index](https://clairvoyance.fyi/skills/llms.txt): just the skill catalog - [MCP server details](https://clairvoyance.fyi/mcp/llms.txt): connecting, tools, and what the server receives - [Full content](https://clairvoyance.fyi/llms-full.txt) ## Source & License Created by [Cody Bromley](https://github.com/codybrom). Inspired by *A Philosophy of Software Design* by John K. Ousterhout. Licensed under the [MIT License](https://github.com/codybrom/clairvoyance/blob/main/LICENSE).