docs: add skills cli install guidance

2 files changed, 16 insertions, 2 deletions

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