Maintain Agent Instructions

Maintain agent instructions

This skill keeps agent guidance consistent while minimizing always-loaded context. It follows a hub-and-spoke model: one compact, always-loaded entrypoint per agent (CLAUDE.md, .github/copilot-instructions.md, …) plus detailed, path-scoped or on-demand instruction files. The model is machine-readable so drift between agent files can be checked by script instead of by eye — if the project records this decision as an ADR, link it here.

When NOT to Use

• A single-file typo fix in one instruction file — edit it directly
• No drift exists and CI checks pass
• Authoring brand-new policy from scratch — that is content work, not reconciliation

Principles

• Use scripts first; inspect only failing files/rules.
• Keep each agent's always-loaded entrypoint compact. Put detailed guidance in scoped or on-demand files.
• Update the agent-instructions model (.ai-badger/agent-instructions/model.json by default; see references/agent-instruction-model.md) when changing shared policy.
• Treat .github/instructions/*.instructions.md (or the project's equivalent) as the shared path-scoped implementation rule source.
• Do not rewrite every agent file just to rephrase. Make the smallest consistency-preserving edit.
• The scripts are check-only by default; the agent handles semantic policy decisions and wording.

Standard workflow

1. Run validation:

   node .ai-badger/skills/maintain-agent-instructions/scripts/validate-agent-instructions.mjs
   

2. Run drift detection:

   node .ai-badger/skills/maintain-agent-instructions/scripts/check-agent-drift.mjs
   

   Both scripts are #!/usr/bin/env node and import only node:fs / node:path — Node 18+, no bundler, no dependencies. Run them from the project root; they read process.cwd() and AGENT_INSTRUCTIONS_DIR (default .ai-badger/agent-instructions). Adjust the path prefix if the skill was scaffolded elsewhere.

3. If both pass, report success.

4. If either fails:

   • inspect only the reported files and rules,
   • update the model if the policy changed,
   • update the smallest affected instruction file(s),
   • rerun both scripts.

5. If the change modifies architecture/process policy, add or update an ADR (if the project keeps one).

Copilot compatibility

GitHub Copilot CLI and Copilot coding agent discover repository instructions in standard files, including .github/copilot-instructions.md, .github/instructions/**/*.instructions.md, AGENTS.md, and CLAUDE.md. Keep Copilot-compatible rules in .github/copilot-instructions.md and .github/instructions/*; the validation scripts are plain command-line checks so Copilot-driven automation or CI can run the same checks.

Script style

Scripts are small deterministic helpers. They should:

• avoid LLM calls,
• avoid network calls,
• read the agent-instructions model (path resolved via AGENT_INSTRUCTIONS_DIR, default .ai-badger/agent-instructions; read references/agent-instruction-model.md when writing a script that reads the model),
• report precise file/rule failures,
• exit non-zero on errors,
• keep warnings separate from errors,
• avoid editing files unless a future explicit --write mode is added.

Read references/agent-instruction-model.md when the model contract is in question and references/copilot-compatibility.md when phrasing a Copilot-specific rule.

Gotchas

No environment-specific gotchas known.

Verification Checklist

• Both scripts ran from the project root
• Both exit 0 — or every reported failure was fixed and the re-runs pass
• Only the reported files and rules were touched
• The model was updated before any shared-policy change
• ADR added or updated when architecture/process policy changed