GitHub Copilot Configuration¶

The Forge repository configures GitHub Copilot across three surfaces — Copilot CLI, VS Code, and the Copilot coding agent — using several customization types. Agent Skills are the largest of these and provide domain-specific guidance and automation for platform development tasks.

Customization types¶

Copilot reads several kinds of customization file. Each is supported on a different set of surfaces and invoked differently:

Type	Location	CLI	VS Code	Coding agent	How it is invoked
Agent instructions	`AGENTS.md` (repo root)	✅	✅	✅	Always loaded
Path instructions	`.github/instructions/*.instructions.md`	✅	✅	✅	Auto, by file glob (`applyTo`)
Agent skills	`.github/skills/*/SKILL.md`	✅	✅	✅	Model-invoked by task/keywords
Custom agents	`.github/agents/*.agent.md`	✅	✅	✅	User-selected (`/agent` or picker)
Prompt files	`.github/prompts/*.prompt.md`	❌	✅	❌	`/name` slash command (VS Code only)

Repo-wide instructions: Forge uses AGENTS.md rather than .github/copilot-instructions.md. Both are read by all three surfaces; AGENTS.md is the cross-tool standard, so there is no need to maintain both.

Prompt files do not run in Copilot CLI (copilot-cli#618). Forge therefore ships no prompt files — cross-surface workflows are implemented as custom agents that delegate to skills, so they work identically in the CLI, VS Code, and the coding agent.

Which type to use¶

Reusable knowledge or a procedure the model should pull in automatically → skill (.github/skills/)
Rules that apply only to specific files → path instructions (.github/instructions/, applyTo)
A guided, user-launched workflow with guardrails → custom agent (.github/agents/), which works in the CLI and VS Code (Forge does not use VS-Code-only prompt files)
Repo-wide, always-on guidance → AGENTS.md

Custom agents¶

Custom agents package a workflow with guardrails and delegate to skills as their source of truth. Invoke them with /agent in Copilot CLI or the agent picker in VS Code.

Agent	Purpose
`create-pr`	Generate a Conventional-Commit PR with issue linking
`code-review`	Read-only review against Forge standards
`create-release`	Draft release notes on a `release-notes/{version}` branch
`create-backport`	Cherry-pick a fix into a `releases/{major}.{minor}` branch

What are Agent Skills?¶

Agent Skills are self-contained folders containing specialized instructions and workflows that GitHub Copilot can use to provide expert assistance for specific tasks. Each skill follows the Agent Skills standard and includes:

YAML frontmatter defining the skill name and description
Detailed instructions and workflows
Code examples and best practices
References subfolder for detailed topic documentation
Troubleshooting guidance

Available Skills¶

Note: Skills are located in the repository at .github/skills/. Links below are repository paths, not documentation paths.

🔨 Core Platform¶

Skill	Description
`forge-standards`	Version compatibility, project structure, emoji conventions
`utils`	Skill creation, Foundry sync, todo tracking

🔀 Git & GitHub¶

Skill	Description
`git-workflows`	Branches, cherry-pick, commit analysis, conventional commits
`github-workflows`	PR creation, issue linking, code review

🚀 Release & Documentation¶

Skill	Description
`release-management`	Version bumps, release notes, announcements
`documentation`	Diátaxis framework, MkDocs formatting, validation

🛠️ Development¶

Skill	Description
`dotnet-development`	.NET templates, NuGet packages, coding standards
`typescript-development`	TypeScript packages, React, conventions
`terraform-development`	Module creation, testing
`aspire`	Aspire CLI orchestration, debugging, integrations
`testing`	xUnit, Playwright E2E, Terraform tests
`local-development`	Environment setup, error resolution

⚙️ CI/CD & Config¶

Skill	Description
`azure-devops`	Pipeline management, forge-orchestrator, PR generation
`yaml`	YAML naming conventions and formatting by tool type

How Skills Work¶

Progressive Disclosure¶

Skills use a progressive disclosure pattern:

Description field - Primary trigger for skill discovery (WHEN to use it)
SKILL.md body - Workflow overview and quick reference
references/ folder - Detailed documentation loaded on demand

This minimizes context overhead while providing deep expertise when needed.

Automatic Discovery¶

GitHub Copilot automatically discovers and loads skills from the .github/skills/ directory. Skills are invoked based on:

Task context - Asking for specific tasks (e.g., "Create a PR") triggers relevant skills
Domain keywords - Mentioning "documentation", "release", or "Forge development" activates corresponding skills
File context - Working in specific files may trigger related skills

Manual Invocation¶

You can explicitly request a skill's help:

@copilot Use the documentation skill to validate this file

@copilot Use the git-workflows skill to help me create a feature branch

Skill Structure¶

Each skill follows the Agent Skills standard:

skill-name/
├── SKILL.md              # Required: YAML frontmatter + markdown instructions
└── references/           # Optional: Detailed docs loaded on demand
    ├── topic-a.md
    └── topic-b.md

SKILL.md Format¶

---
name: skill-name
description: >
  What this skill does AND when to use it.
  Include specific triggers and scenarios.
---

# Skill Title

## Workflow

1. Step 1 → See references/topic-a.md
2. Step 2 → See references/topic-b.md

## Quick Reference

[Essential tables/info that applies across all topics]

Key rules:

description is the PRIMARY trigger—include all "when to use" info there
Keep SKILL.md body under 500 lines
Use references/ for detailed documentation

Creating New Skills¶

To add a new skill:

Create a folder with a lowercase, hyphen-separated name
Add SKILL.md with frontmatter (name, description)
Put trigger info in description, not the body
Keep under 500 lines; split to references/ if needed
Test with GitHub Copilot

📖 See .github/skills/utils/references/skill-creation.md in the repository for detailed guidance.

Naming Conventions¶

Pattern	Example	Use Case
`{domain}-{specialty}`	`terraform-development`, `git-workflows`	Domain-specific skills
`{action}-{object}`	`release-management`	Task-oriented skills

Best Practices¶

For Skill Creators¶

Do:

✅ Focus on specific, actionable tasks
✅ Include real code examples
✅ Use progressive disclosure (SKILL.md → references/)
✅ Keep content current with platform versions
✅ Make descriptions specific with clear triggers

Don't:

❌ Create overly broad or vague skills
❌ Duplicate content across skills
❌ Exceed 500 lines in SKILL.md
❌ Put "when to use" in body instead of description

For Skill Users¶