# Maintain Agent Instructions

> Use when agent instruction files have drifted from each other or from the policy model — CLAUDE.md, copilot-instructions.md, AGENTS.md, hosted-review and path-scoped instruction files — or when validation/drift checks fail in CI. Reconciles them from the machine-readable model in .ai-badger/agent-instructions/.

- Skill: `arasz/maintain-agent-instructions-2` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add arasz/maintain-agent-instructions-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arasz/maintain-agent-instructions-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: Arasz (https://skillmd.com/u/arasz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arasz/maintain-agent-instructions-2

---


# 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
   ```

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

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