diff --git a/README.md b/README.md
index f4d59b3..bc1965d 100644
--- a/README.md
+++ b/README.md
@@ -177,6 +177,16 @@ CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量
 | `hy3d/config.py` | 配置路径管理 |
 | `hy3d/browser/` | 登录 / 抓包 / 浏览器自动化工具 |
 
+## Claude Code Skill（可选）
+
+`skill/run-hy3d/` 附带一个 Claude Code skill：让 agent 直接驱动 `hy3d`（查配额、文生 3D、下载模型、诊断登录状态与退出码）。安装：
+
+```bash
+./skill/install.sh        # 安装到 ~/.claude/skills/run-hy3d
+```
+
+新会话中可用 `/run-hy3d` 调用，或当描述命中时自动加载。卸载：`rm -rf ~/.claude/skills/run-hy3d`。
+
 ## 相关文档
 
 - [reverse engineering 文档](README_REVERSE_ENGINEERING.md) — 签名算法逆向过程与关键常量
diff --git a/README_CN.md b/README_CN.md
index 66016ca..637edbd 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -177,6 +177,16 @@ CLI 等价写法：`hy3d --cookies /path/to/cookies.txt quota`，或环境变量
 | `hy3d/config.py` | 配置路径管理 |
 | `hy3d/browser/` | 登录 / 抓包 / 浏览器自动化工具 |
 
+## Claude Code Skill（可选）
+
+`skill/run-hy3d/` 附带一个 Claude Code skill：让 agent 直接驱动 `hy3d`（查配额、文生 3D、下载模型、诊断登录状态与退出码）。安装：
+
+```bash
+./skill/install.sh        # 安装到 ~/.claude/skills/run-hy3d
+```
+
+新会话中可用 `/run-hy3d` 调用，或当描述命中时自动加载。卸载：`rm -rf ~/.claude/skills/run-hy3d`。
+
 ## 相关文档
 
 - [逆向工程文档](README_REVERSE_ENGINEERING_CN.md) — 签名算法逆向过程与关键常量
