diff --git a/SKILL.md b/htsy/SKILL.md
similarity index 100%
rename from SKILL.md
rename to htsy/SKILL.md
diff --git a/references/api-account.md b/htsy/references/api-account.md
similarity index 100%
rename from references/api-account.md
rename to htsy/references/api-account.md
diff --git a/references/api-automation.md b/htsy/references/api-automation.md
similarity index 100%
rename from references/api-automation.md
rename to htsy/references/api-automation.md
diff --git a/references/api-bot.md b/htsy/references/api-bot.md
similarity index 100%
rename from references/api-bot.md
rename to htsy/references/api-bot.md
diff --git a/references/api-common.md b/htsy/references/api-common.md
similarity index 100%
rename from references/api-common.md
rename to htsy/references/api-common.md
diff --git a/references/api-customer.md b/htsy/references/api-customer.md
similarity index 100%
rename from references/api-customer.md
rename to htsy/references/api-customer.md
diff --git a/references/api-friend.md b/htsy/references/api-friend.md
similarity index 100%
rename from references/api-friend.md
rename to htsy/references/api-friend.md
diff --git a/references/api-group.md b/htsy/references/api-group.md
similarity index 100%
rename from references/api-group.md
rename to htsy/references/api-group.md
diff --git a/references/api-material.md b/htsy/references/api-material.md
similarity index 100%
rename from references/api-material.md
rename to htsy/references/api-material.md
diff --git a/references/cli-install.md b/htsy/references/cli-install.md
similarity index 100%
rename from references/cli-install.md
rename to htsy/references/cli-install.md
diff --git a/references/htsy-api.md b/htsy/references/htsy-api.md
similarity index 100%
rename from references/htsy-api.md
rename to htsy/references/htsy-api.md
diff --git a/llms.txt b/llms.txt
new file mode 100644
index 0000000..49d0178
--- /dev/null
+++ b/llms.txt
@@ -0,0 +1,71 @@
+# htsy-skill instructions for AI agents
+
+Purpose: install the portable agent skill located in this repository's `htsy/` directory.
+
+Important rules:
+- Install only the `htsy/` directory as the skill.
+- Do not install the repository root as a skill.
+- Do not move or rewrite `htsy/SKILL.md` or `htsy/references/*`.
+- This installs the agent skill only. It does not log in to htsy-cli and does not call business APIs.
+- Do not assume the current agent is Codex. Choose the destination for the active agent.
+- If the target already has an `htsy` skill, updating it by replacing that target directory is expected.
+
+Known targets:
+- Claude Code user skill: `~/.claude/skills/htsy`
+- Claude Code project skill: `./.claude/skills/htsy`
+- Codex user skill: `${CODEX_HOME:-$HOME/.codex}/skills/htsy`
+- Other agents that support `SKILL.md` directory skills: use that agent's documented skills directory and install as `<skills-dir>/htsy`.
+
+Choose the install target:
+- If the user is using Claude Code and did not request project-local install, use `--agent claude`.
+- If the user wants the skill checked into the current project for Claude Code, use `--agent claude-project`.
+- If the user is using Codex, use `--agent codex`.
+- If the agent type is different or unclear but its skills directory is known, use `--dest /absolute/path/to/skills/htsy`.
+- If the agent type and skills directory are both unknown, ask the user for the target skills directory.
+
+If this repository is already present locally and `htsy/SKILL.md` exists, run the installer from the repository root.
+
+macOS/Linux examples:
+
+```bash
+bash ./scripts/install-htsy-skill.sh --agent claude
+bash ./scripts/install-htsy-skill.sh --agent claude-project
+bash ./scripts/install-htsy-skill.sh --agent codex
+bash ./scripts/install-htsy-skill.sh --dest /path/to/agent/skills/htsy
+```
+
+Windows PowerShell examples:
+
+```powershell
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Agent claude
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Agent claude-project
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Agent codex
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Dest C:\path\to\agent\skills\htsy
+```
+
+If this repository is not present locally, clone it first:
+
+macOS/Linux:
+
+```bash
+git clone --depth 1 https://git.ikuban.com/server/htsy-skill.git
+cd htsy-skill
+bash ./scripts/install-htsy-skill.sh --agent claude
+```
+
+Windows PowerShell:
+
+```powershell
+git clone --depth 1 https://git.ikuban.com/server/htsy-skill.git
+Set-Location htsy-skill
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Agent claude
+```
+
+Verification after install:
+- Confirm the installed file exists at the target path: `skills/htsy/SKILL.md`.
+- Tell the user to reload or start a new agent session if the current session does not list the skill yet.
+
+When installation fails:
+- If `git clone` fails, ask the user for an accessible checkout or archive.
+- If `CODEX_HOME` is set and installing for Codex, respect it.
+- If the operating system is unknown, ask before choosing commands.
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..7ccfdd8
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,110 @@
+# htsy agent skill
+
+本仓库提供海豚私域 `htsy` 通用 agent skill。真正需要安装到 agent skills 目录的内容只有 [`htsy/`](htsy/) 目录。
+
+安装后，agent 读取到该 skill 时，会按 [`htsy/SKILL.md`](htsy/SKILL.md) 的说明使用 `htsy-cli` 调用海豚私域接口。
+
+## 安装
+
+不同 agent 的 skills 目录不同。常见目标：
+
+- Claude Code 用户级：`~/.claude/skills/htsy`
+- Claude Code 项目级：`./.claude/skills/htsy`
+- Codex 用户级：`${CODEX_HOME:-$HOME/.codex}/skills/htsy`
+- 其他支持 `SKILL.md` 目录格式的 agent：使用该 agent 文档指定的 skills 目录
+
+如果已经 clone 了本仓库，在仓库根目录执行：
+
+```bash
+# Claude Code 用户级
+./scripts/install-htsy-skill.sh --agent claude
+
+# Claude Code 项目级
+./scripts/install-htsy-skill.sh --agent claude-project
+
+# Codex 用户级
+./scripts/install-htsy-skill.sh --agent codex
+
+# 其他 agent，传入完整目标 skill 目录
+./scripts/install-htsy-skill.sh --dest /path/to/agent/skills/htsy
+```
+
+Windows PowerShell：
+
+```powershell
+# Claude Code 用户级
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Agent claude
+
+# Claude Code 项目级
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Agent claude-project
+
+# Codex 用户级
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Agent codex
+
+# 其他 agent，传入完整目标 skill 目录
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Dest C:\path\to\agent\skills\htsy
+```
+
+如果还没有 clone 本仓库：
+
+```bash
+git clone --depth 1 https://git.ikuban.com/server/htsy-skill.git
+cd htsy-skill
+./scripts/install-htsy-skill.sh --agent claude
+```
+
+Windows PowerShell：
+
+```powershell
+git clone --depth 1 https://git.ikuban.com/server/htsy-skill.git
+Set-Location htsy-skill
+PowerShell -ExecutionPolicy Bypass -File .\scripts\install-htsy-skill.ps1 -Agent claude
+```
+
+重新执行安装脚本可更新本地 skill。脚本会替换目标位置的 `htsy` skill 目录。
+
+## 手动安装
+
+也可以手动把仓库里的 `htsy/` 目录复制到目标 agent 的 skills 目录。
+
+Claude Code 用户级：
+
+```text
+~/.claude/skills/htsy
+```
+
+Claude Code 项目级：
+
+```text
+./.claude/skills/htsy
+```
+
+Codex 用户级：
+
+```text
+~/.codex/skills/htsy
+```
+
+Windows Claude Code 用户级：
+
+```text
+%USERPROFILE%\.claude\skills\htsy
+```
+
+Windows Codex 用户级：
+
+```text
+%USERPROFILE%\.codex\skills\htsy
+```
+
+确认目标目录里存在 `SKILL.md`：
+
+```text
+<agent-skills-dir>/htsy/SKILL.md
+```
+
+安装完成后，重新打开或刷新对应 agent 会话，让 skill 列表重新加载。
+
+## 给 agent 的说明
+
+面向 AI/agent 的最短安装指令放在 [`llms.txt`](llms.txt)。如果 agent 正在读取本仓库，请优先读取 `llms.txt`，判断当前 agent 类型后按其中步骤安装 `htsy/`。
diff --git a/scripts/install-htsy-skill.ps1 b/scripts/install-htsy-skill.ps1
new file mode 100644
index 0000000..7434d4c
--- /dev/null
+++ b/scripts/install-htsy-skill.ps1
@@ -0,0 +1,136 @@
+[CmdletBinding()]
+param(
+    [string]$Source,
+    [string]$Dest,
+    [string]$SkillsDir,
+    [string]$Agent = $(if ($env:HTSY_SKILL_AGENT) { $env:HTSY_SKILL_AGENT } else { "" }),
+    [string]$Repo = $(if ($env:HTSY_SKILL_REPO_URL) { $env:HTSY_SKILL_REPO_URL } else { "https://git.ikuban.com/server/htsy-skill.git" })
+)
+
+$ErrorActionPreference = "Stop"
+
+function Resolve-Dest {
+    param(
+        [string]$ExactDest,
+        [string]$ParentSkillsDir,
+        [string]$TargetAgent
+    )
+
+    if ($ExactDest) {
+        return $ExactDest
+    }
+
+    if ($env:HTSY_SKILL_DEST) {
+        return $env:HTSY_SKILL_DEST
+    }
+
+    if (-not $ParentSkillsDir -and $env:AGENT_SKILLS_DIR) {
+        $ParentSkillsDir = $env:AGENT_SKILLS_DIR
+    }
+
+    if ($ParentSkillsDir) {
+        return Join-Path $ParentSkillsDir "htsy"
+    }
+
+    switch ($TargetAgent) {
+        "claude" {
+            $claudeHome = $env:CLAUDE_HOME
+            if (-not $claudeHome) {
+                $claudeHome = Join-Path $HOME ".claude"
+            }
+            return Join-Path (Join-Path $claudeHome "skills") "htsy"
+        }
+        "claude-user" {
+            $claudeHome = $env:CLAUDE_HOME
+            if (-not $claudeHome) {
+                $claudeHome = Join-Path $HOME ".claude"
+            }
+            return Join-Path (Join-Path $claudeHome "skills") "htsy"
+        }
+        "claude-project" {
+            return Join-Path (Join-Path (Join-Path (Get-Location).Path ".claude") "skills") "htsy"
+        }
+        "codex" {
+            $codexHome = $env:CODEX_HOME
+            if (-not $codexHome) {
+                $codexHome = Join-Path $HOME ".codex"
+            }
+            return Join-Path (Join-Path $codexHome "skills") "htsy"
+        }
+        "" {
+            throw "Specify -Agent claude|claude-project|codex, -SkillsDir, or -Dest."
+        }
+        default {
+            throw "Unknown agent: $TargetAgent"
+        }
+    }
+}
+
+function Copy-Skill {
+    param(
+        [Parameter(Mandatory = $true)][string]$From,
+        [Parameter(Mandatory = $true)][string]$To
+    )
+
+    if (-not (Test-Path (Join-Path $From "SKILL.md"))) {
+        throw "Invalid source: $From does not contain SKILL.md"
+    }
+
+    $destParent = Split-Path -Parent $To
+    if (-not (Test-Path $destParent)) {
+        New-Item -ItemType Directory -Force $destParent | Out-Null
+    }
+
+    $tmpDest = Join-Path $destParent (".htsy-install-{0}" -f ([guid]::NewGuid().ToString("N")))
+    New-Item -ItemType Directory -Force $tmpDest | Out-Null
+
+    try {
+        Get-ChildItem -LiteralPath $From -Force | Copy-Item -Destination $tmpDest -Recurse -Force
+
+        if (Test-Path $To) {
+            Remove-Item -Path $To -Recurse -Force
+        }
+
+        Move-Item -Path $tmpDest -Destination $To
+    }
+    catch {
+        if (Test-Path $tmpDest) {
+            Remove-Item -Path $tmpDest -Recurse -Force
+        }
+        throw
+    }
+}
+
+$Dest = Resolve-Dest -ExactDest $Dest -ParentSkillsDir $SkillsDir -TargetAgent $Agent
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+$repoRoot = (Resolve-Path (Join-Path $scriptDir "..")).Path
+$tempRoot = $null
+
+try {
+    if (-not $Source) {
+        $localSkill = Join-Path $repoRoot "htsy"
+        if (Test-Path (Join-Path $localSkill "SKILL.md")) {
+            $Source = $localSkill
+        }
+        else {
+            if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
+                throw "git is required when the local htsy/ directory is unavailable."
+            }
+
+            $tempRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("htsy-skill-{0}" -f ([guid]::NewGuid().ToString("N")))
+            git clone --depth 1 $Repo $tempRoot
+            $Source = Join-Path $tempRoot "htsy"
+        }
+    }
+
+    Copy-Skill -From $Source -To $Dest
+
+    Write-Host "Installed htsy skill to: $Dest"
+    Write-Host "Verify: $(Join-Path $Dest 'SKILL.md')"
+}
+finally {
+    if ($tempRoot -and (Test-Path $tempRoot)) {
+        Remove-Item -Path $tempRoot -Recurse -Force
+    }
+}
diff --git a/scripts/install-htsy-skill.sh b/scripts/install-htsy-skill.sh
new file mode 100755
index 0000000..c3a3b85
--- /dev/null
+++ b/scripts/install-htsy-skill.sh
@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DEFAULT_REPO_URL="https://git.ikuban.com/server/htsy-skill.git"
+REPO_URL="${HTSY_SKILL_REPO_URL:-$DEFAULT_REPO_URL}"
+SOURCE_DIR=""
+DEST_DIR="${HTSY_SKILL_DEST:-}"
+SKILLS_DIR="${AGENT_SKILLS_DIR:-}"
+AGENT="${HTSY_SKILL_AGENT:-}"
+TMP_DIR=""
+TMP_DEST=""
+
+usage() {
+  cat <<'USAGE'
+Install the htsy agent skill.
+
+Usage:
+  scripts/install-htsy-skill.sh --agent claude|claude-project|codex [--source PATH]
+  scripts/install-htsy-skill.sh --dest PATH [--source PATH]
+  scripts/install-htsy-skill.sh --skills-dir PATH [--source PATH]
+
+Options:
+  --source PATH  Path to the htsy skill directory. Defaults to ./htsy when run from this repository.
+  --agent NAME   Install target: claude, claude-project, or codex.
+  --dest PATH    Exact destination skill directory, for example /path/to/skills/htsy.
+  --skills-dir PATH
+                 Parent skills directory. The installer writes PATH/htsy.
+  --repo URL     Repository URL used when ./htsy is not available.
+  -h, --help     Show this help.
+
+Environment:
+  AGENT_SKILLS_DIR      Parent skills directory. The installer writes AGENT_SKILLS_DIR/htsy.
+  CODEX_HOME            Codex home directory when --agent codex is used.
+  CLAUDE_HOME           Claude home directory when --agent claude is used.
+  HTSY_SKILL_AGENT      Default value for --agent.
+  HTSY_SKILL_REPO_URL   Repository URL fallback.
+  HTSY_SKILL_DEST       Destination skill directory.
+USAGE
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --source)
+      SOURCE_DIR="${2:-}"
+      shift 2
+      ;;
+    --dest)
+      DEST_DIR="${2:-}"
+      shift 2
+      ;;
+    --skills-dir)
+      SKILLS_DIR="${2:-}"
+      shift 2
+      ;;
+    --agent)
+      AGENT="${2:-}"
+      shift 2
+      ;;
+    --repo)
+      REPO_URL="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [ -z "$DEST_DIR" ]; then
+  if [ -n "$SKILLS_DIR" ]; then
+    DEST_DIR="$SKILLS_DIR/htsy"
+  else
+    case "$AGENT" in
+      claude|claude-user)
+        DEST_DIR="${CLAUDE_HOME:-$HOME/.claude}/skills/htsy"
+        ;;
+      claude-project)
+        DEST_DIR="$PWD/.claude/skills/htsy"
+        ;;
+      codex)
+        DEST_DIR="${CODEX_HOME:-$HOME/.codex}/skills/htsy"
+        ;;
+      "")
+        echo "Specify --agent claude|claude-project|codex, --skills-dir, or --dest." >&2
+        usage >&2
+        exit 2
+        ;;
+      *)
+        echo "Unknown agent: $AGENT" >&2
+        usage >&2
+        exit 2
+        ;;
+    esac
+  fi
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+cleanup() {
+  if [ -n "$TMP_DEST" ]; then
+    rm -rf "$TMP_DEST"
+  fi
+  if [ -n "$TMP_DIR" ]; then
+    rm -rf "$TMP_DIR"
+  fi
+}
+trap cleanup EXIT
+
+if [ -z "$SOURCE_DIR" ]; then
+  if [ -f "$REPO_ROOT/htsy/SKILL.md" ]; then
+    SOURCE_DIR="$REPO_ROOT/htsy"
+  else
+    if ! command -v git >/dev/null 2>&1; then
+      echo "git is required when the local htsy/ directory is unavailable." >&2
+      exit 1
+    fi
+
+    TMP_DIR="$(mktemp -d)"
+    git clone --depth 1 "$REPO_URL" "$TMP_DIR/htsy-skill"
+    SOURCE_DIR="$TMP_DIR/htsy-skill/htsy"
+  fi
+fi
+
+if [ ! -f "$SOURCE_DIR/SKILL.md" ]; then
+  echo "Invalid source: $SOURCE_DIR does not contain SKILL.md" >&2
+  exit 1
+fi
+
+DEST_PARENT="$(dirname "$DEST_DIR")"
+mkdir -p "$DEST_PARENT"
+TMP_DEST="$DEST_PARENT/.htsy-install.$$"
+rm -rf "$TMP_DEST"
+mkdir -p "$TMP_DEST"
+cp -R "$SOURCE_DIR/." "$TMP_DEST/"
+
+rm -rf "$DEST_DIR"
+mv "$TMP_DEST" "$DEST_DIR"
+TMP_DEST=""
+
+echo "Installed htsy skill to: $DEST_DIR"
+echo "Verify: $DEST_DIR/SKILL.md"