From a20841d3912ce725e5dc8b69af27535270cba020 Mon Sep 17 00:00:00 2001
From: kriptoburak <kriptoburak@users.noreply.github.com>
Date: Fri, 12 Jun 2026 13:35:54 +0200
Subject: [PATCH] docs: add OpenClaw package skill guidance

---
 docs/INTEGRATION.md    | 55 ++++++++++++++++++++++++++++++++++++++++++
 docs/SKILLFLAG_SPEC.md |  4 +--
 2 files changed, 57 insertions(+), 2 deletions(-)

diff --git a/docs/INTEGRATION.md b/docs/INTEGRATION.md
index 428ca4d..47ec6b8 100644
--- a/docs/INTEGRATION.md
+++ b/docs/INTEGRATION.md
@@ -38,6 +38,61 @@ Ensure the `skills/` directory is included in your published package. For npm:
 
 If you publish via a different mechanism, just make sure the skill directory ships alongside your built CLI output.
 
+### OpenClaw plugin packages
+
+OpenClaw plugins can already declare packaged skills in `openclaw.plugin.json`.
+If your plugin also exposes a user-facing CLI, Skillflag can export the same
+skills to Codex, Claude, Goose, and other agents without adding agent-specific
+install paths to the plugin itself.
+
+For a package shaped like `@xquik/tweetclaw`, keep the install metadata and
+skill folder in the package:
+
+```json
+{
+  "name": "@xquik/tweetclaw",
+  "files": ["dist", "skills/tweetclaw/SKILL.md", "openclaw.plugin.json"],
+  "openclaw": {
+    "install": {
+      "defaultChoice": "npm",
+      "npmSpec": "@xquik/tweetclaw"
+    }
+  }
+}
+```
+
+```json
+{
+  "id": "tweetclaw",
+  "skills": ["skills/tweetclaw"]
+}
+```
+
+Then point the CLI entrypoint at the package's `skills/` directory:
+
+```ts
+import { findSkillsRoot, maybeHandleSkillflag } from "skillflag";
+
+await maybeHandleSkillflag(process.argv, {
+  includeBundledSkill: false,
+  skillsRoot: findSkillsRoot(import.meta.url),
+});
+```
+
+This keeps OpenClaw installation native:
+
+```bash
+openclaw plugins install npm:@xquik/tweetclaw
+```
+
+After the package wires that entrypoint to a `tweetclaw` bin, users also get a
+portable skill export path for non-OpenClaw agents:
+
+```bash
+tweetclaw --skill list
+tweetclaw --skill export tweetclaw | npx skillflag install --agent codex
+```
+
 ## 3) Wire `--skill` early in your CLI
 
 Intercept `--skill` before your regular CLI parsing so Skillflag can take over. Example (ESM):
diff --git a/docs/SKILLFLAG_SPEC.md b/docs/SKILLFLAG_SPEC.md
index 610f40d..34bce8a 100644
--- a/docs/SKILLFLAG_SPEC.md
+++ b/docs/SKILLFLAG_SPEC.md
@@ -1,6 +1,6 @@
 ---
 title: Skillflag Specification
-author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+author: Onur Solmaz (GitHub: osolmaz)
 date: 2026-01-11
 ---
 
@@ -589,7 +589,7 @@ If a tool isn’t listed, `skill-install` must support:
 This keeps the spec future-proof without baking in every new agent.
 
 [1]: https://developers.openai.com/codex/skills/ "Agent Skills"
-[2]: https://block.github.io/goose/docs/guides/context-engineering/using-skills/ "Using Skills | goose"
+[2]: https://goose-docs.ai/docs/guides/context-engineering/using-skills/ "Agent Skills | goose"
 [3]: https://code.claude.com/docs/en/skills "Agent Skills - Claude Code Docs"
 [4]: https://docs.github.com/copilot/concepts/agents/about-agent-skills "About Agent Skills - GitHub Docs"
 [5]: https://ampcode.com/news/agent-skills "Agent Skills - Amp"