feat: add openclaw as experimental skills target

Add OpenClaw (github.com/openclaw/openclaw) as an experimental
deployment target for skills.  Once enabled via
'apm experimental enable openclaw', users can deploy SKILL.md
bundles to:

  project scope: .agents/skills/<name>/SKILL.md
  user scope:    ~/.openclaw/skills/<name>/SKILL.md (--global)

At project scope the output is identical to agent-skills; the
--global user path (~/.openclaw/skills/) is the distinguishing
capability -- it maps to OpenClaw's priority-4 managed skill
loading directory.

Changes:
- Register ExperimentalFlag 'openclaw' in FLAGS
- Add KNOWN_TARGETS['openclaw'] TargetProfile
- Wire into EXPERIMENTAL_TARGETS, get_target_description(),
  _CROSS_TARGET_MAPS, and enable-hint UX block
- Update exact-set guardian tests
- Add 25 new tests (E2E, constants, flags, profile, description,
  cross-target-map)
- Update targets-matrix docs and apm-usage commands.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Sergio Sisternes

docs/src/content/docs/reference/targets-matrix.md

@@ -32,9 +32,10 @@ Skills deploy to `.agents/skills/` for Copilot, Cursor, OpenCode,
 Gemini, and Codex by default (see [Skills convergence](#skills-convergence)
 below). Claude and Windsurf keep target-native skill directories.
 
-`copilot-cowork` (Microsoft 365 Copilot) and `copilot-app` (GitHub
-Copilot desktop App) are gated behind experimental flags and not listed
-above. See [Experimental](./experimental/).
+`copilot-cowork` (Microsoft 365 Copilot), `copilot-app` (GitHub
+Copilot desktop App), and `openclaw` (OpenClaw agent runtime) are
+gated behind experimental flags and not listed above. See
+[Experimental](./experimental/).
 
 ## Detection and resolution
 
@@ -61,7 +62,7 @@ list before `compile` or `install`.
 | opencode | `.opencode/` directory                        |
 | windsurf | `.windsurf/` directory                        |
 
-`agent-skills`, `copilot-cowork`, and `copilot-app` are never
+`agent-skills`, `copilot-cowork`, `copilot-app`, and `openclaw` are never
 auto-detected. Select them explicitly with `--target`, or list them in
 a project's `apm.yml` `targets:` field so contributors running plain
 `apm install` pick them up automatically.
@@ -177,6 +178,23 @@ Cross-client shared skills directory.
 - **File conventions.** `.agents/skills/<name>/SKILL.md`.
 - **Use case.** Author-time target for shipping a SKILL bundle that any Skills-aware client (Codex, Copilot CLI, Claude Code, etc.) can read without per-tool deployment.
 
+## openclaw (experimental)
+
+[OpenClaw](https://github.com/openclaw/openclaw) agent runtime.
+
+- **Detection.** Never auto-detected. Select with `--target openclaw`
+  after enabling the experimental flag.
+- **Enable.** `apm experimental enable openclaw`.
+- **Deploy directory.** `.agents/skills/` at project scope (identical to
+  `agent-skills`); `~/.openclaw/skills/` at user scope (`--global`).
+- **Supported primitives.** skills only.
+- **File conventions.** `.agents/skills/<name>/SKILL.md` (project) or
+  `~/.openclaw/skills/<name>/SKILL.md` (user).
+- **Note.** At project scope the output is identical to `agent-skills`.
+  The `--global` user path is the distinguishing capability, deploying
+  skills where OpenClaw reads its managed/local skill directory
+  (priority 4 in the OpenClaw loading order).
+
 ## Skills convergence
 
 By default, every target with a `skills` primitive deploys to `.agents/skills/<name>/SKILL.md` rather than under the target root. This matches the cross-tool agent skills convention so a single skill bundle serves every harness.

packages/apm-guide/.apm/skills/apm-usage/commands.md

@@ -179,6 +179,8 @@ Use `apm experimental enable copilot-cowork` to turn on Microsoft 365 Copilot Co
 
 Use `apm experimental enable copilot-app` to turn on GitHub Copilot desktop App workflow deployment. Once enabled, prompts that carry workflow frontmatter -- any flat top-level key of `interval`, `schedule_hour`, `schedule_day` -- can be deployed to the App's SQLite store at `~/.copilot/data.db` with `apm install --target copilot-app` (project scope) or `--target copilot-app --global` (user scope). A `.prompt.md` belongs to exactly ONE surface: workflow-shape prompts go to the App DB, plain prompts go to slash-command targets. Rows always start `enabled = 0` -- you opt in from the App. `apm install / update / uninstall` preserve user state (`enabled`, `last_run_at`, schedule overrides). Override the database path with `APM_COPILOT_APP_DB=<abs-path>`. Workflows are scoped to a real Copilot App project: when the App is running APM registers the project over the App's loopback WebSocket so the project is immediately known to the webview; when the App is closed APM falls back to a direct-SQLite `BEGIN IMMEDIATE` resolver. The first install in a brand-new repo prints a one-time "restart the Copilot App once" hint (see github/github-app#5483); subsequent installs are silent. `--global` installs that carry workflow-shape prompts warn-and-proceed because workflows run with `CWD=~/.copilot` rather than a repo -- attach the row to a project from the App's Workflows tab to fix.
 
+Use `apm experimental enable openclaw` to turn on OpenClaw agent runtime skill deployment. Once enabled, deploy skills with `apm install --target openclaw` (project scope, `.agents/skills/`) or `apm install --target openclaw --global` (user scope, `~/.openclaw/skills/`). At project scope, output is identical to `agent-skills`; the `--global` user path is the distinguishing capability.
+
 ### Cross-client skills (`agent-skills`)
 
 Use `--target agent-skills` to deploy skills to `.agents/skills/` -- the cross-tool standard directory. This is useful when multiple clients (Codex, future tools) read from `.agents/skills/`. Unlike `--target all`, `agent-skills` must be requested explicitly: `apm install --target agent-skills` or `apm install --target all,agent-skills` for both. `apm compile --target agent-skills` is a no-op (skills-only target).

src/apm_cli/bundle/lockfile_enrichment.py

@@ -52,6 +52,9 @@
     "agent-skills": {
         ".github/skills/": ".agents/skills/",
     },
+    "openclaw": {
+        ".github/skills/": ".agents/skills/",
+    },
 }
 
 

src/apm_cli/core/experimental.py

@@ -107,6 +107,16 @@ class ExperimentalFlag:
             "See https://microsoft.github.io/apm/integrations/external-scanners/"
         ),
     ),
