diff --git a/README.md b/README.md
index d1025f03..83dd8639 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,7 @@ Common CLI flows:
 - Inspect without installing: `clawhub inspect <slug>`
 - Publish/sync skills: `clawhub skill publish <path>`, `clawhub sync`
 - Publish plugins: `clawhub package publish <source>`
+- Code-plugin manifests must include `openclaw.compat.pluginApi` and `openclaw.build.openclawVersion`; see [`docs/cli.md`](docs/cli.md) for a minimal example.
 - Canonicalize owned skills: `clawhub skill rename <slug> <new-slug>`, `clawhub skill merge <source> <target>`
 
 Docs: [`docs/quickstart.md`](docs/quickstart.md), [`docs/cli.md`](docs/cli.md).
diff --git a/docs/cli.md b/docs/cli.md
index 6f7d8c15..fa1c6373 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -260,6 +260,53 @@ clawhub package explore episodic-claw --family code-plugin
 - Existing flags (`--family`, `--name`, `--version`, `--source-repo`, `--source-commit`, `--source-ref`, `--source-path`) still work as overrides.
 - Private GitHub repos require `GITHUB_TOKEN`.
 
+#### Recommended local flow
+
+Use `--dry-run` first so you can confirm the resolved package metadata and
+source attribution before creating a live release:
+
+```bash
+clawhub package publish ./my-plugin --family code-plugin --dry-run
+clawhub package publish ./my-plugin --family code-plugin
+```
+
+#### Minimal `package.json` for `--family code-plugin`
+
+External code plugins need a small amount of OpenClaw metadata in
+`package.json`. This minimal manifest is enough for a successful publish:
+
+```json
+{
+  "name": "@myorg/openclaw-my-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24-beta.2"
+    }
+  }
+}
+```
+
+Required fields:
+
+- `openclaw.compat.pluginApi`
+- `openclaw.build.openclawVersion`
+
+Notes:
+
+- `package.json.version` is your package release version, but it is not used as
+  a fallback for OpenClaw compatibility/build validation.
+- `openclaw.compat.minGatewayVersion` and
+  `openclaw.build.pluginSdkVersion` are optional extras if you want to publish
+  more detailed compatibility metadata.
+- If you are using an older `clawhub` CLI release, upgrade before publishing so
+  the local preflight checks run before upload.
+
 #### GitHub Actions
 
 ClawHub also ships an official reusable workflow at
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 06ef8e97..db06b9db 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -106,7 +106,54 @@ bun clawhub skill publish . \
   --changelog "Initial release"
 ```
 
-## 5) Sync local skills (auto-publish new/changed)
+## 5) Publish a code plugin
+
+Create a plugin folder with a `package.json` that includes the required OpenClaw
+publish metadata:
+
+```bash
+mkdir -p /tmp/clawhub-plugin-demo && cd /tmp/clawhub-plugin-demo
+cat > package.json <<'EOF'
+{
+  "name": "@demo/openclaw-plugin-demo",
+  "version": "0.1.0",
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24-beta.2"
+    }
+  }
+}
+EOF
+```
+
+Preview the resolved publish payload first:
+
+```bash
+bun clawhub package publish . --family code-plugin --dry-run
+```
+
+Then publish:
+
+```bash
+bun clawhub package publish . --family code-plugin
+```
+
+Notes:
+
+- `openclaw.compat.pluginApi` and `openclaw.build.openclawVersion` are required
+  for `code-plugin` publishes.
+- `package.json.version` does not replace either required OpenClaw field.
+- Add `openclaw.compat.minGatewayVersion` and
+  `openclaw.build.pluginSdkVersion` when you want to expose fuller
+  compatibility/build metadata, but they are not required for a successful
+  publish.
+
+## 6) Sync local skills (auto-publish new/changed)
 
 `sync` scans for local skill folders and publishes the ones that aren’t “synced” yet.
 
diff --git a/packages/clawhub/README.md b/packages/clawhub/README.md
index 0fb244af..4e19db4e 100644
--- a/packages/clawhub/README.md
+++ b/packages/clawhub/README.md
@@ -51,6 +51,44 @@ clawhub package publish https://github.com/openclaw/example-plugin --dry-run
 clawhub package publish ./example-plugin
 ```
 
+## Publish code plugins
+
+For local plugin folders, start with a dry run:
+
+```bash
+clawhub package publish ./my-plugin --family code-plugin --dry-run
+clawhub package publish ./my-plugin --family code-plugin
+```
+
+`code-plugin` packages must declare these `package.json` fields:
+
+- `openclaw.compat.pluginApi`
+- `openclaw.build.openclawVersion`
+
+Minimal example:
+
+```json
+{
+  "name": "@myorg/openclaw-my-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "openclaw": {
+    "extensions": ["./index.ts"],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24-beta.2"
+    }
+  }
+}
+```
+
+`package.json.version` does not replace these OpenClaw-specific fields. Add
+`openclaw.compat.minGatewayVersion` and
+`openclaw.build.pluginSdkVersion` when you want richer compatibility metadata,
+but they are not required for publish.
+
 ## GitHub Actions
 
 This repo also provides an official reusable workflow for plugin repos: