# 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](https://agent-plugins.org/) 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 planning, artifact authoring, and bounded pre-implementation review 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 optional Forge planning, artifact-authoring, and bounded design and implementation-plan review skills. This domain boundary covers preparing and reviewing proposed work before implementation, not an orchestration harness. The package mapping and consumer-facing skill inventory track individual skills. `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](https://agent-plugins.org/schemas/1.0.0/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. Planning, artifact authoring, and bounded pre-implementation review form the 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](https://agent-plugins.org/), [§6](https://agent-plugins.org/specification#6-component-discovery)). - Agent Plugins v1 defines exactly **two** portable component types, **skills** and **MCP servers** ([§7](https://agent-plugins.org/specification#7-component-types)). - 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 planning, artifact authoring, or bounded design and implementation-plan review. - 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](0000-use-markdown-architectural-decision-records.md).