/docs/copilot-setup.md

Using agent-skills with GitHub Copilot

Setup

Copilot Instructions

GitHub Copilot supports project-level instructions via .github/copilot-instructions.md:

mkdir -p .github

# Create instructions file with essential skills
cat /path/to/agent-skills/skills/test-driven-development/SKILL.md > .github/copilot-instructions.md
echo "\n---\n" >> .github/copilot-instructions.md
cat /path/to/agent-skills/skills/code-review-and-quality/SKILL.md >> .github/copilot-instructions.md

Agent Personas (agents.md)

Copilot supports specialized agent personas. Use the agent-skills agents:

# Copy agent definitions
cp /path/to/agent-skills/agents/code-reviewer.md .github/agents/code-reviewer.md
cp /path/to/agent-skills/agents/test-engineer.md .github/agents/test-engineer.md
cp /path/to/agent-skills/agents/security-auditor.md .github/agents/security-auditor.md

Invoke agents in Copilot Chat:

• @code-reviewer Review this PR
• @test-engineer Analyze test coverage for this module
• @security-auditor Check this endpoint for vulnerabilities

Custom Instructions (User Level)

For skills you want across all repositories:

1. Open VS Code → Settings → GitHub Copilot → Custom Instructions
2. Add your most-used skill summaries

Recommended Configuration

.github/copilot-instructions.md

# Project Coding Standards

## Testing
- Write tests before code (TDD)
- For bugs: write a failing test first, then fix (Prove-It pattern)
- Test hierarchy: unit > integration > e2e (use the lowest level that captures the behavior)
- Run `npm test` after every change

## Code Quality
- Review across five axes: correctness, readability, architecture, security, performance
- Every PR must pass: lint, type check, tests, build
- No secrets in code or version control

## Implementation
- Build in small, verifiable increments
- Each increment: implement → test → verify → commit
- Never mix formatting changes with behavior changes

## Boundaries
- Always: Run tests before commits, validate user input
- Ask first: Database schema changes, new dependencies
- Never: Commit secrets, remove failing tests, skip verification

Specialized Agents

Use the agents for targeted review workflows in Copilot Chat.

Usage Tips

1. Keep instructions concise — Copilot instructions work best when focused. Summarize the key rules rather than including full skill files.
2. Use agents for review — The code-reviewer, test-engineer, and security-auditor agents are designed for Copilot's agent model.
3. Reference in chat — When working on a specific phase, paste the relevant skill content into Copilot Chat for context.
4. Combine with PR reviews — Set up Copilot to review PRs using the code-reviewer agent persona.