Maximizing VS Code Copilot Customization for Modern TypeScript Development

Copilot gives generic answers until you tell it how your project works. In VS Code you do that with Markdown files that live next to your code: project-wide instructions, targeted instruction files, reusable prompts, and settings for commit messages.

I first wrote this post in June 2025. Parts of it have aged. Custom chat modes became custom agents, prompt files are being folded into agent skills, and several location settings are deprecated. This version reflects the current VS Code docs and flags what changed.

Why customize Copilot for TypeScript?

Without context, Copilot guesses. It will happily write a class component in a codebase that only uses hooks, or a default export where your team uses named exports. Customization fixes that at the source:

• Your React and TypeScript conventions apply without retyping them in every chat.
• Commit messages follow one format.
• Repetitive tasks, such as scaffolding a form, become one slash command.
• The rules live in version control, so the whole team gets them.

I removed a claim from the first version about customized setups giving "40% faster feature delivery and 25% fewer bugs". I can't trace it to a source, and I won't repeat a number I can't back. The honest benefit is consistency: fewer review comments about style, and less time re-explaining the project.

The customization types at a glance

Two caveats shape everything below. Instruction support depends on the agent harness you select in a session, so the exact file locations differ between the Local agent, Copilot, and others. And custom instructions are not used for inline suggestions as you type, only for chat.

Project instructions

The file most people start with is .github/copilot-instructions.md. It holds project-wide context that applies to every chat request. VS Code also reads AGENTS.md at the repository root, a cross-agent format that Codex and other tools understand. If you use more than one AI coding tool, AGENTS.md lets you keep a single source of truth. For the Local agent you can toggle it with the chat.useAgentsMdFile setting.

Here is a trimmed version of the file I use for this portfolio:

# Coding Guidelines

## Introduction

- This project is a portfolio website built with GatsbyJS. It uses TypeScript, functional components, and functional programming principles.
- The project uses `bun` as the package manager.
- Key files: gatsby-config.ts, tailwind.config.js, tsconfig.json, package.json, gatsby-node.ts, components.json

## Coding Guidelines

- Enable strict type-checking in tsconfig.json.
- Use Tailwind CSS, shadcn/ui, and lucide-react icons.
- Validate forms with react-hook-form and zodResolver.
- For TypeScript and React specifics, see the files in `.github/instructions/`.

Keep it short and factual. Name the tools, the package manager, the key config files, and the rules that are easy to get wrong. Anything that only applies to some files belongs in a targeted instruction file instead.

Instruction files for TypeScript and React

Instruction files use the .instructions.md extension. Their applyTo glob attaches them automatically when the agent creates or modifies a matching file. The frontmatter also accepts name and description; a clear description helps the agent decide to load the file for a related task even when no glob matches.

---
name: 'React with TypeScript'
description: 'Use when creating or editing React components.'
applyTo: '**/*.tsx'
---

# React with TypeScript style guide

- Use functional components and hooks only
- Type props with interfaces
- Specify return types for exported functions
- Use camelCase for variables, PascalCase for components

To create one, run Chat: Open Customizations from the Command Palette and add an instructions file from the editor, or create it by hand.

Where they live

VS Code searches these folders recursively, so you can group files by team or module. My first version pointed at ~/Library/Application Support/Code/User/prompts and told you to set chat.instructionsFilesLocations. That setting is now deprecated and used only by the Local agent. Put files in the default locations and skip it.

One correction to the original: I wrote that Copilot "merges" global and workspace files. The docs are more careful. Applicable instruction sources are additive, and you should not rely on an ordering rule to settle conflicts. If two files disagree, fix the contradiction at its source.

Commit .github/instructions/ to share it with your team.

Prompt files, and where they are heading

A prompt file is a .prompt.md file you invoke as a slash command. It suits repeatable tasks you start deliberately, unlike instructions, which apply on their own.

---
description: 'Plan a refactor to improve readability, maintainability, and cyclomatic complexity.'
agent: 'ask'
---

Analyze how this codebase is structured and propose a refactoring plan.

- Focus on structure, readability, testability, and maintainability
- Identify functions with high cyclomatic complexity
- Suggest changes in order of impact

Note the agent field. My original example used mode: 'ask', which came from the chat modes era. The current fields are description, name, argument-hint, agent, model, and tools. The agent value can be ask, agent, plan, or the name of a custom agent.

The bigger change is the status. Prompt files are deprecated for Agent Host sessions and are not loaded there. They still work with the Local agent, but the docs say the Local agent will be removed in a future release. VS Code ships a migration that converts workspace and user prompt files into agent skills. Open the Agent Customizations editor, go to the Overview tab, and use Convert to Skills. Review the results afterward, because prompt frontmatter properties that skills don't support are not carried over.

