The complex-md skill

Skill for spec 0.3 · prompt 0.3.0 · download · CLI source

The skill is a single markdown file a coding agent runs inside a repository to produce a conforming COMPLEX.md. It runs the CLI's local analysis where Node is available, carries a git-and-awk fallback for where it is not, and embeds the same generation prompt the CLI uses, so the output is the same whichever path you take.

Download complex-md.skill.md

Install

Claude Code. Save the file as .claude/skills/complex-md/SKILL.md in the repo (or in ~/.claude/skills/ for all repos), then ask: "generate COMPLEX.md".

Cursor. Save it as .cursor/rules/complex-md.mdc or just open the file and tell the agent to follow it.

Codex or any other agent. Paste the file into the conversation, or point the agent at it: "follow complex-md.skill.md to generate COMPLEX.md".

What it does

  1. Classifies every tracked file by kind: source, config, markup and style can be hotspots; tests, docs, data, manifests, CI, generated, vendored and binary files cannot.
  2. Builds the dependency graph of the working tree: imports and requires with path resolution, script and link tags, stylesheet imports, shell and Caddy includes, and path literals in scripts and configs. Fan-in is the blast radius; the tests that reach a file are its covering tests.
  3. Reads the last 2,000 commits, skipping merges and bulk commits, and weights each by its age in commits, so velocity does not bias the map.
  4. Counts the commits per file whose message says it fixes something. Files fixed before are where the next fix lands; this is the column an agent hunting a bug sorts by.
  5. Finds files and directories that change together, with the share of the quieter side's commits that touch both; convention files like a changelog are detected and excluded.
  6. Scores each file by size, activity and dependents, lists the untouched files everything depends on separately, and cuts the hotspot list where the scores fall off.
  7. Writes the profile and blind spots: history depth, velocity, committers, submodules, vendored code, and whether history carries weight yet.
  8. Writes COMPLEX.md from the numbers plus the top hotspot files and the tests that cover them, following the versioned generation prompt. Every hotspot paragraph ends with an instruction.
  9. Wires the file in: appends the integration block to AGENTS.md, CLAUDE.md, GEMINI.md and copilot-instructions where they exist, adds an @COMPLEX.md import to CLAUDE.md, and writes a path-scoped rule for Claude Code, Cursor and OpenHands keyed to the hotspot files, so the directives reappear exactly when a hotspot is touched.
  10. Installs the enforcement: a hook that holds the first edit of a hotspot per session until the agent has read its paragraph, a hook that refuses to end the turn once if a co-change partner was left unchanged, and the complex-md MCP server so the agent can query the map, a file's blast radius, or a symbol's references mid-task. Via npx complex-md wire when npx is available, by hand otherwise. See the spec.

Everything runs locally in the agent's shell. Nothing is uploaded anywhere.

Versioning

The skill embeds prompts/generate.md, the single source of truth for generation. The prompt version and the spec version are stamped in the file you download, and in the front matter of every COMPLEX.md it produces.