Skip to content

Migrate Forge Skills into Two Agent Plugins Packages

  • Status: Accepted
  • Deciders: Emmitt Johnson
  • Date: 2026-08-06

Context and Problem Statement

Forge currently keeps product-facing skills in .github/skills/, distributed only by cloning the repo and pointed at manually by the CLI's install-time wiring. saif-corp/ai-team is an internal, never-shipped experimental repository that built a broader shared skill library and its own agent/setup/orchestration harness ahead of any published portability standard. Now that Agent Plugins has reached 1.0.0, Forge can adopt a conformant, spec-native package format directly rather than continuing to grow either its own bespoke CLI wiring or ai-team's pre-standard harness.

This decision sources skill content from saif-corp/ai-team's library — content, not the product — because much of it is deeper and more broadly applicable than Forge's current skills. saif-corp/ai-team itself is not being replaced or superseded by this work; it never shipped, so there is no consumer-facing product being retired here. Its repository is expected to be deleted directly outside this change.

This migration needs a clear package boundary, a portability model, and a rule for which existing skills are replaced, merged, kept repo-local, or dropped.

The decision also carries forward one portability rule already validated in saif-corp/ai-team/docs/decisions/0006-skills-are-host-local-no-repo-paths.md: shipped skills run from host-local installs, not from repo-absolute paths. That rule is cited here as prior art, not as an obligation inherited from a shipped product.

Decision Drivers

  • One install should cover a normal Forge app team.
  • Shipped packages should stay within the portable Agent Plugins v1.0.0 surface area.
  • The deeper, more authoritative shared skill should win when Forge and ai-team overlap.
  • Forge-specific operating knowledge should be carried forward instead of lost.
  • Skills about maintaining Forge itself should stay repo-local.

Considered Options

  • Six stack-aligned packages: forge-dotnet, forge-terraform, forge-typescript, forge-azure, forge-delivery, forge-planning.
  • Three audience-aligned packages: a broader builder split, a planning split, and a platform maintenance split.
  • One flat package containing both day-to-day development and planning/artifact-authoring skills.
  • Two packages: forge and forge-planning.

Decision Outcome

Chosen option: two spec-conformant Agent Plugins v1.0.0 packages, forge and forge-planning, because that gives Forge teams a single-install golden path for day-to-day delivery while keeping formal planning artifacts optional.

Package Boundaries

  • forge ships the skills that nearly every team building on Forge needs day to day, plus an mcp.json registering the Forge platform MCP servers.
  • forge-planning ships exactly four optional planning and artifact-authoring skills: create-prd, create-decision, create-implementation-plan, and create-technical-spike.

forge's mcp.json is not limited to the Forge MCP server itself. It may register any Forge-platform MCP server that meets both of these conditions:

  1. Unauthenticated, or headers carrying no credentials. Agent Plugins v1.0.0 restricts remote server entries to type, url, and headers (mcp.schema.json), and a plugin package is distributed to every installer verbatim, so any headers value ships in plaintext to every consumer. headers may only carry non-sensitive values (for example a fixed Accept or API-version header). A server needing a secret, API key, or interactive/token-based auth belongs in the SAIF CLI's Forge:RemoteMcpServers bridge instead, where Entra token acquisition already exists and credentials never leave the CLI's runtime config.
  2. Broadly useful enough to justify universal context cost. Every forge installer loads the server's full tool schemas, which is a larger per-install cost than a skill's frontmatter. A server that only one stack uses should be paired with skill routing so agents know when to call it.

