Skip to content

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
Agent skills (package-mapped) .github/skills/*/SKILL.md ✅ ✅ ✅ Model-invoked by task/keywords, or /name when user-invocable: true
Agent skills (repo-local-only) .github/skills/{maintain-*,code-review}/SKILL.md ✅ ✅ ✅ Model-invoked by task/keywords, or /name when user-invocable: true
Custom agents .github/agents/*.agent.md ✅ ✅ ✅ User-selected (/agent or picker). Supported by Copilot, but Forge does not currently ship any.
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.

Path instructions are not used. Forge previously kept .github/instructions/*.instructions.md files with applyTo globs, but each one only pointed at the skill that already owned those standards. Skills carry the standards directly and load on the same signals, so the indirection was removed rather than maintained in two places by hand. Generated package copies under .github/plugins/*/skills/ are still intentional: they are derived from .github/skills/, drift-checked, and needed for portable Agent Plugin distribution.

Prompt files do not run in Copilot CLI (copilot-cli#618). Forge therefore ships no prompt files. Cross-surface guided workflows use user-invocable skills instead, so they work identically in the CLI, VS Code, and the coding agent.

📦 Agent Plugins packages

Forge separates portable Agent Skills from repository-maintenance skills. The shipped packages follow the Agent Plugins v1.0.0 packaging model:

Package Purpose Authored in Generated package output
forge Day-to-day development skills plus the Forge and Mosaic MCP server registrations .github/skills/ .github/plugins/forge/
forge-planning Optional planning and artifact-authoring skills for PRDs, decisions, implementation plans, and technical spikes .github/skills/ .github/plugins/forge-planning/

.github/plugins/skill-packages.json is the package manifest that maps each shipped skill name to forge or forge-planning. .github/skills/maintain-skills/scripts/Sync-PluginSkills.ps1 reads that manifest and generates the package skills/ trees from .github/skills/. Do not hand-edit the generated plugin copies.

ADR 0012: Migrate Forge Skills into Two Agent Plugins Packages records the package boundary: forge is the default builder install, forge-planning is the optional formal-planning seam, and repo-local-only skills such as maintain-* and code-review stay outside the shipped package mapping.

Copilot code review repository settings

These are GitHub repository settings, not files in this repo, so path cleanups here do not configure them:

  • Register the Forge MCP server for Copilot code review in the repository settings if you want reviews to use Forge MCP tools.
  • Keep Allow Copilot to use MCP tools when reviewing pull requests enabled. GitHub currently defaults that toggle on.
  • Automatic code review must be enabled for the code-review skill to run without a manual request — including its release-notes validation rules. This is a repository setting, not a file.
  • .github/workflows/copilot-code-review.yml configures the Copilot code review environment only: it exposes a copilot-setup-steps job for runner type and preinstalled tooling, falling back to copilot-setup-steps.yml when absent. It is not a place for review rules — those live in .github/skills/code-review/SKILL.md, which Copilot code review reads from the pull request head branch. Forge intentionally has not added a copilot-code-review.yml today. Treat it as an available option if review-environment customization (runner size, preinstalled tools) becomes necessary later.

Read Install the SAIF CLI for the marketplace setup, install commands, prerequisites, and MCP details.

Pull request and issue templates

CLI and API creation flows bypass template prefill on both GitHub and Azure DevOps. The web compose form applies templates, but gh, az repos pr, REST APIs, and MCP issue or PR creation helpers do not.

  • PR authors should read docs/pull_request_template.md, the single host-neutral template used by both GitHub and Azure DevOps, and fill it manually before creating the PR.
  • Issue authors should check .github/ISSUE_TEMPLATE/, including task.yml and design-spike.yml, and render each YAML form field into the issue body instead of skipping the template structure.

Which type to use

  • Reusable knowledge, a procedure, or rules scoped to specific file types the model should pull in automatically → skill (.github/skills/<name>/; add it to .github/plugins/skill-packages.json when it should ship)
  • Reusable knowledge that should also be launchable as /name → skill with user-invocable: true in its SKILL.md frontmatter, such as shipped create-pr and create-backport or repo-local maintain-release
  • A guided, user-launched workflow with guardrails → prefer a user-invocable skill in Forge. Copilot custom agents remain a supported primitive, but Forge no longer ships .github/agents/ workflows for PR, backport, release, or review tasks.
  • Repo-wide, always-on guidance → AGENTS.md

User-invocable workflow skills

Forge now exposes its guided workflows as skills rather than repo-local custom agents. These skills still route automatically by task, and the ones marked user-invocable: true can also be launched directly as slash commands.

Skill Scope Invocation
create-pr Shipped, provider-agnostic PR authoring with template filling and issue or work-item linking Automatic routing or /create-pr
create-backport Shipped, provider-agnostic backport workflow that cherry-picks and opens the release PR Automatic routing or /create-backport
maintain-release Repo-local Forge release-notes and versioning workflow Automatic routing or /maintain-release
code-review Repo-local Forge review guidance used by Copilot code review and manual review requests Automatic routing or /code-review

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
  • Optional user-invocable: true frontmatter for /name slash-command invocation
  • Detailed instructions and workflows
  • Code examples and best practices
  • References subfolder for detailed topic documentation
  • Troubleshooting guidance

Available Skills

Note: Forge authors every skill under .github/skills/. Shipped skills are mapped into Agent Plugin packages via .github/plugins/skill-packages.json; repo-local-only skills stay only in .github/skills/.

Shipped skill inventories for the forge and forge-planning Agent Plugin packages live in Agent Skills. Treat that page as the canonical consumer-facing inventory so package tables stay in one place as shipped skills change.

🧰 Repo-local-only skills

Forge-only skills kept under .github/skills/ that are not mapped into Agent Plugin packages.

Skill Summary
code-review Review Forge pull requests against platform standards using technology-specific routing, documentation validation, security checks, and evidence-based review rigor
maintain-github-actions Forge repo-hygiene GitHub Actions, pull request docs checks, merge gatekeeping, Dependabot automation, and minimal repository automation
maintain-pipelines Forge's own Azure DevOps pipeline generation, forge-orchestrator metadata, PR pipeline regeneration, and package or module pipeline config
maintain-release Forge's own release process, version numbers, module repinning, release-note drafts, and release announcements
maintain-skills Forge repo-local skills, validation scripts, Foundry-sync checks, skill frontmatter validation, and todo tracking
maintain-templates Forge dotnet new templates, template.json, shared template config, host metadata, setup scripts, and snapshot coverage

How Skills Work

Progressive Disclosure

Skills use a progressive disclosure pattern:

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

This minimizes context overhead while providing deep expertise when needed.

Automatic Discovery

In this repository, Copilot discovers authored skills from .github/skills/. For plugin distribution, Sync-PluginSkills.ps1 generates the shipped package copies from .github/skills/ using .github/plugins/skill-packages.json. Skills are invoked based on:

  1. Task context - Asking for specific tasks (e.g., "Create a PR") triggers relevant skills
  2. Domain keywords - Mentioning "documentation", "release", or "Forge development" activates corresponding skills
  3. 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

If a skill sets user-invocable: true, you can also launch it directly:

/create-pr Open a PR for the current branch

/create-backport Backport commit:{sha} to target:releases/{major}.{minor}

/maintain-release Create release notes for 3.8.0

Skill Structure

Each skill follows the Agent Skills standard:

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

Shipped skills are then generated into .github/plugins/<package>/skills/<name>/ for Agent Plugin distribution. Never edit those generated copies by hand.

SKILL.md Format

---
name: skill-name
user-invocable: true # Optional: expose the skill as /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
  • Set user-invocable: true only when the skill should appear as a /name slash command
  • Keep SKILL.md body under 500 lines
  • Use references/ for detailed documentation

Creating New Skills

To add a new skill:

  1. Create the skill under .github/skills/<name>/. If it should ship, map it into the right package in .github/plugins/skill-packages.json; otherwise leave it repo-local.
  2. Create a folder with a lowercase, hyphen-separated name
  3. Add SKILL.md with frontmatter (name, description)
  4. Put trigger info in description, not the body
  5. Keep under 500 lines; split to references/ if needed
  6. Test with GitHub Copilot

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

Naming Conventions

Pattern Example Use Case
{domain} terraform, dotnet Broad domain standards
{domain}-{specialty} terraform-testing, azure-devops-pipelines Specific domain workflows
{action}-{object} create-pr, create-backport, create-prd Guided workflows and artifact-authoring skills
maintain-{scope} maintain-release, maintain-skills Repo-local Forge maintenance skills in .github/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
  • ❌ Hand-maintain duplicate content across skills or between .github/skills/ and generated package copies
  • ❌ Exceed 500 lines in SKILL.md
  • ❌ Put "when to use" in body instead of description

For Skill Users

Do:

  • ✅ Be specific about what you need help with
  • ✅ Provide context about your current task
  • ✅ Ask for clarification if instructions are unclear

Don't:

  • ❌ Expect skills to handle tasks outside their scope
  • ❌ Ignore prerequisites or warnings

Repository paths: All skills are authored in .github/skills/; shipped package membership lives in .github/plugins/skill-packages.json; generated package copies live under .github/plugins/*/skills/; the agent-facing skill inventory is in AGENTS.md at the repository root.

Migration History

The Forge repository previously consolidated fragmented repo-local skills into a smaller set using progressive disclosure. The table preserves the historical names used in that consolidation and maps them to today's authored and packaged layout.

Historical consolidated skill Original skills merged Current successor
documentation documentation-diataxis, documentation-formatting, documentation-validation documentation in forge
git-workflows git-branch-management, git-cherry-pick, git-commit-analysis, conventional-commits git-workflows in forge
github-workflows github-pr-create, github-issue-linking, code-review-standards github-workflows in forge
release-management release-notes-generation, release-announcements, version-management maintain-release repo-local skill
forge-standards forge-emoji-standards, forge-tech-stack, forge-version-compatibility forge-standards in forge
terraform-development terraform-module-creation, terraform-testing terraform and terraform-testing in forge
dotnet-development dotnet-template-creation, nuget-package-creation dotnet, dotnet-testing, and nuget-manager in forge; maintain-templates repo-local skill
utils skill-creation, foundry-examples-sync, todo-tracking maintain-skills repo-local skill

Benefits at the time: fewer skills to scan, consolidated triggers, and better context coherence.

Since that consolidation, Forge moved portable skills into Agent Plugin packages while keeping a single authored source tree in .github/skills/. The current inventory is 32 skills: 22 day-to-day development skills in forge, 4 planning and artifact-authoring skills in forge-planning, and 6 repo-local-only skills (code-review plus 5 maintain-* skills) that are never shipped.

For questions or suggestions about skills, contact the Platform Engineering team.