microsoft · sergio-sisternes-epam · Apr 27, 2026 · Apr 24, 2026 · Apr 25, 2026 · Apr 25, 2026
@@ -40,6 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Gemini CLI** as a supported APM target (`--target gemini`): auto-detects `.gemini/`, writes MCP config to `.gemini/settings.json`, and adds `apm runtime setup|remove gemini`. (#917)
+- Experimental `cowork` target for Microsoft 365 Copilot Cowork custom-skill deployment via OneDrive (`apm experimental enable cowork`; `apm install --target cowork --global`; persisted via `apm config set cowork-skills-dir`). (#913)
 - `apm experimental` command group (`list` / `enable` / `disable` / `reset`) lets you opt into new behaviour before it graduates to default. Ships with the `verbose-version` flag. (#849)
 - `apm audit --ci` now verifies hash integrity of locally deployed `.apm/` files so hand-edits and config drift fail CI instead of slipping through. (#887)
 - `includes:` manifest field (`auto` or list) gives you explicit control over which local `.apm/` files are deployed; pair with `policy.manifest.require_explicit_includes` to block silent expansion. Audit raises an `includes-consent` advisory while you migrate. (#887)

@@ -105,6 +105,7 @@ export default defineConfig({
 						{ label: 'CI/CD Pipelines', slug: 'integrations/ci-cd' },
 						{ label: 'GitHub Agentic Workflows', slug: 'integrations/gh-aw' },
 						{ label: 'IDE & Tool Integration', slug: 'integrations/ide-tool-integration' },
+						{ label: 'Microsoft 365 Copilot Cowork (Experimental)', slug: 'integrations/copilot-cowork' },
 						{ label: 'AI Runtime Compatibility', slug: 'integrations/runtime-compatibility' },
 						{ label: 'GitHub Rulesets', slug: 'integrations/github-rulesets' },
 					],

@@ -0,0 +1,145 @@
+---
+title: "Microsoft 365 Copilot Cowork (Experimental)"
+description: "Deploy APM skills to Microsoft 365 Copilot Cowork through a OneDrive-synchronised skills folder."
+sidebar:
+  order: 4
+---
+
+:::caution[Frontier preview]
+This integration is experimental and off by default. You must enable the `copilot-cowork` flag before using it.
+
+```bash
+apm experimental enable copilot-cowork
+```
+
+Until the flag is enabled, the `copilot-cowork` target stays inert: it is hidden from active target detection, and explicit `--target copilot-cowork` installs fail cleanly instead of deploying anything.
+:::
+
+## What it does
+
+When the `copilot-cowork` flag is enabled, APM can deploy package skills to Microsoft 365 Copilot Cowork at user scope. APM writes each deployed skill to Cowork's fixed OneDrive convention:
+
+```text
+<onedrive-root>/Documents/Cowork/skills/<package-name>/SKILL.md
+```
+
+## Enable the flag
+
+```bash
+apm experimental enable copilot-cowork
+apm experimental list
+apm experimental disable copilot-cowork
+```
+
+Use `apm experimental list` to confirm whether `copilot-cowork` is enabled on the current machine.
+
+## OneDrive auto-detection
+
+Resolution is first match wins:
+
+1. If `APM_COPILOT_COWORK_SKILLS_DIR` is set, APM uses that path as-is.
+2. Otherwise if `apm config set copilot-cowork-skills-dir` has stored a path, APM uses that persisted value.
+3. Otherwise APM falls back to platform-specific detection.
+
+| Platform | Resolution |
+|----------|------------|
+| macOS | Search `~/Library/CloudStorage/OneDrive*`. One match is used. No matches means Cowork is unavailable. Two or more matches fail with an actionable error that lists the candidates and recommends `APM_COPILOT_COWORK_SKILLS_DIR`. |
+| Windows | Use `%ONEDRIVECOMMERCIAL%`, then `%ONEDRIVE%`. |
+| Linux | No default lookup. Set `APM_COPILOT_COWORK_SKILLS_DIR` or persist the path with `apm config set copilot-cowork-skills-dir ...`. |
+
+When APM finds a OneDrive root, it always deploys to `Documents/Cowork/skills/` under that root.
+
+## APM_COPILOT_COWORK_SKILLS_DIR override
+
+Set `APM_COPILOT_COWORK_SKILLS_DIR` when you need to bypass auto-detection, such as:
+
+- a non-standard OneDrive install
+- a multi-tenant macOS machine
+- Linux, where there is no platform default
+
+Example:
+
+```bash
+export APM_COPILOT_COWORK_SKILLS_DIR="$HOME/Library/CloudStorage/OneDrive - Contoso/Documents/Cowork/skills"
+```
+
+## Persisting the skills directory
+
+Use `apm config` when you want the Cowork skills path to persist across shells. This is especially useful on Linux, where there is no auto-detection and you would otherwise need to export `APM_COPILOT_COWORK_SKILLS_DIR` in every shell.
+
+Set a persisted path:
+
+```bash
+apm experimental enable copilot-cowork
+apm config set copilot-cowork-skills-dir "$HOME/OneDrive/Documents/Cowork/skills"
+```
+
+`apm config set copilot-cowork-skills-dir` requires the `copilot-cowork` experimental flag. APM expands `~`, rejects empty or whitespace-only values, and rejects relative paths. The path does not need to exist yet, which is useful while OneDrive is still synchronising.
+
+Inspect the stored value:
+
+```bash
+apm config get copilot-cowork-skills-dir
+```
+
+`apm config get copilot-cowork-skills-dir` works whether or not the `copilot-cowork` flag is enabled, and prints the stored path or `Not set`.
+
+Clear the persisted path:
+
+```bash
+apm config unset copilot-cowork-skills-dir
+```
+
+`apm config unset copilot-cowork-skills-dir` also works whether or not the `copilot-cowork` flag is enabled.
+
+## Install
+
+Cowork is user-scope only. Use `--global`, and add `--target copilot-cowork` when you want to target Cowork explicitly.
+
+```bash
+apm install --global
+apm install --target copilot-cowork --global
+```
+
+Cowork deployments are skills only:
+
+```text
+.apm/skills/<name>/SKILL.md
+-> <onedrive-root>/Documents/Cowork/skills/<name>/SKILL.md
+```
+
+If you try project scope, APM stops with a clean error that tells you to rerun with `--global`.
+
+## Skills-only behaviour
+
+Cowork deploys only `SKILL.md` content. Instructions, agents, prompts, hooks, commands, chatmodes, and MCP material are skipped for this target.
+
+If any selected package contains non-skill primitives, APM emits one `[!]` summary warning for the whole install run. The install still succeeds, and the skill content still deploys.
+
+## Caps
+
+Cowork limits are warn-only. They never block install:
+
+- More than 50 skills in the Cowork directory after install -> one `[!]` warning recommending review.
+- Any individual `SKILL.md` larger than 1 MiB -> one `[!]` warning for that file.
+
+## Lockfile representation
+
+In `apm.lock.yaml`, Cowork-deployed paths are recorded as synthetic URIs such as:
+
+```text
+cowork://skills/my-skill/SKILL.md
+```
+
+This keeps the lockfile portable across machines, users, and OneDrive tenants. APM translates between `cowork://skills/...` and absolute filesystem paths only at I/O boundaries; internal install logic still works with absolute `Path` objects.
+
+## Troubleshooting
+
+- Cowork unavailable or no OneDrive detected: confirm OneDrive is installed and synchronising, then set `APM_COPILOT_COWORK_SKILLS_DIR`.
+- macOS multi-tenant error: set `APM_COPILOT_COWORK_SKILLS_DIR` to the account you want to use.
+- Linux: set `APM_COPILOT_COWORK_SKILLS_DIR` or persist the path with `apm config set copilot-cowork-skills-dir ...`.
+- Path still persists after disabling `copilot-cowork`: run `apm config unset copilot-cowork-skills-dir` to remove the stored value.
+- Project-scope error: rerun with `--global`.
+- Non-skill primitives skipped: expected behaviour. Cowork only deploys skills.
+
+See also [IDE and Tool Integration](../ide-tool-integration/) and [apm experimental](../../reference/experimental/).
@@ -51,7 +51,7 @@ apm compile
 
 For running agentic workflows locally, see the [Agent Workflows guide](../../guides/agent-workflows/).
 
-> **User-scope deployment**: `apm install -g` deploys primitives to user-level directories (`~/.copilot/`, `~/.claude/`, etc.), making packages available across all projects. See [Global Installation](../../guides/dependencies/#global-user-scope-installation) for per-target coverage.
+> **User-scope deployment**: `apm install -g` deploys primitives to user-level directories (`~/.copilot/`, `~/.claude/`, etc.), making packages available across all projects. See [Global Installation](../../guides/dependencies/#global-user-scope-installation) for per-target coverage. For Microsoft 365 Copilot Cowork custom skills, enable `copilot-cowork` with `apm experimental enable copilot-cowork` and use `apm install --target copilot-cowork --global`. See [Microsoft 365 Copilot Cowork](../copilot-cowork/).
 
 ## VS Code Integration
 
@@ -619,4 +619,4 @@ The following IDE integrations are planned for future releases:
 - **[CLI Reference](../../reference/cli-commands/)** -- Complete command documentation
 - Review the [VSCode Copilot Customization Guide](https://code.visualstudio.com/docs/copilot/copilot-customization) for VSCode-specific features
 - Check the [Spec-kit documentation](https://github.com/github/spec-kit) for SDD integration details
-- Explore [MCP servers](https://modelcontextprotocol.io/servers) for tool integration options
+- Explore [MCP servers](https://modelcontextprotocol.io/servers) for tool integration options
@@ -87,7 +87,8 @@ apm install [PACKAGES...] [OPTIONS]
 - `--runtime TEXT` - Target specific runtime only (copilot, codex, gemini, vscode)
 - `--exclude TEXT` - Exclude specific runtime from installation
 - `--only [apm|mcp]` - Install only specific dependency type
-- `--target [copilot|claude|cursor|codex|opencode|gemini|all]` - Force deployment to specific target(s). Accepts comma-separated values for multiple targets (e.g., `-t claude,copilot`). Overrides auto-detection
+- `--target [copilot|claude|cursor|codex|opencode|gemini|copilot-cowork|all]` - Force deployment to specific target(s). Accepts comma-separated values for multiple targets (e.g., `-t claude,copilot`). Overrides auto-detection
+  - `copilot-cowork` - Microsoft 365 Copilot Cowork skills (user scope only, requires `copilot-cowork` experimental flag)
 - `--update` - Update dependencies to latest Git references  
 - `--force` - Overwrite locally-authored files on collision; bypass security scan blocks
 - `--dry-run` - Show what would be installed without installing
@@ -1572,6 +1573,7 @@ apm config get [KEY]
 - `KEY` (optional) - Configuration key to retrieve. Supported keys:
   - `auto-integrate` - Whether to automatically integrate `.prompt.md` files into AGENTS.md
   - `temp-dir` - Custom temporary directory for clone/download operations
+  - `copilot-cowork-skills-dir` - Override the resolved Cowork OneDrive skills directory
 
 If `KEY` is omitted, displays all configuration values.
 
@@ -1596,6 +1598,7 @@ apm config set KEY VALUE
 - `KEY` - Configuration key to set. Supported keys:
   - `auto-integrate` - Enable/disable automatic integration of `.prompt.md` files
   - `temp-dir` - Set a custom temporary directory path
+  - `copilot-cowork-skills-dir` - Override the resolved Cowork OneDrive skills directory
 - `VALUE` - Value to set. For boolean keys, use: `true`, `false`, `yes`, `no`, `1`, `0`
 
 **Configuration Keys:**
@@ -1641,6 +1644,30 @@ apm config get temp-dir
 export APM_TEMP_DIR=/tmp/apm-work
 ```
 
+**`copilot-cowork-skills-dir`** - Override the resolved Cowork OneDrive skills directory
+- **Type:** String (absolute directory path)
+- **Default:** Auto-detected Cowork skills directory (not stored)
+- **Description:** Override the resolved Cowork OneDrive skills directory. Gated on the `copilot-cowork` experimental flag for `set`; `get` and `unset` are always available for cleanup.
+- **Resolution order:** `APM_COPILOT_COWORK_SKILLS_DIR` environment variable > `copilot_cowork_skills_dir` in `~/.apm/config.json` > platform auto-detection.
+- **Use Cases:**
+  - Set a specific OneDrive-backed Cowork skills directory instead of relying on auto-detection
+  - Clear the override with `apm config unset copilot-cowork-skills-dir` when returning to auto-detection
+
+**Examples:**
+```bash
+# Enable the experimental flag, then set an explicit Cowork skills directory
+apm experimental enable copilot-cowork
+apm config set copilot-cowork-skills-dir ~/Library/CloudStorage/OneDrive-Contoso/Documents/Cowork/skills
+
+# Check the current copilot-cowork-skills-dir setting
+apm config get copilot-cowork-skills-dir
+
+# Remove the override and return to auto-detection
+apm config unset copilot-cowork-skills-dir
+```
+
+See also: [Cowork integration](../integrations/copilot-cowork/).
+
 ## Runtime Management (Experimental)
 
 ### `apm runtime` (Experimental) - Manage AI runtimes

@@ -170,8 +170,10 @@ apm experimental reset verbose-version
 | Name              | Description                                                                      |
 |-------------------|----------------------------------------------------------------------------------|
 | `verbose-version` | Show Python version, platform, and install path in `apm --version`.              |
+| `copilot-cowork`  | Deploy APM skills to Microsoft 365 Copilot Cowork via OneDrive.                  |
 
 New flags are proposed via [CONTRIBUTING.md](https://github.com/microsoft/apm/blob/main/CONTRIBUTING.md#how-to-add-an-experimental-feature-flag) and graduate to default when stable. See the contributor recipe for the full lifecycle.
+See also: [Cowork integration](../integrations/copilot-cowork/).
 
 ## Storage and scope
 

@@ -10,7 +10,7 @@
 
 | Command | Purpose | Key flags |
 |---------|---------|-----------|
-| `apm install [PKGS...]` | Install APM and MCP dependencies (supports APM packages, Claude skills (SKILL.md), and plugin collections (plugin.json)) | `--update` refresh refs, `--force` overwrite, `--dry-run`, `--verbose`, `--only [apm\|mcp]`, `--target` (comma-separated), `--dev`, `-g` global, `--trust-transitive-mcp`, `--parallel-downloads N`, `--allow-insecure`, `--allow-insecure-host HOSTNAME`, `--skill NAME` install named skill(s) from SKILL_BUNDLE (repeatable; persisted in apm.yml; `'*'` resets to all), `--mcp NAME` add MCP entry, `--transport`, `--url`, `--env KEY=VAL`, `--header KEY=VAL`, `--mcp-version`, `--registry URL` custom MCP registry |
+| `apm install [PKGS...]` | Install APM and MCP dependencies (supports APM packages, Claude skills (SKILL.md), and plugin collections (plugin.json)) | `--update` refresh refs, `--force` overwrite, `--dry-run`, `--verbose`, `--only [apm\|mcp]`, `--target` (comma-separated; use `copilot-cowork` with `--global` after `apm experimental enable copilot-cowork`), `--dev`, `-g` global, `--trust-transitive-mcp`, `--parallel-downloads N`, `--allow-insecure`, `--allow-insecure-host HOSTNAME`, `--skill NAME` install named skill(s) from SKILL_BUNDLE (repeatable; persisted in apm.yml; `'*'` resets to all), `--mcp NAME` add MCP entry, `--transport`, `--url`, `--env KEY=VAL`, `--header KEY=VAL`, `--mcp-version`, `--registry URL` custom MCP registry |
 | `apm uninstall PKGS...` | Remove packages | `--dry-run`, `-g` global |
 | `apm prune` | Remove orphaned packages | `--dry-run` |
 | `apm deps list` | List installed packages | `-g` global, `--all` both scopes, `--insecure` |
@@ -92,13 +92,18 @@ Set `MCP_REGISTRY_URL` (default `https://api.mcp.github.com`) to point all `apm
 | `apm experimental disable NAME` | Disable an opt-in experimental flag | `-v` verbose |
 | `apm experimental reset [NAME]` | Reset one flag or all flags to defaults; also cleans malformed overrides during bulk reset | `-y` skip confirm, `-v` verbose |
 
+Use `apm experimental enable copilot-cowork` to turn on Microsoft 365 Copilot Cowork skill deployment. Once enabled, deploy skills with `apm install --target copilot-cowork --global`.
+
 Experimental flags MUST NOT gate security-critical behaviour (content scanning, path validation, lockfile integrity, token handling, MCP trust, collision detection). Flags are ergonomic/UX toggles only.
 
 ## Configuration and updates
 
 | Command | Purpose | Key flags |
 |---------|---------|-----------|
 | `apm config` | Show current configuration | -- |
-| `apm config get [KEY]` | Get a config value (`auto-integrate`, `temp-dir`) | -- |
-| `apm config set KEY VALUE` | Set a config value (`auto-integrate`, `temp-dir`) | -- |
+| `apm config get [KEY]` | Get a config value (`auto-integrate`, `temp-dir`, `copilot-cowork-skills-dir`) | -- |
+| `apm config set KEY VALUE` | Set a config value (`auto-integrate`, `temp-dir`; `copilot-cowork-skills-dir` requires `apm experimental enable copilot-cowork`) | -- |
+| `apm config unset KEY` | Remove a stored config value (`temp-dir`, `copilot-cowork-skills-dir`) | -- |
 | `apm update` | Update APM itself (or show distributor guidance when self-update is disabled at build time) | `--check` only check |
+
+`apm config set copilot-cowork-skills-dir <absolute-path>` persists the Cowork skills directory across shells. `apm config get copilot-cowork-skills-dir` and `apm config unset copilot-cowork-skills-dir` remain available even when the `copilot-cowork` flag is disabled so leftover state can still be inspected or cleared. In `apm config` and bare `apm config get`, the `copilot-cowork-skills-dir` entry is shown only when the `copilot-cowork` flag is enabled.