The Mosaic design-system MCP server (https://mosaic.saif.com/mcp) is registered under this rule, with routing guidance in the react skill. If the always-on cost of stack-specific servers becomes measurable, the escape hatch is the same language and infrastructure seam identified below: split a forge-frontend package rather than growing forge's mcp.json indefinitely.

The split axis is audience, not tech stack. A normal Forge app spans .NET, Terraform, TypeSpec, and delivery pipeline work at the same time, so the six-package stack split would force multi-package installs for a single app. The three-audience split was also rejected because it still fragmented the default builder workflow too early. Formal planning artifacts are the only clean opt-in seam, so they become the second package.

Replacement and Merge Rules

When ai-team and Forge overlap on the same domain, the default rule is replace, not merge, when the ai-team skill is materially deeper and more authoritative.

Verified examples from the current source repositories:

  • saif-corp/ai-team/plugin/skills/dotnet-best-practices/SKILL.md references references/ 36 times, versus 4 in Forge's .github/skills/dotnet-development/SKILL.md.
  • terraform-best-practices references references/ 19 times, versus 2 in .github/skills/terraform-development/SKILL.md.
  • typescript-best-practices references references/ 45 times, versus 3 in .github/skills/typescript-development/SKILL.md.
  • aspire references references/ 13 times, versus 2 in Forge's .github/skills/aspire/SKILL.md.

That gap is large enough that the overlapping Forge skills are replaced instead of blended line by line. The same rule applies to testing content during migration: deeper shared skill content wins.

Forge-specific value is still carried forward where it is unique:

  • .github/skills/dotnet-development/references/nuget-packages.md
  • .github/skills/terraform-development/scripts/*.ps1
  • .github/skills/typescript-development/references/configuration.md

Two workflow domains are merged, not replaced outright:

  • Git workflow skill: carry Forge references such as .github/skills/git-workflows/references/branches.md and .github/skills/git-workflows/references/cherry-pick.md into the ai-team-derived baseline.
  • GitHub workflow skill: carry Forge references such as .github/skills/github-workflows/references/code-review.md and .github/skills/github-workflows/references/issue-linking.md into the ai-team-derived baseline.

Explicit Exclusions

Forge will not ship these four ai-team skills:

  • azure-role-selector
  • azure-cost-optimize
  • azure-resource-health-diagnose
  • entra-agent-user

Reasons:

  1. All four declare upstream: github/awesome-copilot in their SKILL.md, so they are forks of upstream-maintained MIT content rather than Forge-specific knowledge.
  2. Three of the four depend on Azure MCP tooling that Forge does not ship: azure-role-selector declares allowed-tools against Azure MCP, and both azure-cost-optimize and azure-resource-health-diagnose explicitly instruct the agent to use azmcp-* tools.
  3. The canonical distribution point already exists in microsoft/azure-skills, whose current README says the package ships Azure skills alongside the Azure MCP Server and Foundry MCP.

Consumers who want Azure operations skills should install them from the Azure-owned distribution instead of from Forge.

The ai-team Harness Is Not Carried Forward

saif-corp/ai-team's agent/setup/orchestration harness is discarded rather than ported into Forge. This is not a product retirement — ai-team never shipped to consumers — it is a scoping decision about which parts of that experimental repo's design are worth carrying forward: the skill content, not the harness that distributed it.

This scoping is independently validated by the Agent Plugins v1.0.0 specification:

  • The portable package model is plugin.json plus fixed locations for skills/ and mcp.json (Agent Plugins overview, §6).
  • Agent Plugins v1 defines exactly two portable component types, skills and MCP servers (§7).
  • Commands, hooks, and agents therefore remain client-specific or extension-specific concerns, not portable v1 components.

setup and adversarial-review are dropped for the same reason: both exist to scaffold or drive the discarded harness layer.

marketplace.json Is Non-Normative

Forge may keep a marketplace.json file as a GitHub-Copilot-specific discovery and distribution shim, but it is not part of either conformant Agent Plugins package.

Agent Plugins defines the portable floor as root plugin.json, optional skills/, optional mcp.json, and client-owned extension namespaces. The Agent Plugins overview also states that distribution, installation, permissions, and user experience remain under each client's control. Forge's marketplace.json therefore lives alongside the two plugin packages as convenience metadata, not as part of the normative portable package format.

Licensing and Attribution

Forge licenses the repository and both shipped plugin packages under the MIT License.

Per the final migration decision, Forge does not preserve per-skill upstream attribution or provenance frontmatter inside shipped SKILL.md files. The migration keeps the resulting content as Forge-maintained package content rather than carrying forward skill-by-skill attribution fields.

Repo-Local maintain- Skills

The maintain- prefix marks skills that stay repo-local in .github/skills/ and are never shipped in either plugin package. These skills are for maintaining Forge itself, not for teams building products on Forge:

  • maintain-pipelines: Forge's own forge-orchestrator Azure DevOps pipeline configuration, including the existing Update-ForgePackageConfig.ps1 automation.
  • maintain-release: Forge version bump and release-notes automation.
  • maintain-templates: authoring src/templates/ dotnet new templates.
  • maintain-skills: skill validation and Foundry sync tooling from the existing utils skill.
  • maintain-github-actions: generic GitHub Actions authoring guidance that is not part of Forge's main CI path, which lives in .azdo/.

This prefix also resolves two naming collisions without adding anti-triggers:

  • repo-local azure-devops versus shipped azure-devops-cli
  • repo-local release-management versus shipped create-release

Skill Naming Convention

The ai-team-inherited -best-practices suffix is dropped during migration. Migrated skills use bare domain names such as dotnet, terraform, typescript, react, and typespec.

The suffix added no useful routing signal because the skill description frontmatter already contains the real disambiguation through explicit USE FOR and DO NOT USE FOR clauses. The suffix was also inconsistent across the library, so the migration is the clean point to normalize on bare domain names.

Consequences

  • Good, because a typical Forge application team gets one opinionated install for daily work and only adds forge-planning when it wants formal planning artifacts.
  • Good, because the portable packages stay aligned with the Agent Plugins v1.0.0 surface area: skills and MCP servers.
  • Good, because repo-maintenance skills stay with the Forge repo, where they can depend on Forge-specific scripts, pipelines, and authoring workflows.
  • Bad, because forge will carry about 20 skill descriptions into routing context on every install, which is roughly 800 to 1,000 tokens of always-available frontmatter.
  • Bad, because the package boundary is intentionally opinionated. Teams that only want one stack still receive the broader Forge golden path package.

If the routing-context cost becomes measurable, the natural future split is along the language and infrastructure seams already identified here: .NET, Terraform, and TypeScript.

More Information

  • saif-corp/ai-team/docs/decisions/0002-agent-distribution-via-plugins.md and 0006-skills-are-host-local-no-repo-paths.md are cited as prior art whose skill-portability reasoning carries forward; ai-team itself never shipped and is not a dependency of this decision.
  • Forge continues to follow its existing ADR convention from 0000-use-markdown-architectural-decision-records.