An agent-agnostic software engineering skill with one job: complete or review a non-trivial change without letting compatibility, safety, or completion claims outrun evidence.
One core control loop (change contract → risk profiles → proof portfolio → execution →
completion gate) plus six composable risk profiles that are read only when their trigger
matches. This is v2, a breaking rewrite of the skill previously named agent-systems —
see CHANGELOG.md and docs/design-rationale.md.
The GitHub repository keeps its original name; the installed skill is change-with-proof.
Install globally with the open skills CLI:
npx skills add CodingCossack/agent-systems -g -yInstall for selected agents:
npx skills add CodingCossack/agent-systems -g -y \
-a codex -a claude-code -a gemini-cli -a opencodeThe skill follows the open Agent Skills format with no harness-specific dependency. It works with Codex, Claude Code, Gemini CLI, OpenCode, Cursor, GitHub Copilot CLI, Windsurf, and other compatible coding agents.
$skill-installer install https://github.com/CodingCossack/agent-systems/tree/main/skills/change-with-proof
Keep a Git checkout outside the agent roots and link the actual skill directory:
git clone https://github.com/CodingCossack/agent-systems.git \
~/.local/share/agent-skills/agent-systems
mkdir -p ~/.agents/skills
ln -s ~/.local/share/agent-skills/agent-systems/skills/change-with-proof \
~/.agents/skills/change-with-proofRestart an active agent session if it does not reload skills dynamically.
npx skills update change-with-proof -g -yFor a Git installation:
git -C ~/.local/share/agent-skills/agent-systems pull --ff-onlyIf updating across the v1→v2 rename, remove the old agent-systems links and re-link
skills/change-with-proof as shown above.
The core SKILL.md owns the whole loop and is the only always-loaded file:
- Change contract — classify what the change preserves, changes, migrates, or retires; how strong each contract is and who consumes it; how reversible the step is.
- Risk profiles — read every profile whose trigger matches, none otherwise:
| Trigger | Profile |
|---|---|
| Bug, failing or flaky test, regression | causal-debugging |
| Changing/migrating/retiring a hard contract | contract-evolution |
| Identity, permissions, tenancy, secrets, untrusted input, uploads, routing | trust-boundaries |
| Persistence, retries, webhooks, payments, queues, caches | stateful-integrations |
| Rendering, copy, notifications, exports, user-facing output | user-visible-surfaces |
| Deletion, replacement, legacy removal | replacement-closure |
- Proof portfolio — the smallest set of evidence that covers every material changed risk, each item chosen at the lowest seam that still contains the real risk.
- Execution — vertical slices; one durable state block for long or resumed work.
- Completion gate — diff locality, claim/evidence/gap matching, one compact report.
The central rule is unchanged from v1: a passing typecheck does not prove a browser flow, a unit test does not prove routing, and a grep result is not deletion authority.
Explicit invocation:
Use $change-with-proof to debug this routing regression and prove the fix at the real failure seam.
Use $change-with-proof to migrate this schema without breaking existing rows, and report the evidence.
Repository and harness instructions remain authoritative. If a repository has AGENTS.md,
CLAUDE.md, CI rules, or local conventions, the skill operates within them.
Implicit invocation is enabled in agents/openai.yaml after the v2 trigger battery achieved
30/30 intended triggers and 0/30 near-miss triggers. On harnesses that route purely by
description (for example Claude Code), the frontmatter description carries the same explicit
"Do not use for" scope.
Changes to the skill's behaviour are gated by subagent-based RED/GREEN pressure scenarios and
trigger micro-tests, recorded in docs/testing.md. Structural checks run in
CI via ./scripts/validate.sh.
skills/change-with-proof/
├── SKILL.md
├── agents/openai.yaml
└── profiles/
├── causal-debugging.md
├── contract-evolution.md
├── trust-boundaries.md
├── stateful-integrations.md
├── user-visible-surfaces.md
└── replacement-closure.md
Focused issues and pull requests are welcome. See CONTRIBUTING.md and SECURITY.md.