name: agent-context-maintainer description: Create, update, and validate repository-local AI agent context files such as AGENTS.md, .agents/core.md, .agents/routing.md, provider-specific profiles, and task SKILL.md routing. Use when an AI coding agent (Codex, Claude Code, Gemini, Copilot, Cursor, or others) is asked to make AGENTS.md or SKILL instructions self-maintaining, inspect the current path and generate optimal agent context for it, or keep agent instructions synchronized with the repository's actual structure.

Agent Context Maintainer

Overview

Maintain a small, layered agent-context system for the current repository: a universal entry point, shared rules, provider-specific profiles, and task-specific skill routing. Prefer safe incremental updates over replacing human-authored instructions.

Workflow

1. Treat the current working directory, or the user-specified path, as the context root. Do not scan above it unless the user explicitly asks.
2. Identify the active agent runtime when possible: Codex, Claude Code, Gemini, Copilot, Cursor, Antigravity, or unknown. If unknown, create generic profiles and make the user-facing routing explicit.
3. Inventory the path with file names, manifests, existing docs, tests, and build files. Do not read secrets, credentials, private keys, .env*, local databases, dependency caches, or generated build output.
4. Read existing AGENTS.md, .agents/**, and relevant SKILL.md files before editing. Preserve human-written rules and update only the smallest needed sections.
5. Create or refresh this structure:

AGENTS.md
CLAUDE.md
GEMINI.md
.github/
  copilot-instructions.md
.gemini/
  settings.json
.agents/
  core.md
  routing.md
  provider-registry.yaml
  profiles/
    codex.md
    claude.md
    gemini.md
    cursor.md
    copilot.md
    antigravity.md
    generic.md
  skills/

6. Keep AGENTS.md as a thin entry point. Generate CLAUDE.md as a Claude Code entry file that imports AGENTS.md with @AGENTS.md.
7. Put durable cross-agent rules in .agents/core.md, provider/model differences in .agents/profiles/*.md, and task selection rules in .agents/routing.md.
8. Validate references and report what changed, what was preserved, and what still needs human confirmation.

Scripted Scaffold

Use scripts/agent_context.py for repeatable setup and validation:

python3 scripts/agent_context.py providers
python3 scripts/agent_context.py inventory /path/to/repo
python3 scripts/agent_context.py scaffold /path/to/repo --agent auto
python3 scripts/agent_context.py check /path/to/repo

Run providers to list supported providers, their bridge files, and whether they can be auto-detected. Run inventory before manual edits when the repository shape is unclear. Use inventory --json --explain-skips when skip reasons matter. Run scaffold to create missing files or refresh generated blocks; --agent auto detects the runtime from confirmed environment variables and reports what it found, and --agent <name> always overrides detection. Run check before finishing.

Update Rules

• Update marker-first by default: replace only generated blocks and preserve hand-written content outside markers.
• Treat markers as owned only when they are standalone lines outside Markdown code fences.
• Refuse existing unmarked Markdown targets by default.
• Use --append-generated-block to preserve an unmarked Markdown target and append a managed block.
• Use --force-recreate only when the user explicitly accepts replacing an unmarked scaffold target.
• Use --dry-run to preview planned writes.
• If a generated-block update is not recoverable from git, snapshot the previous content before overwriting that block.
• Merge existing .gemini/settings.json objects by adding required bridge keys and preserving other settings.
• Prefer generated-block updates delimited by <!-- agent-context-maintainer:begin --> and <!-- agent-context-maintainer:end -->.
• Do not copy raw secrets, credentials, tokens, private URLs, personal data, chat transcripts, or raw logs into context files.
• Mention sensitive boundaries as policy, not as examples containing real data.
• Keep provider profiles short. Put only differences that help that agent behave better.
• Keep task skills focused on triggering and procedure. Avoid duplicating core repository policy in every skill.
• If a private planning document changes a public-facing rule, call out the sync need rather than silently making broad edits.

Reference Files

Read these only when needed:

• references/context-file-contract.md: required files, section ownership, and update boundaries.
• references/provider-profiles.md: what belongs in Codex, Claude, Gemini, Cursor, and generic profiles.
• references/inventory-heuristics.md: what to inspect, what to ignore, and how to summarize a repository safely.
• references/extension-guide.md: product intent, generation rules, and how to extend the skill for new agents or models.
• Japanese companion docs use the same names with .ja.md.

Agent Context Maintainer

agent-context-maintainer is a portable toolkit and agent skill for creating and maintaining repository-local instructions for AI coding agents.

It inspects a target repository, creates a small layered context structure, and keeps generated content bounded so future agents can update it safely. It works the same whether it is driven by Codex, Claude Code, Gemini, Copilot, Cursor, another agent, or a human at a terminal.

When to Use This

This tool provides structure, update safety, and secret-handling boundaries — not the repository-specific content itself. Its value scales with how many tools, repositories, and people share the same instructions. It earns its footprint when at least one of these is true:

• Multiple AI tools work in the same repository. Two or more of Codex, Claude Code, Gemini CLI, Copilot, or Cursor read instructions from different file names, and you want one source of truth instead of hand-synchronized copies.
• You maintain several repositories and want the same context structure, and the same scaffold/check commands, in every one of them.
• Agents or teammates regenerate instruction files, and you need a machine-enforced guarantee that hand-written rules survive updates.
• Instruction files keep drifting from the code, and you want the inventory-derived sections refreshed by a command instead of by memory.

When none of these hold, skip it:

• A single tool on a single repository is better served by one hand-written CLAUDE.md or AGENTS.md. The layered structure adds indirection you are not using, and most of the seven provider profiles will sit unused.
• The instructions that matter are repository-specific judgment — architecture rules, workflow conventions, review policy. This tool cannot write that content for you; if nobody will fill in the hand-written sections, the scaffold alone adds little.
• Your platforms already read AGENTS.md directly and you have no per-provider differences. A plain AGENTS.md may be enough; the bridge files exist for today's inconsistent loading contracts and lose value as platforms converge on the standard.

What It Creates

AGENTS.md
CLAUDE.md
GEMINI.md
.github/
  copilot-instructions.md
.gemini/
  settings.json
.agents/
  core.md
  routing.md
  provider-registry.yaml
  profiles/
    codex.md
    claude.md
    gemini.md
    cursor.md
    copilot.md
    antigravity.md
    generic.md
  skills/

AGENTS.md stays small. CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md act as provider bridges so tools can find the same shared source of truth without duplicating policy. Shared policy lives in .agents/core.md, task routing lives in .agents/routing.md, provider/model differences live in .agents/profiles/, and .agents/provider-registry.yaml records bridge files and source URLs.

See examples/sample-output/ for a complete generated example. This repository itself deliberately has no AGENTS.md or .agents/ at its root: the repository is the distributable skill, and keeping generated artifacts out of the package keeps skill installs clean.

Installation

The core is a single dependency-free Python script (scripts/agent_context.py, Python 3.9+), so every integration below is "put this folder somewhere and run the script".

Codex — place this folder in a skills directory. Codex discovers skills from .agents/skills at repo scope (<repo>/.agents/skills/agent-context-maintainer/) or user scope (~/.agents/skills/agent-context-maintainer/). Since this tool itself creates .agents/skills/ in target repositories, you can self-host it there. Prefer the user scope: with a repo-scope install, files bundled with the skill (examples/, tests/) show up in that repository's own inventory as docs/tests.

Claude Code — place this folder at ~/.claude/skills/agent-context-maintainer/ (personal) or <repo>/.claude/skills/agent-context-maintainer/ (project).

Agents without a skill mechanism — check the folder out anywhere and point the agent at the script from your repository instructions, for example: "To maintain agent context files, run python3 <path>/scripts/agent_context.py scaffold . --agent <name> and check .".

Humans — run the CLI directly; see Quick Start.

Installation paths were verified against the platform documentation on 2026-07-02 (reports/provider-review-2026-07.md). Native subagent locations, skill listing budgets, and the Codex adapter schema were verified on 2026-08-03 (reports/provider-review-2026-08.md).

Quick Start

From this folder:

python3 scripts/agent_context.py providers
python3 scripts/agent_context.py inventory /path/to/repo
python3 scripts/agent_context.py inventory /path/to/repo --json --explain-skips
python3 scripts/agent_context.py scaffold /path/to/repo --agent auto
python3 scripts/agent_context.py check /path/to/repo
python3 scripts/agent_context.py skills inventory /path/to/repo --json
python3 scripts/agent_context.py skills check /path/to/repo
python3 scripts/agent_context.py skills sync /path/to/repo

providers lists supported providers, their bridge files, and whether they can be auto-detected. Use --agent codex, --agent claude, --agent gemini, --agent cursor, --agent copilot, --agent antigravity, or --agent generic to generate a different active profile.

--agent auto detects the runtime from environment variables that were confirmed against first-party sources (see reports/provider-review-2026-07.md) and prints what it detected. Detection is deliberately conservative: unknown environments fall back to generic, and some providers can only be selected explicitly. Codex in particular sets its variables only while sandboxing is active, so pass --agent codex when detection falls back.

scaffold supports three safety controls:

• --dry-run: show planned writes without changing files.
• --append-generated-block: preserve an existing unmarked Markdown file and append a managed block.
• --force-recreate: explicitly replace an existing scaffold target that has no generated marker.

SkillOps

The nested skills command group audits and maintains repository-local Agent Skills under .agents/skills/.

python3 scripts/agent_context.py skills inventory /path/to/repo
python3 scripts/agent_context.py skills inventory /path/to/repo --json
python3 scripts/agent_context.py skills check /path/to/repo
python3 scripts/agent_context.py skills report /path/to/repo
python3 scripts/agent_context.py skills sync /path/to/repo
python3 scripts/agent_context.py skills routes /path/to/repo
python3 scripts/agent_context.py skills eval /path/to/repo --skill code-review --plan
python3 scripts/agent_context.py skills eval /path/to/repo --skill code-review --init-workspace

skills inventory scans only direct child directories under ROOT/.agents/skills/, then validates the SKILL.md inside each one. It parses a safe dependency-free frontmatter subset, validates required Agent Skills fields, checks safe local references, validates evals/evals.json when present, and reports symlinked skill directories without following them. Missing evals are warnings only; valid skills default to active. It also verifies the Codex adapter file (agents/openai.yaml) without following symlinks, and warns when skill listings would exceed provider limits (Claude Code truncates each listing entry at 1,536 characters; the estimated Codex listing is checked against an 8,000-character fallback budget).

skills sync writes .agents/skill-registry.yaml and .agents/skill-reports/skill-health.md with deterministic content and generated markers. It preserves human content outside managed blocks and refuses unmarked files by default. skills routes adds compact active/watch skill routes to .agents/routing.md without copying skill bodies. skills eval --init-workspace creates local planning workspaces under .agents/skill-workspaces/; it does not run Codex unless --runner codex is explicitly provided with a prompt and output path. Workspace snapshots require a readable, non-symlink SKILL.md and copy references/ only.

Codex eval execution uses codex exec --json --sandbox ... and writes JSONL trace output only under .agents/skill-workspaces/. Prefer --sandbox read-only or --sandbox workspace-write. --sandbox danger-full-access also requires --i-understand-danger and is suitable only for isolated CI/container environments. --full-auto is a deprecated legacy alias and should not be used for new automation.

Safety

The inventory skips common secrets, keys, dependency caches, build outputs, local databases, and raw logs. Generated context should describe safety boundaries, not copy sensitive values.

Generated Markdown sections are wrapped with:

<!-- agent-context-maintainer:begin -->
...
<!-- agent-context-maintainer:end -->

The updater replaces only the marked block when both markers exist, preserving hand-written content outside the markers.

Markers are recognized only as standalone lines outside Markdown code fences.

When scaffold runs, existing marked files are updated marker-first: only the generated block is replaced, and hand-written content outside the markers is preserved. Existing unmarked Markdown files are refused by default; pass --append-generated-block to add a managed block or --force-recreate to replace them. Generated-block changes that are not recoverable from git are snapshotted under .agents/snapshots/agent-context-maintainer/ before they are overwritten. Existing .gemini/settings.json files are merged by adding required bridge keys while preserving other settings.

Inventory skips sensitive directory components, symlinks, binary files, large files, archives, dependency caches, build outputs, local databases, and raw logs. Use inventory --explain-skips to see bounded skip reasons.

R