diff --git a/skill/install.sh b/skill/install.sh
new file mode 100755
index 0000000..2579b06
--- /dev/null
+++ b/skill/install.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# 安装 hy3d 的 Claude Code skill 到用户级目录（~/.claude/skills/run-hy3d）
+# 用法: ./skill/install.sh
+set -euo pipefail
+
+SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")/run-hy3d" && pwd)"
+DEST="$HOME/.claude/skills/run-hy3d"
+
+mkdir -p "$(dirname "$DEST")"
+rm -rf "$DEST"
+cp -r "$SRC" "$DEST"
+echo "✓ skill 已安装到 $DEST"
+echo "  新会话中即可用 /run-hy3d；描述命中时自动加载"
\ No newline at end of file
diff --git a/skill/run-hy3d/SKILL.md b/skill/run-hy3d/SKILL.md
new file mode 100644
index 0000000..a3d7484
--- /dev/null
+++ b/skill/run-hy3d/SKILL.md
@@ -0,0 +1,91 @@
+---
+name: run-hy3d
+description: 运行并驱动腾讯混元 3D（hy3d）。当用户要求：跑 hy3d、查混元 3D 配额、列作品、文生 3D / 图生 3D 生成模型、查询生成状态、下载 GLB/OBJ/USDZ 模型，或验证 hy3d 能否工作时使用。
+---
+
+hy3d 是腾讯混元 3D（https://3d.hunyuan.tencent.com/）的非官方 CLI 与 Python 客户端，通过 `pipx install hy3d`（或 `pip install hy3d`）全局安装，**独立于任何仓库工作**。命令入口即 PATH 上的 **`hy3d`**（源码仓库 bin/hy3d shim 是免安装备选，一般不需要）。
+
+## 前置条件
+
+```bash
+hy3d auth status     # 先跑这个——验证安装与登录状态
+# 退出码 0 + "登录有效 ✓" 即一切就绪
+```
+
+若命令不存在（未发布 PyPI，需从仓库安装）：
+```bash
+pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"
+# 或克隆后 pipx install ".[browser]"；纯源码运行见 README 安装节
+```
+
+## Setup
+
+无安装步骤。唯一需要的文件：登录 cookie `~/.config/hy3d/cookies.txt`（2026-08-15 曾登录，可能随时过期，过期按下方"重新登录"处理）。
+
+## Run（agent 路径）
+
+```bash
+hy3d auth status          # 登录体检（最先跑）
+hy3d quota                # 配额（2026-08-15 实测 20/20）
+hy3d list                 # 作品列表（实测 7 个作品）
+hy3d formats <creationsId>
+hy3d download <creationsId> --format glb -o model.glb
+hy3d text "a ceramic teapot" --wait    # 文生 3D（消耗 4 配额）轮询到完成
+# 更多: status/user/count/image/sketch/animate/texture/topo/cancel/share
+#       全部支持 --json；生成命令支持 --wait/--style/--title
+```
+
+**退出码**（agent 分支判断依据，已实测）：
+
+| 码 | 含义 | 处理 |
+|---|---|---|
+| 0 | 成功 | — |
+| 1 | 环境/网络/参数/4xx | 看 stderr |
+| 2 | 认证失败（token 无效/过期） | 重新登录（需人工，见下） |
+| 3 | cookie 缺失 | 重新登录（需人工，见下） |
+
+实测记录（2026-08-15）：`auth status`/`quota`/`list`/`count`/`user`/`formats`/`download`（下载预览图验证过）全部通过；`text --wait` 已验证提交+轮询框架，未跑完整生成（消耗配额）。
+
+## 重新登录（退出码 2/3 时唯一出路）
+
+**必须由人类用户在真实终端**（Claude 的 `!` 前缀 stdin 非交互，`input()` 会 EOF）运行：
+
+```bash
+hy3d-login               # 邮箱验证码登录（browser 扩展）
+```
+
+输邮箱 → 收验证码 → 输验证码，cookie 自动存回 `~/.config/hy3d/cookies.txt`。登录后浏览器进程自动退出，无残留（2026-08-15 验证）。
+
+## Python API（同一安装）
+
+```python
+from hy3d import Hunyuan3DAPIComplete, upload_image
+api = Hunyuan3DAPIComplete()
+print(api.get_quota_info())
+```
+
+## Test（离线自检）
+
+```bash
+python -m hy3d.sign   # 在 pipx venv 内（~/.local/share/pipx/venvs/hy3d/bin/python3）
+# 输出含「派生密钥: Hf6d6KFB3D」即签名算法正确
+```
+
+---
+
+## Gotchas
+
+- **`!` 前缀跑登录必 EOF** —— `input()` 在管道 stdin 上直接 `EOFError`。登录必须真实终端；agent 只能引导用户。
+- **401 两种码都证明签名正确** —— `"code":"20001"`=token 过期（重登）；`"code":"999"`=cookie 无用户。
+- **不存在的 creationsId → HTTP 400 空 body**（CLI 归为退出码 1），不是 JSON 错误。
+- **文生 3D 一次消耗 4 次配额**（`count=4` 固定）；图生 3D 等消耗 1 次。
+- **配置目录 `~/.config/hy3d` 独立于仓库**——卸载重装/删仓库不影响登录态。
+- **generation 类命令（text/image/animate/...）未完整跑通过**——验证到提交与轮询框架；大规模使用前先 `hy3d auth status`。
+
+## Troubleshooting
+
+- **`hy3d auth status` 退出码 2**：token 过期。让人在真实终端跑 `hy3d-login`。
+- **退出码 3**：cookie 缺失。同上，或检查 `HY3D_COOKIES` 是否指向错误路径。
+- **`command not found: hy3d`**：`pipx install "git+https://gitea.akasei.top/KawasakiAkasei/hy3d.git"`（browser 扩展可选，见 README）。
+- **`EOFError`（登录时）**：stdin 非交互，换真实终端。
+- **`401` + 'token无效'**：重登，不是代码 bug。
\ No newline at end of file