My advice: if you are starting today, write a skill instead of a prompt file. Keep existing prompt files working, and migrate them when you next touch them.

Agent skills

A skill is a folder with a SKILL.md file, plus any scripts or reference files it needs. It is an open standard, so the same skill works across several tools.

---
name: refactor-plan
description: Plan a refactor for readability and lower cyclomatic complexity. Use when asked to clean up or restructure code.
---

# Refactor plan

1. Map the module structure and find the highest-complexity functions.
2. Propose changes ordered by impact and risk.
3. List the tests that protect each change.

The rules that trip people up:

• name must be lowercase letters, numbers, and hyphens, and must match the parent directory name. A mismatch means the skill silently fails to load.
• description should say what the skill does and when to use it. The agent uses it to decide whether to load the skill.
• Project skills go in .github/skills/, .claude/skills/, or .agents/skills/. Personal skills go in ~/.copilot/skills/, ~/.claude/skills/, or ~/.agents/skills/.
• Skills show up in the / menu next to prompt files. Set user-invocable: false to hide one from the menu, or disable-model-invocation: true to run it only on demand.

Custom agents

If a task needs its own tool selection, a custom agent is the right unit. It is an .agent.md file that combines instructions, tools, and an optional model. A read-only planning agent and a review agent with your team's criteria are the typical cases. These were called custom chat modes before. If you still have .chatmode.md files, rename them to .agent.md.

Commit message customization

Settings-based instructions for code generation and test generation were deprecated in VS Code 1.102 in favor of file-based instructions. Commit messages are different: the docs still describe settings for commit messages, code review of selected code, and pull request descriptions. Each accepts an array of objects with either a text property or a file property pointing at a Markdown file.

{
  "github.copilot.chat.commitMessageGeneration.instructions": [
    {
      "text": "Use the Conventional Commits format: <type>(<scope>): <subject>, then a blank line and an optional body."
    },
    {
      "text": "Types: feat, fix, docs, style, refactor, perf, test, chore."
    },
    {
      "text": "Subject: imperative mood, capitalized, under 50 characters, no trailing period."
    },
    {
      "text": "Body: wrap at 72 characters. Explain what and why, not how. Use bullets for multiple points."
    },
    {
      "text": "Footer: reference issues as Closes #123. Start breaking changes with BREAKING CHANGE:."
    }
  ]
}

The file form is easier to maintain once the rules grow. Point it at a Markdown file in the repo and the team shares one definition.

I dropped the Gitmoji requirement from the original. It works, but it adds emoji to your git history, and I found it noisier than useful. Add it back if your team likes it.

Typical output:

feat(ui): Add user profile page

• Add a form for updating user details
• Validate input with Zod

Closes #456

A setup you can copy

1. Create .github/copilot-instructions.md with the stack, package manager, and key files.
2. Add .github/instructions/react-typescript.instructions.md with applyTo: '**/*.tsx'.
3. Add .github/instructions/tests.instructions.md with applyTo: '**/*.spec.ts'.
4. Write one skill in .github/skills/ for the task you repeat most.
5. Add the commit message setting to your user or workspace settings.json.
6. Commit the .github/ folder so the team picks it up.

How the pieces fit together

<!-- diagram: flow-copilot-customization -->

flowchart LR
    R[Chat request] --> P[Project instructions: always]
    R --> I[Instruction files: by file or task]
    R --> S[Skills, prompts, agents: on demand]
    P --> C[Combined context]
    I --> C
    S --> C

Troubleshooting

• Copilot ignores a file. Check that it sits in a supported location for the harness you selected, and that the applyTo glob matches the file being edited.
• A skill never loads. Confirm name matches the directory name and uses only lowercase letters, numbers, and hyphens.
• Inline suggestions ignore everything. That is expected. Custom instructions apply to chat, not to completions as you type.
• Two files contradict each other. Instructions are additive with no guaranteed precedence. Remove the duplication.
• A setting from an old tutorial does nothing. chat.instructionsFilesLocations, chat.agentFilesLocations, chat.modeFilesLocations, and chat.agentSkillsLocations are deprecated for Agent Host sessions.

Where to go next

Start with the project instructions file and one targeted instruction file. Those two cover most of the value and take ten minutes. Add a skill only when you notice yourself pasting the same prompt a third time, and keep every file short enough that you would actually maintain it.

If you want to draft prompts for other tasks, the blog post prompt generator on this site is one I built for exactly that.

References

• Use custom instructions in VS Code
• Use prompt files in VS Code
• Use Agent Skills in VS Code
• Custom agents in VS Code
• Create and manage agent customizations
• Gain control over commit messages generated by GitHub Copilot