docs: add skills cli install guidance

5 files changed, 33 insertions, 5 deletions

diff --git a/README.md b/README.md
index d7ff6999..7ebd7c69 100644
--- a/README.md
+++ b/README.md
@@ -119,7 +119,13 @@ official integrations add native session restore, and some report semantic state
 
 ## agents can use herdr too
 
-the local Unix socket lets agents create workspaces, split or zoom panes, spawn helpers, read output, and subscribe to state changes instead of polling. start with the [socket API docs](https://herdr.dev/docs/socket-api/) and [`SKILL.md`](./SKILL.md).
+the local Unix socket lets agents create workspaces, split or zoom panes, spawn helpers, read output, and subscribe to state changes instead of polling. install the reusable skill with:
+
+```bash
+npx skills add ogulcancelik/herdr --skill herdr -g
+```
+
+start with the [agent skill docs](https://herdr.dev/docs/agent-skill/), [socket API docs](https://herdr.dev/docs/socket-api/), and [`SKILL.md`](./SKILL.md).
 
 ## docs
 
diff --git a/docs/next/README.md b/docs/next/README.md
index d8e46b36..671cab17 100644
--- a/docs/next/README.md
+++ b/docs/next/README.md
@@ -170,7 +170,13 @@ not a gui window, not a web dashboard, not electron. herdr runs inside whatever
 
 ## agents can use herdr too
 
-The local Unix socket lets agents create workspaces, split or zoom panes, spawn helpers, read output, and wait for state changes. Start with the [socket API docs](https://herdr.dev/docs/socket-api/) and [`SKILL.md`](./SKILL.md).
+The local Unix socket lets agents create workspaces, split or zoom panes, spawn helpers, read output, and wait for state changes. Install the reusable skill with:
+
+```bash
+npx skills add ogulcancelik/herdr --skill herdr -g
+```
+
+Start with the [agent skill docs](https://herdr.dev/docs/agent-skill/), [socket API docs](https://herdr.dev/docs/socket-api/), and [`SKILL.md`](./SKILL.md).
 
 ## supported agents
 
diff --git a/docs/next/website/src/content/docs/agent-skill.mdx b/docs/next/website/src/content/docs/agent-skill.mdx
index af7fa7bf..13a90154 100644
--- a/docs/next/website/src/content/docs/agent-skill.mdx
+++ b/docs/next/website/src/content/docs/agent-skill.mdx
@@ -25,7 +25,15 @@ The skill is not a separate app or service. It is a markdown instruction file fo
 
 ## Install it
 
-Use the repository copy as the source of truth:
+Install the skill with `npx skills`:
+
+```bash
+npx skills add ogulcancelik/herdr --skill herdr -g
+```
+
+The `-g` flag installs it globally for supported agents. Omit `-g` to install it into the current project.
+
+Use the repository copy as the manual fallback and source of truth:
 
 ```text
 https://github.com/ogulcancelik/herdr/blob/master/SKILL.md
diff --git a/website/agent-guide.md b/website/agent-guide.md
index ed845fc0..d40e8833 100644
--- a/website/agent-guide.md
+++ b/website/agent-guide.md
@@ -67,7 +67,7 @@ Important framing for new users: Herdr does not require learning keybindings. Th
 
 Herdr ships `SKILL.md` (https://raw.githubusercontent.com/ogulcancelik/herdr/master/SKILL.md), an instruction file that teaches a coding agent to control Herdr from inside a pane — splitting panes, running commands without stealing focus, reading output, waiting on other agents.
 
-Once the human is set up, offer to install it into your own harness so future sessions know Herdr natively. You know your own conventions best; install it wherever your global reusable instructions live. For example: Claude Code installs it as a skill (e.g. `~/.claude/skills/herdr/SKILL.md`); Codex and similar agents include it from their global instructions file (e.g. `~/.codex/AGENTS.md`); agents without a skill system can paste it into global custom instructions. Ask the human before writing to their config locations, and use the GitHub copy above as the source of truth.
+Once the human is set up, offer to install it into your own harness so future sessions know Herdr natively. For agents supported by the open skills CLI, use `npx skills add ogulcancelik/herdr --skill herdr -g`. Agents without a skill system can paste the GitHub copy above into global custom instructions. Ask the human before writing to their config locations, and use the GitHub copy above as the source of truth.
 
 ## Configuration
 
diff --git a/website/src/content/docs/agent-skill.mdx b/website/src/content/docs/agent-skill.mdx
index af7fa7bf..13a90154 100644
--- a/website/src/content/docs/agent-skill.mdx
+++ b/website/src/content/docs/agent-skill.mdx
@@ -25,7 +25,15 @@ The skill is not a separate app or service. It is a markdown instruction file fo
 
 ## Install it
 
-Use the repository copy as the source of truth:
+Install the skill with `npx skills`:
+
+```bash
+npx skills add ogulcancelik/herdr --skill herdr -g
+```
+
+The `-g` flag installs it globally for supported agents. Omit `-g` to install it into the current project.
+
+Use the repository copy as the manual fallback and source of truth:
 
 ```text
 https://github.com/ogulcancelik/herdr/blob/master/SKILL.md