# Tool Sp Maintain Agents Instructions

> Review and update repository agent instruction files after code, workflow, or skill changes. Use when: AGENTS.md, GEMINI.md, or .claude/CLAUDE.md may be outdated, the skill catalog changed, or a multi-provider repo needs its instruction bridge refreshed.

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

---


# Maintain Agents Instructions

## Purpose

Guide the agent through a short maintenance wizard so top-level instruction files stay aligned with current repo workflows, skill changes, and provider support without drifting into duplicate or conflicting guidance.

## When to use this skill

- The repo's workflows, commands, or package-manager defaults changed.
- Skills were added, removed, renamed, or substantially rewritten.
- `AGENTS.md`, `GEMINI.md`, or `.claude/CLAUDE.md` may be outdated.
- A repo added multi-provider support and needs a bridge pattern or refresh.

## Scope boundaries

This tool maintains the **instruction files** — `AGENTS.md` and the provider bridges — not the skills
they route to.

- `tool-sp-maintain-skills` — drift inside the skills themselves. The two hand off constantly:
  renaming a skill drifts the routing here, and a rule that outgrew an instruction file usually
  belongs in a skill over there.
- `ref-sp-agents-instructions-authoring` — the rules this tool applies: source-of-truth model, bridge
  pattern, persona placement.
- `ref-sp-agents-mr-wolf-persona` — the canonical persona text. The instruction file carries a
  verbatim projection of it; this tool re-syncs that copy but never rewrites the voice in place.
- Domain detail belongs in the owning skill, not in an instruction file. Moving a rule out of
  `AGENTS.md` and into its skill is a valid outcome of this pass.

## First Step

Read the repo's instruction-authoring skill (`ref-sp-agents-instructions-authoring` here, the `requires` dependency), its agent-persona skill (`ref-sp-agents-mr-wolf-persona` here), and the provider reference files under the instruction-authoring skill's `references/providers/` folder that match the files being touched.

## Core Workflow

1. Inspect the current instruction files and the code or skill changes that may affect them.
2. Ask only the missing questions needed to determine the source of truth, supported providers, and any real provider-specific exceptions.
3. Update the source-of-truth instruction file first.
4. Refresh provider bridge files so they still point back to the source of truth cleanly.
5. Update skill listings, help-routing sections, quick commands, and workflow summaries that drifted.
6. Validate that the files still agree and that bridge files remain thin.

## Defaults

- Prefer a single source-of-truth instruction file plus thin provider bridges.
- Prefer a root `AGENTS.md` as the source of truth; fall back to `.github/copilot-instructions.md` only when the repo is Copilot-centric or already uses that pattern.
- If the repo supports multiple providers, recommend an import bridge rather than parallel duplicated instruction bodies.
- When the repo carries a deliberate persona or working style, keep the persona core **inline** in the source-of-truth file — it must load on every turn — and treat the repo's agent-persona skill (`ref-sp-agents-mr-wolf-persona` here) as the canonical text that copy is refreshed from. Sync in that direction; never rewrite the tone ad hoc in the instruction file. See "Persona placement" in `ref-sp-agents-instructions-authoring`.
- When skill names or workflows change, update both the source-of-truth file and any provider routing summaries that mention them.
- If the top-level instruction file grows too large, move domain detail into the owning skill and keep only routing at the top level.

## Wizard Questions

Ask only the questions that are still unanswered after inspecting the repo.

| Question area | What to ask | Why | When | Expected outcome |
| --- | --- | --- | --- | --- |
| Provider support | Which providers or entry files does this repo actively support now? | The maintenance pass should not update phantom entry points or miss live ones. | When the supported provider set is unclear. | The update scope matches the real instruction surfaces. |
| Source of truth | Which file should own the real repo guidance after this update? | The maintenance pass needs one authoritative file before bridges can be refreshed. | When the current source of truth is unclear or changing. | One file owns the real workflow and policy text. |
| Provider-specific exceptions | Does any provider need a real provider-specific note, or should the bridge stay thin? | Unnecessary provider-specific text creates drift. | When a bridge file is growing or behaving differently. | Exceptions stay narrow and justified. |
| Drift scope | Which commands, workflows, skills, or policies changed? | The maintenance pass should update the exact sections that drifted, not rewrite the whole file blindly. | When the triggering change is broad or loosely described. | The edit is focused on the real drift surface. |

## Gotchas

- Do not rewrite every instruction file independently if an import bridge already exists.
- Do not leave skill listings or quick-command sections stale after renames or workflow changes.
- Do not move framework or language detail into the top-level instructions when the owning skill should hold it.
- If the repo already uses policy-managed files such as `.aiexclude` or `.claude/settings.json`, instruction updates should still match that model.

## Validation

- Check the result against the instruction-authoring skill's checklist (`ref-sp-agents-instructions-authoring`; in this repo, its `references/checklist.md`).
- Confirm the source-of-truth file and bridge files still agree.
- Confirm provider bridge files remain minimal unless a real provider-specific exception exists.
- Run a targeted error check on the touched instruction files before concluding.

## References

- Read the instruction-authoring skill's provider references (`ref-sp-agents-instructions-authoring`; in this repo, its `references/providers/copilot-instructions.md`, `references/providers/gemini-instructions.md`, and `references/providers/claude-instructions.md`) for file-specific authoring rules.
- Use the repo's agent-persona skill (`ref-sp-agents-mr-wolf-persona` here) when the instruction changes need to preserve the repo's agent voice, interaction style, or escalation stance.
- Use the repo's skill-maintenance skill (`tool-sp-maintain-skills` here) when the instruction pass also needs skill consolidation or routing cleanup.
- Use the repo's agent-security skill (`ref-sp-agents-security` here) when instruction changes must stay aligned with generated policy files or provider restrictions.