---
title: Set up Forge Agent Plugins
description: Choose Forge plugins, configure their scope and optional permissions, verify installation, and repair updates.
moved_from:
  - reference/tools/agent-skills.md
---

# Set up Forge Agent Plugins

<a id="agent-skills"></a>

Install the `forge` plugin for day-to-day development skills and the Forge and Mosaic MCP servers. Add `forge-planning` when you want planning and pre-implementation review skills. Install and [verify the SAIF CLI](install-saif-cli.md#verify-installation) first: the Forge MCP registration launches the bare `saif` executable and cannot bootstrap it for you.

## Shipped packages

| Package | Choose it for |
| --- | --- |
| `forge` | Building and delivering Forge applications, with read-only command, documentation, and service discovery through MCP |
| `forge-planning` | Optional requirements, decisions, implementation plans, technical spikes, and bounded plan review |

The [package manifest](https://github.com/saif-corp/forge/blob/main/.github/plugins/skill-packages.json) owns the skill inventory. Read an individual skill's `SKILL.md` in the [authoring tree](https://github.com/saif-corp/forge/tree/main/.github/skills) for its instructions; this guide does not maintain a second inventory. The [marketplace catalog](https://github.com/saif-corp/forge/blob/main/.github/plugin/marketplace.json) owns package defaults.

<a id="forge-package-skills"></a>
<a id="forge-planning-package-skills"></a>
<a id="repo-local-only-skills"></a>

Skills load when the task matches their description. Skills marked `user-invocable: true` also support direct invocation in hosts with slash commands. Repo-maintenance skills remain local to the Forge repository rather than shipping in either package.

### Azure operations are intentionally out of scope

Forge's package boundary excludes Azure operations skills such as role selection, cost optimization, resource health diagnosis, and Entra agent-user management. See [ADR 0012](../reference/decisions/0012-migrate-forge-skills-into-two-agent-plugins-packages.md#explicit-exclusions); use the [Azure-owned distribution](https://github.com/microsoft/azure-skills) for those workflows.

## Installing

### Install the Forge plugin packages

With `saif` on your PATH, configure detected VS Code and GitHub Copilot hosts:

```powershell
saif --version
saif agent init
```

`agent init` registers the packages you select. On an interactive terminal it shows a checklist with saved choices preselected: press Space to toggle a package and Enter to accept. On first use, catalog defaults select `forge` and leave `forge-planning` clear. The packages are independent, so selecting planning does not enable `forge`, and clearing both disables both without uninstalling. When it detects GitHub Copilot, it also installs enabled packages that lack an installed `plugin.json`. It copies files directly to the Copilot plugin cache to avoid a Windows directory-rename failure (`Access is denied. (os error 5)`) that can affect `copilot plugin install`. It prints equivalent manual install commands for every enabled package whether or not that direct installation ran, and prints none when you disable every package. Re-running init does not update an already-installed package; use [doctor for updates](#keeping-packages-up-to-date).

### Select plugins

Rerun `saif agent init` to change the selection. For scripts, pass the complete desired set with `--plugins`, or keep saved choices without prompting:

```powershell
# Enable both packages
saif agent init --plugins forge forge-planning

# Keep development skills and disable planning
saif agent init --plugins forge

# Enable only planning, or disable both without uninstalling
saif agent init --plugins forge-planning
saif agent init --plugins none

# Retain saved choices, using catalog defaults only for missing entries
saif agent init --no-interactive
```

| Option | Behavior |
| --- | --- |
| `--plugins` | Complete set of package names to enable, space-separated or supplied through repeated options. The command disables any catalog package you omit. Use `none` alone to disable all. Unknown names, a missing value, or combining `none` with package names fail before configuration changes. Explicit `--plugins` bypasses the checklist in every scope. |
| `--no-interactive` | Global option. Skips the checklist and retains the resolved saved selection, using catalog defaults only for missing entries. Redirected input behaves the same way, and a terminal without ANSI support also retains the selection and prints guidance to use `--plugins`. |

Saved choices come from the Copilot user settings file, honoring `COPILOT_HOME` and the configured filename. In project scope, explicit workspace plugin booleans take precedence over user choices; missing entries inherit user choices, then catalog defaults. User scope ignores workspace selections.

Disabling writes `false` to `enabledPlugins` without deleting installed files. Repeating the same selection does not rewrite unchanged settings or reinstall cached packages. Disabling `forge` also turns off its bundled skills and MCP integrations in hosts that honor the selection; it does not disable independently configured MCP servers.

!!! note "Host activation overrides still apply"
    Init manages declarative plugin settings, not every host's activation controls. [VS Code stores enable/disable state separately](https://code.visualstudio.com/docs/agent-customization/agent-plugins#_enable-or-disable-plugins) from shared workspace configuration; use its Agent Plugins view to change that state. [Copilot repository settings and managed policies](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference) can override user-level plugin choices. Init does not modify those managed policies or VS Code's private state.

!!! note "Historical command"
    `saif mcp init` remains a hidden compatibility alias through Forge 3.x. It prints a deprecation warning and forwards to `saif agent init`; the [compatibility shim](https://github.com/saif-corp/forge/blob/main/src/dotnet/SAIF.Platform.CLI/Commands/_deprecated/Mcp/McpInitCommand.cs) schedules removal for Forge 4.0. Use the new command in scripts and instructions.

For a manual install, or to opt into the planning package:

```powershell
copilot plugin marketplace add saif-corp/forge
copilot plugin install forge@forge

# Optional planning package
copilot plugin install forge-planning@forge
```

The catalog is Copilot's distribution entry point; the portable package payloads live under `.github/plugins/forge/` and `.github/plugins/forge-planning/`.

### Scope targets

The default scope is user-level and applies across repositories on the machine. Use `--local` or `--scope project` for shared workspace plugin settings:

```powershell
saif agent init --local
saif agent init --workspace-root C:\repos\my-service --scope project
```

`--workspace-root` defaults to the git root or current directory. The CLI resolves it even in user scope because optional Copilot permissions use a repository key. `--local` cannot combine with an explicit `--scope user`.

| Setting | User scope (default) | Project scope |
| --- | --- | --- |
| VS Code marketplace discovery | Detected Stable/Insiders user profile `settings.json`, under `chat.plugins.marketplaces` | Not written |
| Shared workspace plugin selection | Not written | `.github/copilot/settings.json`, with `extraKnownMarketplaces` and `enabledPlugins` |
| Copilot CLI and app plugin selection | `~/.copilot/settings.json`, with `extraKnownMarketplaces` and `enabledPlugins` | Same user-level file |
| VS Code approval rules, only with `--grant-permissions` | User profile `settings.json` | `.vscode/settings.json` |
| Copilot CLI approval rules, only with `--grant-permissions` | `~/.copilot/permissions-config.json`, keyed by repository | Same user-level file and repository key |

`COPILOT_HOME` relocates the Copilot configuration root. VS Code user profiles live under `%APPDATA%\Code\User\` on Windows, `~/Library/Application Support/Code/User/` on macOS, and `$XDG_CONFIG_HOME/Code/User/` (or `~/.config/Code/User/`) on Linux. Insiders uses `Code - Insiders`.

!!! note "Migrating an earlier MCP setup"
    Forge's current agent initialization no longer reads or writes the former `~/.copilot/mcp-config.json` registration. Its [Copilot scanner](https://github.com/saif-corp/forge/blob/main/src/dotnet/SAIF.Platform.CLI/Commands/Agent/Scanners/CopilotCliAgentEnvironmentScanner.cs) registers plugins in `settings.json` instead. Verify the new plugin setup before cleaning up an old Forge entry, and preserve any unrelated MCP server definitions. This change to Forge's registration does not establish whether a host still uses that file for other servers.

!!! warning "Project scope does not isolate every setting"
    Committing `.github/copilot/settings.json` shares that plugin selection with collaborators; init writes it only when VS Code is detected. Copilot CLI and app settings and CLI permission grants still use user-level files regardless of `--scope`, so changing a project-scope selection can also affect other repositories.

### Permissions are a separate opt-in

Prefer Forge MCP tools such as `list_commands`, `get_command`, `search_docs`, and `search_services` for read-only lookups. Plugin setup registers those tools without granting direct shell execution.

Only if you want the agent to execute `saif` through the shell, opt in:

```powershell
saif agent init --grant-permissions
```

!!! warning "Copilot CLI approval trusts the whole SAIF CLI"
    VS Code generates per-command `chat.tools.terminal.autoApprove` rules, allowing read-only commands and explicitly denying mutating commands. Copilot CLI's `saif` grant approves **every subcommand**, including mutations such as pipeline approval and token generation. An individual `saif` subcommand deny rule cannot narrow that bare-command grant. `agent init` prints the mutating commands covered by this approval so you can review its breadth.

To review or revert permissions, inspect `chat.tools.terminal.autoApprove` in the VS Code file for your chosen scope. For Copilot CLI, remove the `{"kind": "commands", "commandIdentifiers": ["saif"]}` entry under `locations.<repo-key>.tool_approvals` in `permissions-config.json`. Do not remove unrelated approvals.

## Verify installation

1. Confirm `saif --version` works in the host's environment, not only in an unrelated terminal.
2. Check that the detected host's settings contain the Forge marketplace and intended plugin selection.
3. Check the installed packages under `~/.copilot/installed-plugins/forge/` (or the relocated Copilot root). Each installed package should have `plugin.json`.
4. In the agent host, check for Forge skills and the Forge MCP tools, then ask it to look up a SAIF command through `get_command`.

VS Code [discovers plugins in the Copilot installed-plugin directory](https://code.visualstudio.com/docs/agent-customization/agent-plugins#_plugins-installed-by-github-copilot-cli). Its marketplace setting supports browsing additional packages; it is not a separate copy of the installed plugin. If init did not detect a supported host or reported a scanner/install failure, address that message and use the printed install command after the host becomes available.

### Review the active plan

After installing `forge-planning`, invoke:

```text
/review-plan
```

The skill uses the active issue, design, or plan from the conversation; no file path is required. Optional trailing text narrows the scope, for example `/review-plan Focus on migration and rollback`. Use it in the host's plan mode. It challenges scope by constructing the smallest coherent version of the plan that still meets the goal, and treats public API surface with no named consumer, or contracts that leak implementation detail, as the hardest scope to reverse. It preserves required security, integrity, recovery, and accessibility behavior when cutting scope. It returns evidence-backed blockers, optional suggestions, and unknowns, or `No findings`; material unjustified scope counts as a blocker. It applies only unambiguous, safety-preserving corrections to an editable plan document, never to an issue or work-item body, code, configuration, or other documentation, then asks the plan owner how to proceed on the remaining findings. It saves no report.

## Keeping packages up to date

<a id="update-forge-agent-plugins"></a>

`saif doctor` checks plugin installation, version drift, and host registration. `saif doctor fix` includes that group with no filter flags; target only plugins with:

```powershell
saif doctor fix --agent
```

Version drift compares installed `plugin.json` versions with the marketplace. A package update must bump that version for version-based detection; missing installations and stale registrations do not depend on a version bump.

### Refresh and recovery

`agent init` only installs missing plugins. `doctor fix` refreshes installed ones through the same installer, overwriting files in place rather than deleting the whole plugin directory. Stale-entry pruning is best-effort: a locked obsolete file can remain. A locked file that the new package must overwrite fails the refresh, and earlier copies may already contain new content because the directory update is not transactional.

The installer writes `plugin.json` last, so a failed refresh remains detectable as drift. Release the lock and rerun `saif doctor fix --agent`. A file/directory/link kind change requires removing the old entry before recreating it, so that entry can remain absent if recreation fails. A first install can also leave an incomplete directory if copying fails before `plugin.json`; doctor treats the missing manifest as not installed and retries.

Do not treat a settings entry or an existing directory alone as proof of a healthy install. Verify the manifest and host tools after repair.

## Related guidance

- [Install the SAIF CLI](install-saif-cli.md)
- [CLI command reference](../reference/dotnet/SAIF.Platform.CLI/commands.md)
- [Agent init implementation](https://github.com/saif-corp/forge/blob/main/src/dotnet/SAIF.Platform.CLI/Commands/Agent/AgentInitCommand.cs)
- [Plugin installer implementation](https://github.com/saif-corp/forge/blob/main/src/dotnet/SAIF.Platform.CLI/Commands/Agent/Scanners/ForgePluginInstaller.cs)