skills.rest
leonardoacosta
leonardoacostaCOMMUNITY
Explore all skills by this author →
GitHub

agent-instruction-pairing

Creates and maintains paired CLAUDE.md and AGENTS.md instruction files across repository roots and nested packages.

Updated Aug 2, 2026
Search Tags:#claude.md#agents.md#agent instructions#documentation sync#repository configuration#cross-runner parity#nested packages
One-click install
npx skills add https://github.com/leonardoacosta/skills --skill agent-instruction-pairing-leonardoacosta
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agent-instruction-pairing
Source: https://github.com/leonardoacosta/skills/tree/main/meta/skills/agent-instruction-pairing
Command: npx skills add https://github.com/leonardoacosta/skills --skill agent-instruction-pairing-leonardoacosta

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Different agent runners like Claude Code, Codex, and PI look for different instruction files (CLAUDE.md vs AGENTS.md), so a single-file or mixed parent/child layout causes inconsistent agent behavior across tools. This Skill establishes a paired-file strategy that keeps both files present and aligned wherever agents need guidance. ## Core Features & Use Cases - Paired File Setup: Creates both CLAUDE.md and AGENTS.md at the repo root and in any nested package that needs local instructions. - Drift Detection and Repair: Identifies directories where one file is missing or where the pair has diverged, then syncs them back into alignment. - Override Management: Mirrors intentional child-directory overrides into both files so local behavior stays consistent across runners. - Use Case: A monorepo team finds Codex ignoring root CLAUDE.md guidance inside a nested app; this Skill adds paired files in that package and aligns them with the root policy. ## Quick Start Set up paired CLAUDE.md and AGENTS.md files at my repo root and in any nested packages that need their own agent instructions.

Frequently Asked Questions about agent-instruction-pairing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up CLAUDE.md and AGENTS.md for my repository?▼

Create both CLAUDE.md and AGENTS.md at the repo root with aligned content, then repeat the pair in any nested package needing local instructions. Keeping both files present ensures Claude Code, Codex, and PI all find guidance.

Should I use CLAUDE.md or AGENTS.md for agent instructions?▼

Use both rather than choosing one. Evaluations show Claude prefers CLAUDE.md while Codex and PI prefer AGENTS.md in direct conflicts, so a paired layout is the most portable strategy across runners.

How do I add different agent instructions for a nested package?▼

Create both CLAUDE.md and AGENTS.md inside the child directory with the override content mirrored in each file. Document the override briefly so later edits do not accidentally collapse it back to root behavior.

Why is one agent runner ignoring my CLAUDE.md file?▼

Runners like Codex and PI prefer AGENTS.md, so a root-only CLAUDE.md may be ignored. Mixed parent/child filename layouts also behave inconsistently; pairing both files in each directory resolves this.

What happens when CLAUDE.md and AGENTS.md drift out of sync?▼

Drifted pairs cause divergent behavior between runners. The fix is to sync the sibling files in the same change whenever you edit one, rather than adding runner-specific branching.

Related Skills

Explore More Software Engineering Skills→
leonardoacostaleonardoacosta

agent-instruction-pairing

Creates and maintains paired CLAUDE.md and AGENTS.md instruction files across repository roots and nested packages.

Community
Basic
polikeijipolikeiji

constitution

Create structured project constitutions for coding and documentation standards.

Community
Advanced
webdevcodywebdevcody
22

code-write-tests

Detect a test harness and write behavioral tests with real DB usage.

Community
Advanced
ComposioHQComposioHQ
74.2k

shorten-rest-automation

Automate Shorten Rest operations using Rube MCP toolkits for efficient workflow execution.

Official
Intermediate