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.

<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: