thesoftwarehouse/copilot-collections/tsh-creating-instructions

Creating Instructions

Creates well-structured instruction files for GitHub Copilot in VS Code. Covers the repository-level constitution and granular scoped conventions, with clear guidance on what belongs in instructions versus skills.

Core Design Principles

<principles>

<instruction-types> Two types of instruction files exist:

Repository-level instructions (.github/copilot-instructions.md): A single file per repository — the "constitution." Defines architecture, directory structure, languages, frameworks, library versions, and fundamental project constraints. Applied to ALL Copilot interactions in the workspace. No frontmatter required. This is the first file any developer or AI agent should read to understand the project.

Granular custom instructions (*.instructions.md): Multiple files per repository. Support YAML frontmatter with applyTo glob patterns. Applied automatically when matching files are in context, or manually added to chat. Stored in .github/instructions/ folder. These encode file-type-specific or directory-specific coding conventions.

</instruction-types>

<instructions-vs-skills> Instructions define RULES — declarative constraints that Copilot must follow whenever they apply. They are project-specific, loaded automatically, and encode decisions for THIS repository.

Skills define HOW — procedural workflows loaded on-demand by agents to perform specific tasks. Skills are generic, reusable across projects, and encode expert knowledge.

Mental model: Instructions are "the law" (always in force). Skills are "expert handbooks" (consulted for specific tasks). </instructions-vs-skills>

<conciseness> Instruction files compete for the context window with conversation history, skills, and the actual task.

• Keep instructions short and self-contained — each instruction should be a single, simple statement.
• Include the reasoning behind rules (e.g., "Use date-fns instead of moment.js — moment.js is deprecated and increases bundle size").
• Show preferred and avoided patterns with concrete code examples — AI responds more effectively to examples than abstract rules.
• Focus on non-obvious rules — skip conventions that standard linters/formatters already enforce.
• Whitespace between instructions is ignored — format for legibility.

</conciseness>

</principles>

Creation Process

Use the checklist below and track progress:

Creation progress:
- [ ] Step 1: Determine the instruction type
- [ ] Step 2: Define the instruction scope
- [ ] Step 3: Gather content for the instruction file
- [ ] Step 4: Write the instruction file
- [ ] Step 5: Validate the instruction file

Step 1: Determine the instruction type

Determine from context or ask the user. Use the vscode/askQuestions tool to clarify the user's intent if it's ambiguous:

• Is this a NEW project needing its first copilot-instructions.md? → Create repository-level instructions.
• Are there existing copilot-instructions.md and file-specific rules are needed? → Create granular instructions.
• Unsure? → Check if .github/copilot-instructions.md exists. If not, recommend creating it first. The constitution comes before specific laws.

Step 2: Define the instruction scope

For repository-level instructions, the scope is always the entire project. Research by:

• Reading package.json, pyproject.toml, Cargo.toml, go.mod, or equivalent to identify languages, frameworks, and versions.
• Analyzing the directory structure to understand architecture (monorepo, feature-based, layered, etc.).
• Reading existing config files (.eslintrc, tsconfig.json, .prettierrc, etc.) to understand tooling.
• Checking for existing README or architectural documentation.

For granular instructions, determine:

• Which files they apply to (the applyTo glob pattern).
• What specific conventions exist for that file scope.
• Whether an existing instruction file already covers this scope (avoid overlapping applyTo patterns).

applyTo glob pattern reference:

Step 3: Gather content for the instruction file

For repository-level instructions (the constitution), research and document:

1. Architecture — Overall architecture pattern (monorepo, microservices, modular monolith, etc.), directory structure, and responsibility of each top-level directory.
2. Technology Stack — ALL languages, frameworks, and key libraries with specific versions. Critical — Copilot needs exact versions to generate compatible code.
3. Coding Conventions — Conventions NOT enforced by linters/formatters. Architectural rules (e.g., "business logic must not import from UI layer"), project-specific naming conventions, and agreed-upon patterns.
4. Error Handling — The project's error handling strategy.
5. Testing Strategy — Testing approach (unit, integration, E2E), frameworks, and key patterns.
6. Development Workflow — How developers interact with the project. Document task runners (Make, Taskfile, npm scripts, Turbo), containerization (Docker Compose commands), and common developer commands (build, test, lint, migrate, seed). Copilot should use the same scripts and tools a regular developer would — never raw commands when a script exists.

For granular instructions, research and document:

• Specific conventions for the target file scope.
• Preferred patterns with code examples.
• Anti-patterns to avoid with code examples.
• Reasoning behind non-obvious rules.

Use the ./assets/copilot-instructions.template.md and ./assets/custom-instructions.template.md templates as starting points.

Step 4: Write the instruction file

For repository-level instructions:

• Create the file at .github/copilot-instructions.md.
• No frontmatter required.
• Use clear Markdown headers to organize sections.
• Use the ./assets/copilot-instructions.template.md template.

For granular instructions:

• Create the file in .github/instructions/ directory.
• Name the file descriptively: {scope}.instructions.md (e.g., python.instructions.md, react-components.instructions.md, api-endpoints.instructions.md).
• Include YAML frontmatter with name, description, and applyTo.
• Use the ./assets/custom-instructions.template.md template.

Frontmatter fields reference:

Step 5: Validate the instruction file

Validation:
- [ ] File is in the correct location (`.github/copilot-instructions.md` or `.github/instructions/*.instructions.md`)
- [ ] Frontmatter (if present) is valid YAML
- [ ] `applyTo` pattern (if present) matches the intended files — verify with a glob tester
- [ ] Instructions are short and self-contained — each rule is a single statement
- [ ] Non-obvious rules include reasoning ("because...")
- [ ] Preferred/avoided patterns include concrete code examples
- [ ] No duplication of rules already enforced by linters/formatters
- [ ] No procedural workflow content (that belongs in skills)
- [ ] No agent personality or behavior definitions (that belongs in .agent.md)
- [ ] No prompt/workflow triggers (that belongs in .prompt.md)
- [ ] Repository-level file covers: architecture, stack with versions, key conventions
- [ ] Granular files have descriptive, non-overlapping `applyTo` patterns

Quick Reference

Instruction File Types

Priority Order

Higher takes precedence on conflict:

1. Personal instructions (user-level) — highest
2. Repository instructions (.github/copilot-instructions.md or AGENTS.md)
3. Organization instructions — lowest

Connected Skills

• tsh-creating-agents - to ensure agent files don't embed coding standards that belong in instructions
• tsh-creating-skills - to understand the boundary between procedural knowledge (skills) and declarative rules (instructions)
• tsh-creating-prompts - to ensure prompts reference instructions rather than duplicating conventions
• tsh-technical-context-discovering - the complementary skill that discovers and reads existing instruction files
• tsh-codebase-analysing - to analyze existing instruction files and identify patterns to follow