Instructions Creator

Create effective VS Code custom instruction files that shape AI behavior consistently across chat sessions.

Before Creating Instructions

Fetch Latest Documentation

Before writing or overhauling any instructions file, fetch the latest VS Code custom instructions documentation:

1. •Use fetch_webpage to retrieve: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
2. •Extract current file formats, frontmatter options, and best practices
3. •Apply those patterns throughout the instruction design

If the URL is unreachable, fall back to the embedded format reference below.

Fetch Anthropic Prompt Engineering Best Practices

For instruction content quality, also fetch:

1. •https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/overview
2. •https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/be-clear-and-direct
3. •https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/system-prompts

Extract principles for clear, direct, and effective instructions.

Instruction File Types

Always-On Instructions

Automatically included in every chat request. Two formats:

File-Based Instructions

Applied conditionally based on file patterns or task matching:

File Format Reference

Frontmatter (YAML)

---
name: 'Display Name'           # Optional. Shown in UI. Defaults to filename.
description: 'Short summary'   # Optional. Shown on hover in Chat view.
applyTo: '**/*.py'             # Optional. Glob pattern for auto-application.
---

Frontmatter rules:

• •All three fields are optional
• •Without applyTo, instructions are not applied automatically (manual attachment only)
• •applyTo: '**' applies to all files
• •Glob patterns are relative to workspace root

Common applyTo Patterns

Body

Markdown content with the actual instructions. Supports:

• •Standard Markdown formatting
• •Code blocks with examples
• •Markdown links to reference files or URLs
• •Tool references via #tool:<tool-name> syntax

Creation Workflow

Step 1: Determine Instruction Type

Step 2: Gather Requirements

Clarify with the user:

1. •Scope — Project-wide or file-type-specific?
2. •Purpose — Coding standards, architecture rules, workflow conventions, or domain knowledge?
3. •Audience — Solo developer, team, or organization?
4. •Existing instructions — Check for existing .github/copilot-instructions.md, .instructions.md files, or AGENTS.md
5. •Conflicts — Will these instructions contradict or override existing ones?

Step 3: Draft Instructions

Apply the Writing Principles and structure the content using the Instruction Architecture.

Step 4: Review and Validate

Run through the Quality Checklist before delivering.

Writing Principles

These principles are derived from Anthropic's prompt engineering best practices and adapted for VS Code instruction files.

1. Be Clear, Direct, and Specific

Treat the AI as a skilled new team member with no context on project norms.

2. Show, Don't Just Tell

Code examples communicate format, style, and expectations far more effectively than abstract descriptions.

## Naming conventions

### Preferred
```typescript
// React component files: PascalCase
UserProfile.tsx
OrderHistory.tsx

// Utility functions: camelCase
formatCurrency.ts
parseUserInput.ts

// Constants: UPPER_SNAKE_CASE
const MAX_RETRY_COUNT = 3;
const API_BASE_URL = '/api/v2';

Avoid

// ❌ No kebab-case for components
user-profile.tsx

// ❌ No abbreviations
fmtCur.ts

### 3. Use Positive Instructions

State what TO do, not just what NOT to do. Positive instructions are more effective.

| Instead of | Write |
|------------|-------|
| "Don't use `any` type" | "Use explicit TypeScript types for all parameters and return values" |
| "Don't write long functions" | "Extract functions longer than 30 lines into smaller, named functions" |
| "Don't use console.log" | "Use the project logger (`logger.info()`, `logger.error()`) for all output" |

### 4. Include Reasoning Behind Rules

When instructions explain *why* a convention exists, the AI makes better decisions in edge cases.

```markdown
## Error handling

Wrap all API calls in try-catch blocks with typed error responses.
This ensures the frontend always receives a structured error object
instead of an unhandled 500 response.

5. Focus on Non-Obvious Rules

Skip conventions that standard linters or formatters already enforce. The AI knows standard best practices — provide only project-specific or team-specific knowledge.

## What to include
- Project-specific architecture decisions
- Team conventions not covered by ESLint/Prettier
- Domain-specific terminology and patterns
- Integration patterns with internal services

## What to skip
- Basic syntax rules (linter handles these)
- Standard formatting (Prettier handles this)
- General language best practices (AI already knows)

6. Keep Instructions Concise

Each instruction file shares the context window with conversation history, other instructions, and the user's request.

• •Target: 50–150 lines per file for file-based instructions
• •Maximum: 300 lines for always-on instructions (.github/copilot-instructions.md)
• •If longer: split into multiple file-based instruction files with specific applyTo patterns

Instruction Architecture

Structure for Always-On Instructions (copilot-instructions.md)

# Project: [Name]

## Tech Stack
- [Languages, frameworks, key libraries]

## Architecture
- [Key architectural patterns and decisions]

## Coding Conventions
- [Project-specific rules with examples]

## File Structure
- [Important directory conventions]

## Domain Knowledge
- [Business terms, glossary, or domain rules]

## Testing
- [Test conventions and requirements]

Structure for File-Based Instructions

---
name: '[Descriptive Name]'
description: '[When and why these rules apply]'
applyTo: '[glob pattern]'
---

# [Domain] Standards

## Conventions
- [Rules with code examples]

## Patterns
- [Preferred patterns with examples]

## Anti-Patterns
- [What to avoid and why]

Structure for Domain-Specific Instructions

For complex domains, use a focused approach:

---
name: 'API Design'
description: 'REST API conventions for backend services'
applyTo: '**/api/**/*.ts'
---

# API Design Standards

## Endpoint Naming
[Convention with examples]

## Request/Response Format
[Schema patterns with code]

## Error Handling
[Standard error structure]

## Authentication
[Auth pattern for this project]

## Versioning
[API versioning approach]

Instruction Hierarchy and Priority

When multiple instruction files exist, VS Code combines them. Higher priority wins on conflicts:

Conflict resolution strategies:

• •Avoid contradictions between instruction files
• •If unavoidable, add explicit override statements: "This rule supersedes any conflicting instruction about X"
• •Use applyTo patterns to scope rules narrowly and prevent overlap

Quality Checklist

Run every instruction file through this checklist:

Anti-Patterns

Important Rules

• •Always determine the correct instruction type (always-on vs. file-based) before writing
• •Include code examples for every non-trivial rule — examples communicate more than descriptions
• •State rules positively with reasoning — "Use X because Y" beats "Don't use Z"
• •Respect the context window — challenge every line: "Does the AI need this?"
• •Never duplicate what linters, formatters, or the AI already knows
• •Always set applyTo for file-based instructions to ensure automatic application
• •Audit existing instructions for conflicts before adding new ones
• •Keep individual files under 150 lines; split when approaching this limit