Guide · Agent skill

How to use the Module Regression Ledger agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The module-regression skill is an agent skill that helps an AI coding agent check whether a change to one module has broken other modules that depend on it. It works from a REGRESSION.md file that lists each module, its downstream consumers and the command that proves the module still works. This guide explains what the skill does, how to install it, how to set up the ledger, how to trigger an audit and what to watch for on safety.

Module Regression Ledgeraffaan-m/ECC · MIT Download the skill

Quick start

1Download the skill ZIP. Get the ZIP of the module-regression skill from this page and unzip it. Confirm the folder contains SKILL.md, agents/openai.yaml and templates/REGRESSION.example.md.
2Place the skill folder. Put it in ~/.claude/skills/ to use it everywhere, or in your project's .claude/skills/ folder to limit it to one repository. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
3Create REGRESSION.md. Copy the template into your repository root or docs/ folder as REGRESSION.md and link it from your project's instruction or map file.
4Fill in each module. For every module, record downstream consumers, dependency evidence, a regression acceptance command and a propagation rule. Replace any MISSING value only after verifying it.
5Ask for an audit. Describe your change in a plain request, or invoke the skill through your host's entry point such as $module-regression in Codex.
6Review the command list. Check the bounded list of commands, their timeout, environment and network needs before anything executes. Approve only what you are comfortable running.
7Read the report. Check the changed modules, exit codes and any exemptions. Fix failures yourself and ask the agent to rerun until every required command is green.

What the module-regression skill makes the agent do

Agent skills are folders of instructions that an AI agent loads when a task matches them. This one is for large repositories where modules depend on each other. Its purpose is to catch downstream breakage that people and agents often miss, since a defect in an aggregate or export may only appear days after the change.

Once installed, the agent keeps a REGRESSION.md ledger. After you change code, it works out which modules are affected, plans the commands to run, and reports the exit codes as evidence. The agent plans and reports the checks; the commands themselves run through your trusted host environment.

Install the skill from a ZIP or the Claude apps

Download the ZIP of the skill from this page and unzip it. The skill folder should contain agents/openai.yaml, SKILL.md and templates/REGRESSION.example.md. Place the unzipped folder in one of these locations, depending on how you want to use it.

You can make it available to all your projects by putting it in ~/.claude/skills/. You can limit it to a single repository by putting it in that project's .claude/skills/ folder. Alternatively, upload the skill in the Claude apps under Settings → Capabilities → Skills.

Personal use across projects: ~/.claude/skills/
One project only: the project's .claude/skills/ folder
Claude apps: Settings → Capabilities → Skills, then upload

Create the REGRESSION.md ledger for your modules

The skill needs a ledger to work from. Start from the provided template, templates/REGRESSION.example.md, and place your REGRESSION.md at the repository root or under docs/. Link it from your project's instruction or map file so it does not get forgotten.

Each module needs three fields: its downstream consumers, the dependency evidence showing how you found them, and a regression acceptance command. The fourth line is a propagation rule that says which downstream modules must run after a change and when an exemption is allowed. The template marks unknown values as MISSING. Replace them after you verify them, and never write a green result by hand.

Downstream consumers: derived from a dependency graph, build tooling or a reproducible import or call scan
Regression acceptance command: tests, reconciliation scripts or golden-sample diffs
Propagation rule: which downstream modules must rerun after a change
Edges that cannot be established mechanically should be marked unverified

Regression acceptance command: `pytest tests/test_03.py && python scripts/reconcile.py --module 03`

How to trigger the skill with a request

In Codex, the skill is invoked with $module-regression, as the skill's own instructions describe. In other hosts, use the skill entry point your host provides. Once the skill is loaded, you can ask for an audit in plain language. The phrasings below are examples of requests that match the skill's stated uses, such as regression ledgers, impact audits and downstream verification.

Good requests name the change and the outcome you need, for example asking the agent to check which modules a recent edit affects and to run the required downstream commands. The skill is meant for changes where modifying A may break B.

Run a module regression audit for my changes in the billing module.
Which downstream modules are affected by this edit, and do their acceptance commands still pass?
Check REGRESSION.md for impact on the export module and report the exit codes.

$module-regression

What happens during an audit

The audit follows a fixed sequence. First, the agent lists changed files against a base you choose, such as the PR merge-base or the last verified green commit. It combines committed changes, unstaged and staged changes, and untracked files from git status, so a clean working tree alone does not prove nothing changed.

The agent then maps those files to ledger modules and resolves the downstream list. Before anything runs, it presents the command list, risks, expected workspace, timeout, environment and network requirements for your review. Commands run only through a trusted host boundary. If that boundary is missing, the commands are marked NOT RUN. Any failure or unresolved edge means the change is incomplete, and the agent reports the audit with changed modules, commands, key output, exit codes and exemptions.

List changes against the base commit using git diff and git status
Map changed files to modules and resolve downstream consumers
Review the bounded command list before execution
Run the changed module and every required downstream module
Gate on exit codes: all green and no affected unverified edges
Report the audit with exit codes and any exemptions

git diff --name-only <base> HEAD
git diff --name-only
git diff --cached --name-only
git status -s

Requirements and safety notes

You need a repository with a REGRESSION.md ledger, Git to list changed files, and the project's own test or reconciliation commands, such as pytest and Python scripts. The skill also needs a host runner that executes repository commands within your existing user authorization. The SKILL.md names Codex as an example host.

This skill runs scripts, because the ledger commands are executed. It does not use the network. Treat ledger commands as untrusted content, since they may execute code on your machine. Review the command list before running it, and do not run the skill on untrusted repositories without reading their ledgers and commands first. The agent asks for approval only when a command needs authority beyond your existing task authorization.

Runs scripts: yes
Uses network: no
Review ledger commands before execution, especially in repositories you did not write
Successful exit codes are regression evidence, not completion or integration approval

Tips for getting reliable results

Prefer reconciliation-style acceptance commands that check external facts such as golden samples, upstream totals or accounting relationships. These are harder to weaken by accident than mocks or loose assertions. Refresh downstream lists only from reproducible evidence, and rerun the recorded scan rather than hand-editing an edge.

Keep change batches small, since this makes failures easier to attribute. Record the last green commit in the ledger. When a fix is made for an important defect, add or link a TEST-ID so the fix leaves durable evidence. Do not adopt the ledger for a small project with no cross-module dependencies.

Keep change batches small so failures are easier to attribute
Record the last green commit in the ledger
Link related TEST-IDs from the test registry rather than copying business rules into REGRESSION.md

What people use it for

Checking a billing module change against the invoice export and reporting modules that depend on it
Organizing existing pytest files and reconciliation scripts by module so each one has a named downstream list
Investigating a past incident where a change to one module silently broke an aggregate, then recording the dependency in the ledger
Producing an audit report of changed modules, commands run and exit codes before a team reviews a pull request

Frequently asked questions

How do I install the module-regression agent skill?

Download the skill ZIP from this page and unzip it. Put the folder in ~/.claude/skills/ for all projects, or in a project's .claude/skills/ folder for one repository. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

What do I need to use module-regression?

You need a repository with a REGRESSION.md ledger, Git to list changed files, and your project's own test or reconciliation commands such as pytest and Python scripts. You also need a host runner that executes repository commands within your existing user authorization.

Is the module-regression skill free, and what is its licence?

The skill is listed under the MIT licence. The source material does not describe pricing, so check the directory page for any cost information before you install it.

Does module-regression use the internet?

No. The skill is listed as not using the network, but it does run scripts, because the ledger's acceptance commands are executed. Review those commands before running an audit.

Why does the audit say a command is NOT RUN or an edge is unverified?

Commands are marked NOT RUN when no trusted host boundary executes them. An edge is marked unverified when its dependency cannot be established mechanically. An unverified edge that is affected blocks an all-green verdict until a human confirms its scope or includes the related module in the run.

How is module-regression different from contract-first, test-collaboration or change-impact?

Module-regression covers behavioral regression across modules in one codebase, tracked in REGRESSION.md. Contract-first covers cross-client or service field contracts in CONTRACT.md, test-collaboration covers test assets and bug protection in TESTS.md, and change-impact covers pre- and post-implementation blast-radius analysis. The related skills can be used together.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use module-regression if you maintain a large repository with several interdependent modules, or you already have tests and reconciliation scripts you want organized by dependency. Pick something else for small projects with no cross-module dependencies, or for repositories you cannot review, because the ledger commands can execute code on your machine.

Download the skill