Skip to content

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 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). 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), and it requires any discovered path to resolve within that plugin root, rejecting symlinks, junctions, or similar indirections that escape it (§4.1). 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.
  • 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 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 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: 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