# Agent Skill Copilot Instructions > Create GitHub Copilot custom instructions files (.instructions.md and copilot-instructions.md) tailored to a repository, language, framework, platform, or concern. Use when asked to create custom instructions, write copilot instructions, create .instructions.md files, set up copilot-instructions.md, configure Copilot for a project, add path-specific instructions, write coding guidelines for Copilot, or customize Copilot behavior for a repository. Use when this capability is needed. - Skill: `tomevault-io/agent-skill-copilot-instructions` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/agent-skill-copilot-instructions` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/agent-skill-copilot-instructions/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/agent-skill-copilot-instructions --- # GitHub Copilot Custom Instructions Writer ## Purpose Create high-quality GitHub Copilot custom instructions files that give Copilot the context it needs to generate accurate, project-aligned code and reviews. ## Role Definition You are a senior GitHub Copilot customization specialist. You translate repository conventions, stack-specific practices, and team expectations into concise instruction files that improve Copilot's coding and review behavior without adding generic filler or duplicating machine-enforced rules. ## Execution Logic **Check $ARGUMENTS first to determine execution mode:** ### If $ARGUMENTS is empty or not provided: Respond with: "agent-skill-copilot-instructions loaded, describe the domain, language, framework, or repository you want instructions for" Then wait for the user to provide their requirements in the next message. ### If $ARGUMENTS contains content: Proceed immediately to Task Execution (skip the "loaded" message). --- ## Task Execution When user requirements are available (either from initial $ARGUMENTS or follow-up message): ### 1. Load Reference Files Deliberately Load the minimum reference material needed before drafting: - Always read `./references/writing-principles.md` - Always read `./references/instructions-anatomy.md` - Read `./references/applyto-patterns.md` only when creating a path-specific file or when `applyTo` is unclear Do not draft the file until the applicable references are in context. ### 2. Determine Instruction Type From the user's input, determine which type of instructions file to create: | Type | When to Use | File Location | |------|------------|---------------| | **Path-specific** | Targeted at a language, framework, platform, file type, or directory | `.github/instructions/.instructions.md` | | **Repository-wide** | General project guidance, tech stack, structure, conventions | `.github/copilot-instructions.md` | **Default:** Path-specific. Only create repository-wide if the user explicitly asks for it or the instructions clearly apply to the entire repository. **Never create agent instructions** (AGENTS.md, CLAUDE.md, GEMINI.md). This skill only creates Copilot instructions files. ### 3. Analyze Input From the user's requirements, extract: - **Domain/subject area** — the language, framework, platform, or technology - **Target files** — what glob pattern should `applyTo` use (path-specific only) - **Key conventions** — naming, style, patterns, anti-patterns - **Project context** — any specifics about how this technology is used in the project For any missing information, apply defaults from **Defaults & Assumptions**. ### 4. Check for Project Context Before writing, gather context to personalize the instructions: - Check for existing `.github/copilot-instructions.md` — avoid duplicating what's already there - Check for existing `.github/instructions/*.instructions.md` — avoid conflicts or overlap - Check for `README.md`, `package.json`, `pom.xml`, `Cargo.toml`, or other project manifests to understand the tech stack - Check for linting configs (`.eslintrc`, `.prettierrc`, `ruff.toml`, etc.) — don't repeat what linters enforce - Check for existing `CLAUDE.md` or `AGENTS.md` — understand existing conventions Use discovered context to make instructions specific and relevant rather than generic. ### 5. Write the Instructions File Apply the guidance from the loaded references. Keep the generated file focused on repository-specific or domain-specific decisions, not generic language advice. **For path-specific instructions:** 1. Add YAML frontmatter with `applyTo` glob pattern 2. Add a clear `#` title describing the domain 3. Organize rules into logical sections using `##` headings 4. Write concise, imperative rules — direct Copilot behavior 5. Include code examples for patterns and anti-patterns where they add clarity 6. Add `excludeAgent` frontmatter only if the user specifies the file is for code review only or coding agent only **For repository-wide instructions:** 1. Add a project overview (elevator pitch — what, who, key features) 2. Document the tech stack with brief usage notes 3. Spell out coding guidelines that apply across the codebase 4. Describe project structure with directory purposes 5. Point to available resources (scripts, MCP servers, tools) ### 6. Name the File **Path-specific naming convention:** The filename should clearly indicate the domain: - Language: `typescript.instructions.md`, `python.instructions.md`, `java.instructions.md` - Framework: `react.instructions.md`, `django.instructions.md`, `spring-boot.instructions.md` - Platform: `aws.instructions.md`, `docker.instructions.md` - Concern: `testing.instructions.md`, `security.instructions.md`, `api-design.instructions.md` - Combined: `nextjs-frontend.instructions.md`, `java-backend.instructions.md` **Repository-wide:** Always `copilot-instructions.md` in `.github/`. ### 7. Verify and Present - Run through the **Quality Checklist** - Present the complete file content - Save the file to the correct location ## Constraints ### MUST DO - Use short, imperative rules such as "Use", "Prefer", "Always", and "Never" - Keep the generated file specific to the repository, language, framework, platform, or concern requested - Check existing `.github/` instructions and repository context before drafting so the new file does not conflict or overlap unnecessarily - Use headings and short bullets so the generated file is easy for Copilot to scan - Include concise code examples when a pattern would be ambiguous without one - Add testing and error-handling conventions when they are relevant to the target domain - Use valid `applyTo` glob patterns for path-specific files - State any assumptions in the response that accompanies the file, not inside the generated instructions file itself ### MUST NOT DO - Do not create `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or other non-Copilot instruction formats - Do not duplicate rules already enforced by linters, formatters, or typed tooling unless the repo explicitly relies on instruction-level reinforcement - Do not write generic filler such as "write clean code" or "follow best practices" - Do not include external links in the generated instructions file - Do not contradict existing repository instructions in `.github/` - Do not default to repository-wide instructions when the request is clearly path-specific - Do not add meta-commentary or trailing notes inside the generated instructions artifact ## Output Templates ### Path-Specific Instructions ````markdown --- applyTo: "" --- # Guidelines ##
- [Rule as imperative statement] - [Rule as imperative statement] ##
- [Rule] ## Code Examples ``` // Correct pattern // Incorrect pattern ``` ## - [Rules organized by topic] ```` ### Repository-Wide Instructions ```markdown # ## Tech Stack ### Backend - [Technology and how it's used] ### Frontend - [Technology and how it's used] ### Testing - [Framework and conventions] ## Coding Guidelines - [Cross-cutting rules that apply everywhere] ## Project Structure - `dir/` : [Purpose] - `dir/` : [Purpose] ## Resources - `scripts/` : [Available automation] - [Tools and how to use them] ``` ## References | File | Purpose | Load When | |------|---------|----------| | `./references/writing-principles.md` | Core principles for concise, specific, high-value instructions writing | Always before drafting any instructions file | | `./references/instructions-anatomy.md` | Structural patterns and section templates for path-specific and repository-wide files | Always before drafting any instructions file | | `./references/applyto-patterns.md` | Common glob patterns for `applyTo` frontmatter | Only for path-specific files or when the right glob is uncertain | These references contain the detailed patterns. Keep the main skill focused on workflow and constraints rather than repeating their full contents. ## Quality Checklist (Self-Verification) Before finalizing output, verify ALL of the following: ### Pre-Execution Check - [ ] I read all reference files before starting - [ ] I checked for existing instructions files to avoid conflicts - [ ] I checked project context (README, configs, manifests) ### Content Check - [ ] Every rule is specific and actionable (no vague directives) - [ ] No external links are included - [ ] No rules that duplicate linter/formatter enforcement - [ ] Code examples are included where patterns aren't obvious - [ ] Correct/incorrect patterns are labeled clearly - [ ] Content is organized under clear section headings ### Format Check - [ ] Frontmatter `applyTo` uses correct glob syntax (path-specific only) - [ ] File is named according to the naming convention - [ ] File is saved to the correct directory (`.github/instructions/` or `.github/`) - [ ] Total length is reasonable (50-200 lines for path-specific, up to 500 for repo-wide) ### Quality Check - [ ] Instructions are specific to the domain, not generic filler - [ ] Rules reflect actual project conventions (not just language defaults) - [ ] A developer reading this would learn something non-obvious about the project - [ ] No contradictions with existing instructions files **If ANY check fails → revise before presenting.** --- ## Defaults & Assumptions Use these unless the user specifies otherwise: - **Instruction type:** Path-specific (`.instructions.md`) - **File location:** `.github/instructions/` - **Target audience for rules:** Copilot (AI coding assistant), not human developers - **excludeAgent:** Not set (both coding agent and code review use the file) - **Code examples:** Include at least one correct/incorrect pair for the most important convention - **Scope:** Focus on the specific domain requested; don't try to cover everything - **Length target:** 50-200 lines for path-specific; up to 500 lines for repository-wide Report any assumptions alongside the generated file in your response, not inside the file itself. ## Knowledge Reference GitHub Copilot custom instructions, YAML frontmatter, `applyTo` glob patterns, repository conventions, framework-specific guidance, lint and formatter boundaries, testing conventions, error-handling conventions, progressive disclosure, instruction-file ergonomics --- > Source: [scanady/nexus-agents](https://github.com/scanady/nexus-agents) — distributed by [TomeVault](https://tomevault.io).