Agent Setup Maintenance

Agent Setup Maintenance

Use this skill when changing the shared agent setup for the repository.

Start Here

• Read ../../README.md for the shared config and shim model.
• Read root ../../AGENTS.md for repo-level expectations.
• When adding or editing shared skills, use

../skill-creator/SKILL.md, then apply the

repo-specific checks in this skill.

• Inspect ../../../scripts/agents/sync-agent-shims.mjs

before changing generated outputs or provider discovery behavior.

• Inspect ../../../scripts/postinstall.sh

and ../../../package.json when changing install-time

sync behavior.

Workflow

• Edit the canonical files under .agents/, not generated provider outputs.
• Keep root AGENTS.md and CLAUDE.md as discovery symlinks; do not turn

them back into manually maintained copies.

• Treat tool-specific directories such as .claude/, .cursor/, .codex/,

.vscode/, and .mcp.json as generated discovery surfaces unless the tool

requires a truly tool-specific feature.

• Keep root AGENTS.md concise. Move detailed or conditional workflows into

shared skills or package AGENTS.md files.

• Treat developer feedback as a learning loop: when a task reveals a durable

repo convention, recurring pitfall, reusable workflow, or verification

pattern, update the smallest relevant AGENTS.md or shared skill.

• When adding or changing a shared skill, keep SKILL.md as the entrypoint; do

not add skill-by-skill links to root AGENTS.md.

• When shared setup behavior changes materially, update README.md and

contributor-facing docs in the same PR.

Docker / Install-Time Constraint

• pnpm install runs in environments that may not contain the full repo source

tree.

• In Docker builds, Turbo's pruned install stage can run root postinstall

before scripts/ and .agents/ are available in the image.

• Keep install-time agent setup logic robust in those pruned contexts: skip

cleanly when the required repo-owned files are not present.

Required Verification

Run after changing shared agent setup:

• pnpm run agents:sync
• pnpm run agents:check

Run additional verification when relevant:

• pnpm run postinstall when install-time behavior changes
• targeted tests for any scripts you changed

Design Rules

• Prefer one repo-owned source of truth over duplicated provider-specific files.
• Keep shared setup tool-neutral where possible.
• Only keep provider-specific files in source control when the provider requires

a fixed discovery path or feature that cannot be expressed through the shared

setup model.