# 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](https://github.com/github/copilot-cli/issues/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](https://agentskills.io/specification) 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:

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

GitHub Copilot automatically discovers and loads skills from the `.github/skills/` directory. 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:

```text
@copilot Use the documentation skill to validate this file
```

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

## Skill Structure

Each skill follows the [Agent Skills standard](https://agentskills.io/specification):

```text
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

```yaml
---
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:

1. Create a folder with a lowercase, hyphen-separated name
2. Add `SKILL.md` with frontmatter (`name`, `description`)
3. Put trigger info in `description`, not the body
4. Keep under 500 lines; split to `references/` if needed
5. 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

**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

## Related Resources

- [Agent Skills Specification](https://agentskills.io/specification)
- [GitHub Agent Skills Docs](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
- [Forge Documentation](../../index.md)

> **Repository paths:** Skills are in `.github/skills/`; the agent-facing skill inventory is in `AGENTS.md` at the repository root.

## Migration History

The Forge repository originally consolidated 25 fragmented skills into 9 focused skills using progressive disclosure:

| Consolidated Skill      | Original Skills Merged                                                            |
| ----------------------- | --------------------------------------------------------------------------------- |
| `documentation`         | documentation-diataxis, documentation-formatting, documentation-validation        |
| `git-workflows`         | git-branch-management, git-cherry-pick, git-commit-analysis, conventional-commits |
| `github-workflows`      | github-pr-create, github-issue-linking, code-review-standards                     |
| `release-management`    | release-notes-generation, release-announcements, version-management               |
| `forge-standards`       | forge-emoji-standards, forge-tech-stack, forge-version-compatibility              |
| `terraform-development` | terraform-module-creation, terraform-testing                                      |
| `dotnet-development`    | dotnet-template-creation, nuget-package-creation                                  |
| `local-development`     | local-development-setup, error-resolution                                         |
| `utils`                 | skill-creation, foundry-examples-sync, todo-tracking                              |

**Benefits:** 64% reduction in skills to scan, consolidated triggers, better context coherence.

Since that consolidation, five skills have been added as the platform grew — `aspire`, `typescript-development`, `testing`, `azure-devops`, and `yaml` — bringing the current total to **14**.

---

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