GitHub Copilot Agent Mode and SKILL.md: Setup Guide

GitHub Copilot's agent mode in VS Code can read SKILL.md files to understand your project context, but it's not obvious how to set this up correctly. The agent mode scans for specific file patterns and uses them to provide better code suggestions.

Agent mode expects files in your workspace root or .vscode folder. Drop your SKILL.md in either location and Copilot will pick it up automatically on the next restart.

How GitHub Copilot agent mode processes SKILL.md

When you activate agent mode, Copilot reads markdown files that follow specific naming patterns. SKILL.md files get parsed during workspace initialization. The content becomes part of Copilot's context window for that session.

Your SKILL.md should contain the project's purpose, architecture decisions, and coding patterns. Copilot uses this information to suggest code that matches your existing style and conventions.

# Project: expense-tracker-api

## Purpose
REST API for personal expense tracking with SQLite database and JWT authentication.

## Architecture
- Express.js server on port 3000
- SQLite database with migrations in /db/migrations
- JWT tokens for auth, stored in httpOnly cookies
- Input validation using Joi schemas

The agent reads this context before generating suggestions. It won't suggest PostgreSQL drivers if you specify SQLite. It won't recommend session storage if you use JWT.

File placement and discovery

Copilot checks these locations in order:

Workspace root: SKILL.md
.vscode/SKILL.md
docs/SKILL.md (sometimes works, inconsistent)

The workspace root placement works most reliably. If you have multiple projects in one workspace, place the SKILL.md at the workspace root, not in individual project folders.

For teams sharing skills, the .vscode folder makes sense. Add it to version control and everyone gets the same context. For personal projects, workspace root keeps it visible.

What works in agent mode context

Copilot agent mode handles these SKILL.md sections well:

Technology stack declarations - List your main dependencies and Copilot suggests compatible packages. Mention React 18 and it suggests React 18 patterns, not class components.

Database schema information - Include table structures and Copilot generates queries that match your schema. No more suggestions for columns that don't exist.

API endpoint patterns - Document your routing conventions and error handling approach. Copilot will follow the same patterns for new endpoints.

Environment variables - List configuration keys and Copilot references them correctly in code suggestions.

You can browse skills to see examples that work well with agent tooling.

What doesn't work reliably

Some SKILL.md content gets ignored or misinterpreted by Copilot's agent mode:

Complex workflow descriptions - Long prose about business logic confuses the model. Keep descriptions short and technical.

Nested folder structures - Copilot doesn't always understand deep project hierarchies from markdown descriptions. File paths work better than folder explanations.

Conditional logic in documentation - "Use X if Y, otherwise Z" statements don't translate well. Pick one approach and document that.

External service integrations - Third-party API details get mixed up with your internal code patterns. Keep external references minimal.

The SKILL.md spec covers the technical format that works best with AI tools.

Integration with VS Code workspace settings

Agent mode combines SKILL.md content with your VS Code workspace configuration. This creates conflicts if the settings contradict your skill file.

If your SKILL.md mentions TypeScript strict mode but your tsconfig.json has strict disabled, Copilot gets confused about which rules to follow. Keep both files aligned.

Workspace settings for formatters and linters take precedence over SKILL.md style guidelines. Set up Prettier and ESLint configuration first, then document those choices in your skill file.

{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.preferences.importModuleSpecifier": "relative",
  "eslint.workingDirectories": ["./src"]
}

Your SKILL.md can reference these settings but shouldn't duplicate them.

Performance and context limits

GitHub Copilot agent mode has token limits that affect how much of your SKILL.md gets processed. Files over 2000 words get truncated randomly, not from the end.

Put the most important information first: technology stack, main architecture decisions, critical patterns. Save detailed examples and explanations for later sections.

Multiple smaller files work better than one large SKILL.md. Split complex projects into focused skill files:

SKILL-api.md for backend patterns
SKILL-frontend.md for UI components
SKILL-database.md for data layer conventions

Agent mode reads multiple files but processes them separately, reducing context mixing.

Comparison with other skill formats

SKILL.md works differently than MCP servers or other AI integration patterns. MCP provides real-time function calls while SKILL.md gives static context.

For GitHub Copilot specifically, SKILL.md files provide better integration than CLAUDE.md spec files. Copilot's agent mode was designed around markdown documentation patterns.

If you use multiple AI tools, check out Skills vs MCP to understand which approach fits your workflow.

Testing your setup

Restart VS Code after adding or modifying SKILL.md files. Agent mode only reads files during initialization.

Test the integration by asking Copilot to generate code that should follow your documented patterns. If suggestions ignore your skill file content, check the file placement and format.

Create a simple function and see if Copilot suggests variable names, error handling, or import statements that match your SKILL.md guidelines.

For debugging, temporarily add very specific technical requirements to your SKILL.md (like "always use const for variables"). If Copilot still suggests let or var, the file isn't being processed correctly.

The best practices guide covers more testing approaches for skill files.

Your SKILL.md becomes part of Copilot's understanding of your codebase. Keep it current as your project evolves, and the suggestions will stay relevant to your actual architecture.