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:

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

1. Run drift detection:

``bash 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.

1. If both pass, report success.
2. 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.

1. 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Arasz
• Source: Arasz/ai-badger
• License: MIT
• Homepage: https://github.com/Arasz/ai-badger

Install and usage instructions live in the source repository linked above.