+    "openclaw": ExperimentalFlag(
+        name="openclaw",
+        description="Deploy skills to OpenClaw agent runtime directories.",
+        default=False,
+        hint=(
+            "Use '--target openclaw' to deploy skills to your project, "
+            "or '--target openclaw --global' for your personal OpenClaw "
+            "skills at ~/.openclaw/skills/."
+        ),
+    ),
 }
 
 

src/apm_cli/core/target_detection.py

@@ -300,6 +300,7 @@ def get_target_description(target: UserTargetType) -> str:
         "gemini": "GEMINI.md + .gemini/commands/ + .gemini/skills/ + .gemini/settings.json (MCP/hooks)",
         "windsurf": "AGENTS.md + .windsurf/rules/ + .windsurf/skills/ + .windsurf/workflows/ + .windsurf/hooks.json",
         "agent-skills": ".agents/skills/ only (cross-client shared skills -- no agents, hooks, or commands)",
+        "openclaw": ".agents/skills/ (project) or ~/.openclaw/skills/ (--global) -- experimental",
         "all": "AGENTS.md + CLAUDE.md + GEMINI.md + .github/copilot-instructions.md + .github/ + .claude/ + .cursor/ + .opencode/ + .codex/ + .gemini/ + .windsurf/ + .agents/",
         "minimal": "AGENTS.md only (create .github/, .claude/, or .gemini/ for full integration)",
     }
@@ -320,7 +321,7 @@ def get_target_description(target: UserTargetType) -> str:
 #: ``is_enabled()`` in ``core/experimental.py`` and ``_flag_gated()`` in
 #: ``integration/targets.py``.  They are NOT included in the
 #: ``parse_target_arg("all")`` expansion -- explicit opt-in only.
-EXPERIMENTAL_TARGETS: frozenset[str] = frozenset({"copilot-cowork", "copilot-app"})
+EXPERIMENTAL_TARGETS: frozenset[str] = frozenset({"copilot-cowork", "copilot-app", "openclaw"})
 
 #: Stable targets excluded from "all" expansion (cross-client deploy
 #: locations). Unlike EXPERIMENTAL_TARGETS, these are GA -- they just do

src/apm_cli/install/phases/targets.py

@@ -324,6 +324,30 @@ def run(ctx: InstallContext) -> None:
     # restart is needed; the SQLite path is the fallback for the
     # App-closed case (still the common case during install).
 
+    # ------------------------------------------------------------------
+    # OpenClaw target gating: explicit --target openclaw with the flag
+    # OFF must hint at the experimental enable command.
+    # ------------------------------------------------------------------
+    _user_asked_openclaw = False
+    if _explicit:
+        if isinstance(_explicit, list):
+            _user_asked_openclaw = "openclaw" in _explicit
+        else:
+            _user_asked_openclaw = _explicit == "openclaw"
+
+    if _user_asked_openclaw:
+        _openclaw_resolved = any(t.name == "openclaw" for t in _targets)
+        if not _openclaw_resolved:
+            from apm_cli.core.experimental import is_enabled as _is_flag_on
+
+            if not _is_flag_on("openclaw"):
+                if ctx.logger:
+                    ctx.logger.progress(
+                        "The 'openclaw' target requires an experimental flag. "
+                        "Run: apm experimental enable openclaw",
+                        symbol="info",
+                    )
+
     # ------------------------------------------------------------------
     # v2 resolution (#1154): signal-based provenance and strict errors.
     # Runs AFTER the legacy resolver and cowork gates so existing

src/apm_cli/integration/targets.py

@@ -609,6 +609,31 @@ def for_scope(self, user_scope: bool = False) -> TargetProfile | None:
         user_root_dir=".agents",
         generated_files=(),
     ),
+    # OpenClaw -- experimental, skills-only target for the OpenClaw agent
+    # runtime (github.com/openclaw/openclaw).  OpenClaw reads SKILL.md
+    # directories from several locations; APM deploys to:
+    #   project scope: <workspace>/.agents/skills/ (agentskills.io standard,
+    #                  OpenClaw priority-2 load path)
+    #   user scope:    ~/.openclaw/skills/ (OpenClaw managed dir, priority-4)
+    # At project scope the output is identical to the agent-skills target;
+    # the --global user path is the distinguishing capability.
+    # Ref: https://docs.openclaw.ai/tools/skills
+    "openclaw": TargetProfile(
+        name="openclaw",
+        root_dir=".agents",
+        primitives={
+            "skills": PrimitiveMapping(
+                "skills",
+                "/SKILL.md",
+                "skill_standard",
+            ),
+        },
+        auto_create=True,
+        detect_by_dir=False,
+        user_supported=True,
+        user_root_dir=".openclaw",
+        requires_flag="openclaw",
+    ),
     # Microsoft 365 Copilot (Cowork) -- experimental, user-scope only.
     # Skills are deployed to <OneDrive>/Documents/Cowork/skills/.
     # The deploy root is resolved dynamically at runtime via