Swiftpostlab Agentic Tools Ref Agents Instructions Authoring

Agents Instructions Authoring

Purpose

Provide portable defaults for designing maintainable repository instruction systems across the major agent entry points without duplicating the same workflow, policy, and routing text in every provider file.

When to use this skill

• Creating or refactoring repo instruction files.
• Deciding where the source of truth for instructions should live.
• Adding Gemini or Claude support to a repo that already has Copilot instructions, or the reverse.
• Reviewing whether top-level instruction files still match the codebase and the skill catalog.

Scope Boundaries

• Use this skill for the overall instruction architecture across providers.
• Use ./references/providers/copilot-instructions.md for what belongs specifically in .github/copilot-instructions.md.
• Use ./references/providers/gemini-instructions.md for GEMINI.md bridge or provider-specific decisions.
• Use ./references/providers/claude-instructions.md for .claude/CLAUDE.md bridge or provider-specific decisions.
• Use .agents/skills/ref-agents-persona/SKILL.md when the instruction system needs to preserve or refresh the repo's agent voice, interaction style, or escalation stance.
• Use .agents/skills/ref-skills-authoring/SKILL.md for authoring skills rather than top-level instruction files.
• Use .agents/skills/tool-maintain-agents-instructions/SKILL.md when the user wants a guided update workflow instead of just the reference guidance.

Major Provider References

• GitHub Copilot: ./references/providers/copilot-instructions.md
• Google Gemini: ./references/providers/gemini-instructions.md
• Anthropic Claude: ./references/providers/claude-instructions.md

Defaults

• Choose one source-of-truth instruction file for the repo.
• Prefer .github/copilot-instructions.md as the source of truth when the repo already supports Copilot or needs a broadly readable markdown home.
• Use thin provider bridge files for Gemini and Claude by default rather than duplicating the full instruction set.
• Keep always-on repo rules in the source-of-truth file and move domain-specific detail into skills.
• Add provider-specific exceptions only when a real platform behavior requires them.

Task Framing

Core Rules

Source-of-truth model

• Make one file authoritative.
• If the repo already has a mature .github/copilot-instructions.md, keep it as the default source of truth unless there is a concrete reason not to.
• Avoid parallel hand-maintained instruction bodies across several provider files.

Import bridge pattern

• In multi-provider repos, prefer a bridge pattern where the provider-specific entry files import or route back to the source-of-truth file.
• Keep bridge files minimal and readable.
• Use repo-root imports when the provider supports them so the bridge does not depend on folder depth.

Provider-specific exceptions

• Add provider-specific text only when the platform has a real bootstrap requirement, limitation, or routing constraint.
• Keep the provider-specific exception narrow and then route back to the shared instructions.
• Do not duplicate the full workflow, command list, or policy text in the provider bridge file when a reference is enough.

Maintenance

• Review top-level instructions when quick commands, workflow defaults, safety policy, or the skill catalog changes.
• If the repo adds or removes important skills, update both the skill inventory and the routing hints in the source-of-truth file.
• Keep instruction files aligned with generated policy files and provider settings when the repo uses them.

Validation

• The repo has one clear instruction source of truth.
• Bridge files stay thin unless a provider-specific exception is genuinely required.
• Top-level instructions contain durable repo workflow and routing, not duplicated domain detail.
• The instruction files still match the current skills, commands, and policy model.

References

• Read ./references/providers/copilot-instructions.md for Copilot-specific source-of-truth guidance.
• Read ./references/providers/gemini-instructions.md for GEMINI.md bridge guidance.
• Read ./references/providers/claude-instructions.md for .claude/CLAUDE.md bridge guidance.
• Read ./references/checklist.md for a quick multi-provider instruction review pass.
• Read ./references/import-bridge.md when choosing between thin stubs, bridge files, and rare split-source patterns.
• Read ./assets/trigger-eval-queries.example.json when testing trigger quality for instruction-authoring prompts.
• Review ./evals/evals.json when validating output quality for source-of-truth and bridge recommendations.

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