Swiftpostlab Agentic Tools Tool 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.
• .github/copilot-instructions.md, GEMINI.md, or .claude/CLAUDE.md may be outdated.
• A repo added multi-provider support and needs a bridge pattern or refresh.

First Step

Read .agents/skills/ref-agents-instructions-authoring/SKILL.md, .agents/skills/ref-agents-persona/SKILL.md, 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 .github/copilot-instructions.md as the source of truth when the repo 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 that voice aligned with .agents/skills/ref-agents-persona/SKILL.md instead of rewriting tone ad hoc.
• 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.

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 .agents/skills/ref-agents-instructions-authoring/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 .agents/skills/ref-agents-instructions-authoring/references/providers/copilot-instructions.md, .agents/skills/ref-agents-instructions-authoring/references/providers/gemini-instructions.md, and .agents/skills/ref-agents-instructions-authoring/references/providers/claude-instructions.md for file-specific authoring rules.
• Use .agents/skills/ref-agents-persona/SKILL.md when the instruction changes need to preserve the repo's agent voice, interaction style, or escalation stance.
• Use .agents/skills/tool-maintain-skills/SKILL.md when the instruction pass also needs skill consolidation or routing cleanup.
• Use .agents/skills/ref-agents-security/SKILL.md when instruction changes must stay aligned with generated policy files or provider restrictions.

Source: swiftpostlab/agentic-tools — distributed by TomeVault.