A Small Skill for Keeping Instruction Parity 🦆

Turns out keeping parity between Claude and Codex instructions is a lot of maintenance.

I made a skill for Codex (or Claude, but I built this one for Codex since it's the one with spare tokens most of the time) to run on a schedule that handles it for me now:

refresh-guidance-parity/SKILL.md

---
name: refresh-guidance-parity
description: Refresh AGENTS.md and CLAUDE.md parity across a workspace or subset of repositories. Use when the user asks for a global parity check, guidance drift cleanup, repo onboarding doc sync, or wants missing AGENTS.md files created alongside existing CLAUDE.md files. Keep AGENTS.md as the concise operational brief and CLAUDE.md as the deeper architecture and reference document.
---

# Refresh Guidance Parity

Use this skill when guidance docs need to be brought back into alignment.

## Scope

Default scope:

- workspace root AGENTS.md and CLAUDE.md
- every child repo that has either file

Follow user-provided scope if specified.

## Core rule

- AGENTS.md = concise operational brief
- CLAUDE.md = deeper architecture and reference
- Instruction files = workflows and procedures

Do not duplicate full content across files.

## What belongs where

AGENTS.md:
- repo purpose in 1-3 lines
- toolchain bootstrap
- highest-signal commands
- current status
- repo-specific rules
- pointers to instruction files

CLAUDE.md:
- architecture walkthroughs
- product context
- component maps
- deeper command references
- references to instruction files

Instruction files:
- step-by-step workflows
- operational runbooks
- repeated procedures

## Working steps

1. Inventory AGENTS.md and CLAUDE.md files
2. Identify drift patterns
3. Patch files directly
4. Verify parity across scope

## Drift patterns

- CLAUDE.md exists but AGENTS.md missing
- AGENTS.md missing key operational details
- long procedures embedded instead of extracted

## Instruction extraction rule

- shared workflows → central instructions directory
- repo-specific workflows → local instructions directory
- index docs reference, not embed

## Editing rules

- prefer targeted edits
- keep AGENTS.md short
- preserve useful repo language
- add missing AGENTS.md where needed
- replace long procedures with references

## Validation

- ensure every CLAUDE.md has AGENTS.md
- check for template mistakes
- confirm instruction references exist

## Completion

report:
- repos checked
- files added or updated
- instruction files touched
- parity status