# Swiftpostlab Agentic Tools Ref Agents Instructions Authoring > Agents Instructions Authoring - Skill: `tomevault-io/swiftpostlab-agentic-tools-ref-agents-instructions-authoring` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/swiftpostlab-agentic-tools-ref-agents-instructions-authoring` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/swiftpostlab-agentic-tools-ref-agents-instructions-authoring/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/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 | Command or action | What | Why | When | Expected outcome | | --- | --- | --- | --- | --- | | Choose the instruction source of truth | Decide which file owns the actual repo guidance. | Instruction systems drift quickly when several entry files all act authoritative. | When setting up or refactoring multi-provider support. | One file owns the real policy and workflow text. | | Design the import bridge | Route other provider entry files back to the source-of-truth file with minimal local text. | Thin bridge files reduce duplication while preserving provider compatibility. | When the repo supports more than one AI entry point. | The provider files stay short and the effective guidance still matches. | | Separate always-on rules from on-demand detail | Keep durable repo workflow and safety rules in the top-level instructions and move domain specifics into skills. | Bloated instruction files become harder to maintain and easier to contradict. | When top-level instructions start absorbing framework or language detail. | Instruction files stay durable and the skills remain discoverable. | ## 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](https://github.com/swiftpostlab/agentic-tools) — distributed by [TomeVault](https://tomevault.io).