A standard Codex Skill for recording and verifying durable project decisions through evidence-backed Agent Notes.
Code, tests, and task trackers show what changed, but often do not preserve why a high-impact decision was made, which alternatives were rejected, who owns it, or which consumers must remain compatible. This Skill turns those decisions into reviewable, version-controlled contracts.
Use this Skill before or during changes to:
- public APIs, schemas, persistence formats, and compatibility boundaries;
- algorithms, statistical meanings, security posture, dependencies, and performance strategy;
- migrations, cache ownership, lifecycle models, and generated artifacts;
- shared contracts or test/release policies used by multiple Agents;
- deletions or replacements where missing consumers could cause a regression.
Do not create a Note for formatting, mechanical renames, isolated typo fixes, or disposable experiments.
The skill/ directory is the distributable Codex Skill:
skill/
├── SKILL.md
├── agents/openai.yaml
├── references/note-contract.md
└── scripts/
├── new_agent_note.py
└── validate_agent_notes.py
The repository-level README and Git files stay outside skill/, so they are not included when the Skill is packaged.
Copy skill/ to a target repository as:
<target-repository>/.codex/skills/agent-notes-governance/
Copy skill/ to:
%USERPROFILE%/.codex/skills/agent-notes-governance/
Use project scope when the Skill is part of a repository's development process. Use user scope when it should be available across projects.
Run from the target repository root:
uv run --isolated --python 3.12 python \
.codex/skills/agent-notes-governance/scripts/new_agent_note.py \
--root .agents/notes \
--status proposed \
--type architecture \
--slug result-cache-owner \
--title "Result cache ownership" \
--scope "cache module and public API" \
--owner "project maintainer" \
--impact high
Fill every required section in the generated Note before review. After implementation and direct verification, record the decision as implemented. Validate the Note set:
uv run --isolated --python 3.12 python \
.codex/skills/agent-notes-governance/scripts/validate_agent_notes.py \
--root .agents/notes
The default validator mode strictly checks Governance: v1 Notes and reports legacy Notes as warnings. Use --strict only after legacy Notes have been migrated intentionally.
proposed -> implemented -> superseded (archived)
\-> rejected
proposed: reviewable but not shipped;implemented: current decision backed by verification;rejected: explicitly not adopted;archived: non-current history, with a successor link for superseded decisions.
The scripts use only the Python standard library. Python 3.12 plus uv is the tested execution path; direct python execution is also supported.
Run the regression tests from the repository root:
uv run --isolated --python 3.12 python -m unittest discover -s tests -v
Validate the distributable Skill with the Codex Skill validator. The official validator imports PyYAML, so include it in the isolated environment:
uv run --isolated --with pyyaml --python 3.12 python \
<CODEX_HOME>/skills/.system/skill-creator/scripts/quick_validate.py skill
Package only the skill/ directory with the official Codex Skill packager when it is available. Do not package the repository root, because the root README is maintainer documentation rather than Skill instructions.
Commit skill/, README.md, and .gitignore. Keep project decision records in the consuming repository's .agents/notes/ directory rather than bundling them into this Skill.
MIT. See LICENSE.