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
- Treat the current working directory, or the user-specified path, as the context root. Do not scan above it unless the user explicitly asks.
- 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.
- 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.
- Read existing
AGENTS.md, .agents/**, and relevant SKILL.md files before editing. Preserve human-written rules and update only the smallest needed sections.
- 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/
- Keep
AGENTS.md as a thin entry point. Generate CLAUDE.md as a Claude Code entry file that imports AGENTS.md with @AGENTS.md.
- Put durable cross-agent rules in
.agents/core.md, provider/model differences in .agents/profiles/*.md, and task selection rules in .agents/routing.md.
- 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.