fix: scope agent skill installation

refs #2022

3 files changed, 15 insertions, 9 deletions

diff --git a/website/src/content/docs/agent-skill.mdx b/website/src/content/docs/agent-skill.mdx
index 498861f7..361a7319 100644
--- a/website/src/content/docs/agent-skill.mdx
+++ b/website/src/content/docs/agent-skill.mdx
@@ -3,7 +3,7 @@ title: Agent skill file
 description: Install Herdr instructions for Claude Code or another coding agent.
 ---
 
-Herdr ships a reusable agent skill file at [`SKILL.md`](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md).
+Herdr ships a reusable agent skill file at [`skills/herdr/SKILL.md`](https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md).
 
 Install that file into any coding agent that supports reusable skills or custom instructions. The skill teaches the agent how to control Herdr from inside a Herdr pane.
 
@@ -31,12 +31,14 @@ Install the skill with `npx skills`:
 npx skills add ogulcancelik/herdr --skill herdr -g
 ```
 
+If you installed the skill while it lived at the repository root, rerun this add command once instead of using `skills update`. The add command replaces the oversized copy and records the new location.
+
 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
+https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md
 ```
 
 For agents with a skill system, install that file as a skill named `herdr`. For agents without a skill system, paste the file into the agent's project or user instructions.
@@ -62,4 +64,4 @@ The full command guide lives in the skill file itself. It covers pane IDs, `pane
 
 Read the source file here:
 
-[Open `SKILL.md` on GitHub →](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md)
+[Open `SKILL.md` on GitHub →](https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md)
diff --git a/website/src/content/docs/ja/agent-skill.mdx b/website/src/content/docs/ja/agent-skill.mdx
index 97d109f7..c89c61e2 100644
--- a/website/src/content/docs/ja/agent-skill.mdx
+++ b/website/src/content/docs/ja/agent-skill.mdx
@@ -3,7 +3,7 @@ title: エージェントスキルファイル
 description: Claude Code などのコーディングエージェントに Herdr の使い方をインストールします。
 ---
 
-Herdr は再利用可能なエージェントスキルファイルを [`SKILL.md`](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md) として提供しています。
+Herdr は再利用可能なエージェントスキルファイルを [`skills/herdr/SKILL.md`](https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md) として提供しています。
 
 このファイルを、再利用可能なスキルやカスタム指示に対応した任意のコーディングエージェントにインストールしてください。このスキルは、Herdr のペイン内から Herdr を制御する方法をエージェントに教えます。
 
@@ -31,12 +31,14 @@ Herdr は別の用途向けに [`herdr.dev/agent-guide.md`](https://herdr.dev/ag
 npx skills add ogulcancelik/herdr --skill herdr -g
 ```
 
+スキルがリポジトリのルートにあったときにインストールした場合は、`skills update` ではなく、この add コマンドを一度再実行してください。大きすぎる既存のコピーが置き換えられ、新しい場所が記録されます。
+
 `-g` フラグは、対応エージェントにグローバルインストールします。現在のプロジェクトにインストールする場合は `-g` を省略してください。
 
 手動でのフォールバックおよび信頼できるソースとしては、リポジトリのコピーを使ってください:
 
 ```text
-https://github.com/ogulcancelik/herdr/blob/master/SKILL.md
+https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md
 ```
 
 スキルシステムを持つエージェントには、このファイルを `herdr` という名前のスキルとしてインストールしてください。スキルシステムを持たないエージェントには、ファイルの内容をプロジェクト指示またはユーザー指示に貼り付けてください。
@@ -62,4 +64,4 @@ claude
 
 ソースファイルはこちら:
 
-[GitHub で `SKILL.md` を開く →](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md)
+[GitHub で `SKILL.md` を開く →](https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md)
diff --git a/website/src/content/docs/zh-cn/agent-skill.mdx b/website/src/content/docs/zh-cn/agent-skill.mdx
index f905f347..8f0b015b 100644
--- a/website/src/content/docs/zh-cn/agent-skill.mdx
+++ b/website/src/content/docs/zh-cn/agent-skill.mdx
@@ -3,7 +3,7 @@ title: 智能体技能文件
 description: 为 Claude Code 或其他编程智能体安装 Herdr 使用说明。
 ---
 
-Herdr 提供了一个可复用的智能体技能文件: [`SKILL.md`](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md)。
+Herdr 提供了一个可复用的智能体技能文件: [`skills/herdr/SKILL.md`](https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md)。
 
 把这个文件安装到任何支持可复用技能或自定义指令的编程智能体中。这份技能教智能体如何在 Herdr 窗格内部控制 Herdr。
 
@@ -31,12 +31,14 @@ Herdr 还提供了另一份用途不同的指南: [`herdr.dev/agent-guide.md`](h
 npx skills add ogulcancelik/herdr --skill herdr -g
 ```
 
+如果你是在该技能仍位于仓库根目录时安装的，请重新运行一次此 add 命令，而不要使用 `skills update`。add 命令会替换原先过大的副本并记录新位置。
+
 `-g` 参数为受支持的智能体全局安装。省略 `-g` 则安装到当前项目。
 
 以仓库中的副本作为手动兜底和事实来源:
 
 ```text
-https://github.com/ogulcancelik/herdr/blob/master/SKILL.md
+https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md
 ```
 
 对于有技能系统的智能体,把这个文件安装为名为 `herdr` 的技能。对于没有技能系统的智能体,把文件内容粘贴到智能体的项目指令或用户指令中。
@@ -62,4 +64,4 @@ claude
 
 在这里阅读源文件:
 
-[在 GitHub 上打开 `SKILL.md` →](https://github.com/ogulcancelik/herdr/blob/master/SKILL.md)
+[在 GitHub 上打开 `SKILL.md` →](https://github.com/ogulcancelik/herdr/blob/master/skills/herdr/SKILL.md)