# Author Forge Skills in .github/skills and Generate Plugin Copies

- Status: Accepted
- Deciders: Emmitt Johnson
- Date: 2026-08-07

## Context and Problem Statement

[ADR 0012](0012-migrate-forge-skills-into-two-agent-plugins-packages.md) moved Forge's shipped
skills into `.github/plugins/{forge,forge-planning}/skills/` so they could ship as spec-conformant
Agent Plugins packages. That works for Copilot CLI and VS Code, which read plugin packages
directly, but it does not work for GitHub-hosted surfaces.

GitHub Copilot code review and the GitHub-hosted Copilot coding agent only discover project-level
skills from the repository roots `.github/skills`, `.claude/skills`, and `.agents/skills`
([GitHub docs: MCP servers and agent skills](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review#mcp-servers-and-agent-skills)).
As a result, the shipped Forge skills under `.github/plugins/*/skills/` were invisible to GitHub
code review and the cloud agent even though the same repository worked locally.

The obvious "one tree, two paths" workaround also fails. Agent Plugins v1.0.0 fixes skill
discovery at `skills/` inside the plugin root ([§6.1](https://agent-plugins.org/specification#61-fixed-locations)),
and it requires any discovered path to resolve within that plugin root, rejecting symlinks,
junctions, or similar indirections that escape it
([§4.1](https://agent-plugins.org/specification#41-general-requirements)). Forge therefore needs a
single authoring source that GitHub can see and a real generated copy that each Agent Plugin can
ship.

## Decision Drivers

- Make shipped Forge skills discoverable to GitHub Copilot code review and the GitHub-hosted
  coding agent.
- Preserve the two-package split and host-local-install boundary already decided in
  [ADR 0012](0012-migrate-forge-skills-into-two-agent-plugins-packages.md).
- Stay conformant with the Agent Plugins v1.0.0 fixed-location and path-containment rules.
- Keep repo-local `maintain-*` skills out of shipped packages without relying on directory
  placement alone.
- Make drift between authored skill content and shipped plugin copies fail fast in CI.

## Considered Options

- Keep authoring shipped skills in `.github/plugins/*/skills/` and accept that GitHub-side review
  and cloud-agent paths cannot see them.
- Use symlinks, junctions, or similar filesystem indirection between `.github/skills/` and
  `.github/plugins/*/skills/`.
- Restore `.github/skills/` as the single authoring source and generate the plugin package
  `skills/` trees from it.
- Publish plugin package contents only as build or release artifacts and stop committing generated
  plugin skill trees.

## Decision Outcome

Chosen option: **restore `.github/skills/` as the single authoring source and generate the Agent
Plugin `skills/` trees from it**, because that is the only option that satisfies GitHub skill
discoverability and Agent Plugins package constraints at the same time without changing the
consumer-facing two-package model.

This decision **amends** [ADR 0012](0012-migrate-forge-skills-into-two-agent-plugins-packages.md)
in two places only:

1. Skill authoring moves back to `.github/skills/` instead of living primarily under
   `.github/plugins/*/skills/`.
2. The shipped versus repo-local boundary is enforced by explicit package mapping in
   `.github/plugins/skill-packages.json` instead of by "which directory is this skill under."

Everything else from ADR 0012 stays in force unchanged: the `forge` and `forge-planning`
two-package split, the audience boundary itself, the rule that shipped skills must remain
host-local-installable and must not depend on repo-internal paths, and the Azure-operations
exclusion from both shipped packages.

Forge now authors all skills in `.github/skills/`, including shipped skills, repo-local
`maintain-*` skills, and a review-focused `code-review` skill. `.github/plugins/skill-packages.json`
is the authority for which authored skills ship in which Agent Plugin package.
`.github/plugins/{forge,forge-planning}/skills/` becomes generated output produced by
`.github/skills/maintain-skills/scripts/Sync-PluginSkills.ps1`, with `-Check` wired into CI and
`Test-AgentPluginPackages.ps1` enforcing the new invariants: every mapped skill exists in source,
no `maintain-*` skill is ever mapped to a package, and each generated plugin `skills/` tree
matches the declared mapping exactly.

Forge also retires `.github/copilot-review-instructions.md` as an orphaned review surface. GitHub's
documentation says review-focused skill names such as `code-review` are more likely to be used for
review tasks, so the review guidance moves into a new `code-review` skill, with a small severity
table duplicated inside the shipped `github-workflows` skill where that package cannot rely on
repo-internal links.

Forge does **not** adopt a dedicated `.github/workflows/copilot-code-review.yml` in this decision.
GitHub documents that workflow as an available way to customize the review environment, but Forge
keeps the default environment for now and only records the option.

### Consequences

- Good, because GitHub Copilot code review and the GitHub-hosted coding agent can now discover the
  same authored skill content that local hosts use, including a review-targeted `code-review`
  skill.
- Good, because Forge keeps the packaging and audience model from
  [ADR 0012](0012-migrate-forge-skills-into-two-agent-plugins-packages.md) while making the
  shipped-package boundary explicit in data instead of implicit in directory layout.
- Good, because generated plugin copies are drift-checked in CI, so the duplication cannot silently
  rot the way two hand-maintained sources would.
- Bad, because skill content is now committed twice: once as source under `.github/skills/` and
  once as generated output under `.github/plugins/*/skills/`.
- Bad, because GitHub-side MCP usage still depends on repository settings outside the repo: a
  maintainer must register the Forge MCP server for code review, and the repository setting
  **Allow Copilot to use MCP tools when reviewing pull requests** must remain enabled when that
  behavior is wanted.

## More Information

- This decision keeps the "host-local install" rule from
  [ADR 0012](0012-migrate-forge-skills-into-two-agent-plugins-packages.md): shipped skills must be
  self-contained within the installed plugin package and must not link back into repo-only paths.
- The committed generated trees are an implementation trade-off, not a design goal. A future Forge
  release flow could publish the Agent Plugin packages as build or release artifacts instead of
  committing generated skill trees, eliminating the duplication entirely.
- The GitHub-side repository steps above are intentionally recorded here because no file change can
  perform them:
  - register the Forge MCP server in repository Copilot settings for code review
  - keep or deliberately change the repository setting **Allow Copilot to use MCP tools when
    reviewing pull requests**