@yottameta/yotta-skills 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# 更新日志
+
+## v0.1.0 (2026-08-29)
+
+初始发布：
+
+- 定位：元阁 —— 全家技能一键安装 CLI（「分发与安装」家族，市场主线 M2「全渠道分发」第一步，
+  降低「n 个技能逐个装」门槛）。
+- CLI（bin/yotta-skills.js，零依赖 Node.js 18+）：
+  - `--list` 列出全家技能 + 版本 + 说明（可按技能名过滤）；
+  - `install --agent <name>` / `install --dir <path>` 装全家或指定技能；
+  - `update` 增量更新（补齐缺失 / 升级版本不一致）；
+  - `--dry-run` 预览不联网不改动；`--pin` 锁死清单精确版本；
+  - `--force` / `--skip-scan` / `--npm` / `--python` / `--verify` 等选项。
+- 清单：skills.json 收录 22 个已发布技能（登记表为权威源，2026-08-29 校准；
+  元安全 / 元测 / 元造 / 元守 / 元察 / 元情 / 元钥 / 元链 / 元鉴 等补入）。
+- 机制：逐技能 `npm pack` → 系统 tar 解压 → 元信装前摘要（若可用，仅提示不拦截）→
+  落位 `<dest>/<slug>` → 汇总报告（✔ 成功 / - 跳过 / ✘ 失败，有失败项退出码 1）。
+- 幂等：目标 `<slug>/SKILL.md` frontmatter version 与清单一致即跳过；`update` 只补缺失 /
+  版本不一致。
+- 版本策略：默认 range（`major.x` 取同 major 最新 patch）；`--pin` 锁死可复现。
+- 支持智能体：内置 17 个键名（claude / cursor / codex / gemini / goose / amp / opencode /
+  windsurf / workbuddy / kiro / trae / trae-cn / qwen / comate / codebuddy / kimi / agents）；
+  未收录用 `--dir` 指目录。
+- Windows npm 解析：定位 npm.cmd 同目录 npm-cli.js 用 node 直跑（规避 EINVAL / cmd 引号坑）。
+- 测试：12 用例全绿（--list / 临时目录安装断言 / 幂等 / --pin / update / 异常路径 /
+  元信 scan 集成）+ 全家族联网实测 22/22 安装成功、版本全对齐、幂等复跑 22 跳过。
+- 文档：SKILL.md（中立版）+ references 三件（skill-list 全家清单 / install-flow 内部机制 /
+  tutorial 中文教程）+ README 中英双版。
+- 发布件：LICENSE（MIT）/ NOTICE / banner（1280×640）/ install.sh。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YottaMeta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,13 @@
+# NOTICE — YottaMeta 品牌声明
+
+「YottaMeta」「元阁」「yotta-skills」以及本家族各技能名称（yotta-* 前缀）是 YottaMeta 的品牌与标识。
+
+本软件以 MIT 许可证开源，任何人均可自由使用、修改与分发。若你在其基础上制作派生作品：
+
+1. 不得继续使用 YottaMeta 或本家族名称（yotta-*、元阁 等）作为派生作品的名称；
+2. 不得暗示派生作品由 YottaMeta 官方维护、认可或与之存在关联；
+3. 建议在派生作品中明确声明「与 YottaMeta 官方无关联」。
+
+上游来源致谢：本技能由 YottaMeta 全新实现（零依赖自研 + 中文教学）。全家一键安装的方向参考
+社区 bundle / installer 类技能与 npm 生态思路，无上游代码；本包不包含任何技能本体，技能内容
+均来自各 yotta-* 技能自身的 npm 包。

package/README.md

@@ -0,0 +1,144 @@
+<p align="center"><b>Language</b>: English · <a href="./README.zh-CN.md">中文</a></p>
+
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-skills banner" width="100%" />
+</p>
+
+<h1 align="center">yotta-skills · 元阁 (YuanGe)</h1>
+
+<p align="center">YottaMeta's <b>one-command family installer</b> for Agent skills: one <code>npx</code> line installs all published <code>yotta-*</code> skills (currently <b>22</b>) into any agent or directory.</p>
+<p align="center">List the family, install everything, incrementally update, preview with <code>--dry-run</code>, pin exact versions — idempotent and zero-dependency (Node.js 18+), pure npm ecosystem.</p>
+<p align="center">This package contains <b>no skill bodies</b> — only a manifest, a downloader, a placer and a summary. Each skill still comes from its own npm package.</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-skills"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-skills" /></a>
+  <a href="https://github.com/YottaMeta/yotta-skills"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-skills" /></a>
+  <a href="https://github.com/YottaMeta/yotta-skills/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-skills" /></a>
+  <a href="https://github.com/YottaMeta/yotta-skills"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
+</p>
+
+## What it is
+
+Installing the whole YottaMeta family used to mean running <code>npx</code> for each skill one by one. 元阁 turns it into a single command: it reads a built-in manifest (22 published skills), downloads each from its own npm package, places it into the target skills directory, and prints a summary (success / skipped / failed).
+
+- **List** — see the whole family: slug, Chinese name, package, version and a one-line description.
+- **Install** — install everything (or a subset) into an agent's default user-level directory or any directory.
+- **Update** — incremental update: add missing skills, upgrade version-skewed ones.
+- **Idempotent** — a skill already at the manifest version is skipped; re-running is safe.
+- **Pre-install summary** — if yotta-verify (元信) is available, each skill is scanned first; the verdict is informational only.
+
+Boundaries: it only downloads, places and summarizes — it does **not** develop skill content, does **not** bundle any skill body, and does **not** use <code>-g</code> global installs. It never writes outside the target you specify.
+
+## Quick start
+
+```bash
+# List the whole family (no network, no changes)
+npx -y @yottameta/yotta-skills --list
+
+# Install everything into an agent's default user-level skills dir (recommended)
+npx -y @yottameta/yotta-skills install --agent codex
+
+# Install everything into any directory (each skill lands in <dir>/<slug>)
+npx -y @yottameta/yotta-skills install --dir ~/my-skills
+
+# Install only selected skills
+npx -y @yottameta/yotta-skills install yotta-memory yotta-verify --dir ~/my-skills
+
+# Incrementally update installed skills
+npx -y @yottameta/yotta-skills update --agent codex
+
+# Preview what would be installed (no network, no changes)
+npx -y @yottameta/yotta-skills --dry-run
+```
+
+Requirements: Node.js 18+, npm, and system <code>tar</code> (built into Windows 10+ / macOS / most Linux distributions).
+
+## Commands & options
+
+| Command / option | Description |
+|---|---|
+| `--list` (`-l`) | List the whole family with versions and descriptions; add a skill name to filter |
+| `install --agent <name>` | Install everything into the agent's default user-level skills dir (recommended) |
+| `install --dir <path>` | Install everything into a directory; each skill lands in `<path>/<slug>` |
+| `install <skill>... [--agent <name> \| --dir <path>]` | Install only the given skills |
+| `update [--agent <name> \| --dir <path>]` | Incremental update: add missing, upgrade version-skewed |
+| `--dry-run` | Preview the install / update list; no network, no changes |
+| `--pin` | Lock the exact manifest versions (default: range, latest patch of the same major) |
+| `--force` | Reinstall even when already at the latest version |
+| `--skip-scan` | Skip the yotta-verify pre-install summary (auto-enabled when yotta-verify is installed) |
+| `--npm <path>` | Specify the npm executable |
+| `--python <path>` | Specify the python executable (used for the yotta-verify summary) |
+| `--verify <path>` | Specify the yotta_verify.py path |
+| `-h, --help` / `-v, --version` | Help / version |
+
+Calling `npx -y @yottameta/yotta-skills <skill>` without a subcommand is equivalent to `install <skill>`.
+
+Supported agent keys (17): `claude` `cursor` `codex` `gemini` `goose` `amp` `opencode` `windsurf` `workbuddy` `kiro` `trae` `trae-cn` `qwen` `comate` `codebuddy` `kimi` `agents`. For agents not in the preset list, point `--dir` at their skills directory (`.agents/skills` is not a universal directory).
+
+## Version strategy
+
+- Default `range`: `npm pack <pkg>@<major>.x` — the latest patch of the same major in the manifest, so maintenance releases are picked up automatically.
+- `--pin`: exact manifest versions, fully reproducible.
+- "Already at the latest" is determined by comparing the frontmatter `version` in `<dir>/<slug>/SKILL.md` with the manifest; matching versions are skipped.
+
+## Installation
+
+Pick any of the four methods below; the order is the recommended priority. The package always comes from **npm** (GitHub can be slow without a proxy; npm supports mirrors).
+
+### Method 1: npm one-liner (recommended)
+
+```text
+# Optional China mirror: npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-skills install --agent <agent-name>      # install the whole family to the agent's default user-level skills dir
+npx -y @yottameta/yotta-skills install --dir <your-skills-dir>   # install the whole family to a directory (e.g. ~/.codex/skills)
+```
+
+- `npx` fetches the latest `yotta-skills` automatically, so there is no separate installation step.
+- `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.
+- `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.
+- If the mirror has not synced the new package (404): add `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror cache.
+
+### Method 2: git clone (developers / git available)
+
+```text
+git clone https://github.com/YottaMeta/yotta-skills.git <your-skills-dir>/yotta-skills
+cd <your-skills-dir>/yotta-skills
+node bin/yotta-skills.js --list
+```
+
+### Method 3: GitHub Download ZIP (manual / no git)
+
+On the GitHub repository `YottaMeta/yotta-skills`, click **Code → Download ZIP**, unzip it, then either run `node bin/yotta-skills.js --list` from the folder, or copy the `yotta-skills` folder into the agent's skills directory.
+
+### Method 4: install.sh (multi-agent one-liner script)
+
+```text
+bash install.sh --agent <name>   # install this skill itself to the agent's default user-level directory
+bash install.sh --dir <path>     # install this skill itself to the given directory
+bash install.sh --list           # list agents -> default directories
+```
+
+> Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
+
+## Included skills
+
+The full 22-skill manifest with Chinese names, package names, versions and descriptions is in `references/skill-list.md` (the machine-readable source is `skills.json`). Family coverage: Security & Guardrails (12), Quality & Engineering (4), Memory & Context (3), Writing & Expression (1), Workflow (1), Entry & Guidance (1).
+
+## How it works
+
+For each skill in the manifest: `npm pack <pkg>@<spec>` into a temp directory → `tar -xzf` → optional yotta-verify pre-install summary → replace `<dest>/<slug>` → summary report. Details: `references/install-flow.md`; beginner tutorial (Chinese): `references/tutorial.md`.
+
+## Development & validation
+
+```bash
+# Run the test suite (12 cases) from the skill directory
+npm test
+```
+
+The tests cover `--list`, install into a temp directory with assertions, idempotency, `--pin`, `update`, error paths, and yotta-verify scan integration (with a fake npm).
+
+## License
+
+MIT © YottaMeta — see [LICENSE](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,156 @@
+<p align="center"><b>Language</b>: <a href="./README.md">English</a> · 中文</p>
+
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-skills banner" width="100%" />
+</p>
+
+<h1 align="center">yotta-skills · 元阁 (YuanGe)</h1>
+
+<p align="center">YottaMeta 的<b>全家技能一键安装 CLI</b>：一条 <code>npx</code> 命令把已发布的全部
+<code>yotta-*</code> 技能（当前 <b>22</b> 个）装进指定智能体或目录。</p>
+<p align="center">看清单、装全家、增量更新、<code>--dry-run</code> 预览、<code>--pin</code> 锁版本——
+幂等、零依赖（Node.js 18+）、纯 npm 生态。</p>
+<p align="center">本包<b>不含任何技能本体</b>——只做「清单 + 下载 + 落位 + 汇总」；每个技能仍走各自 npm 包。</p>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a>
+  <a href="https://agentskills.io/"><img alt="Standard: agentskills.io" src="https://img.shields.io/badge/standard-agentskills.io-orange" /></a>
+  <a href="https://www.npmjs.com/package/@yottameta/yotta-skills"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-skills" /></a>
+  <a href="https://github.com/YottaMeta/yotta-skills"><img alt="GitHub stars" src="https://img.shields.io/github/stars/YottaMeta/yotta-skills" /></a>
+  <a href="https://github.com/YottaMeta/yotta-skills/commits/main"><img alt="last commit" src="https://img.shields.io/github/last-commit/YottaMeta/yotta-skills" /></a>
+  <a href="https://github.com/YottaMeta/yotta-skills"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen" /></a>
+</p>
+
+## 这是什么
+
+以前装元阁全家要逐个 <code>npx</code> 跑很多次。元阁把它变成一条命令：读内置清单（22 个已发布技能）、
+逐个从各自 npm 包下载、落位到目标技能目录、打印汇总（成功 / 跳过 / 失败）。
+
+- **看清单**——全家技能一览：slug / 中文名 / 包名 / 版本 / 一句话说明。
+- **安装**——装全家（或指定技能）到智能体默认用户级目录或任意目录。
+- **更新**——增量更新：补齐缺失技能、升级版本不一致的技能。
+- **幂等**——已在清单版本的技能跳过；重复运行安全。
+- **装前摘要**——若装了元信（yotta-verify），先对每个待装技能做一次装前扫描；verdict 仅提示、不拦截。
+
+边界：只做「下载 + 落位 + 汇总」——**不**开发技能内容、**不**内置任何技能本体、**不**用 <code>-g</code>
+全局安装；只在你指定的目标内写文件。
+
+## 快速使用
+
+```bash
+# 列出全家技能（不联网、不改动）
+npx -y @yottameta/yotta-skills --list
+
+# 装全家到指定智能体默认用户级技能目录（推荐）
+npx -y @yottameta/yotta-skills install --agent codex
+
+# 装全家到任意目录（每个技能落在 <dir>/<slug>）
+npx -y @yottameta/yotta-skills install --dir ~/my-skills
+
+# 只装个别技能
+npx -y @yottameta/yotta-skills install yotta-memory yotta-verify --dir ~/my-skills
+
+# 增量更新已装技能
+npx -y @yottameta/yotta-skills update --agent codex
+
+# 预览将安装清单（不联网、不改动）
+npx -y @yottameta/yotta-skills --dry-run
+```
+
+前置：Node.js 18+、npm、系统 tar（Windows 10+ / macOS / 多数 Linux 自带）。
+
+## 命令与选项
+
+| 命令 / 选项 | 作用 |
+|---|---|
+| `--list`（`-l`） | 列出全家技能 + 版本 + 说明；可加技能名过滤 |
+| `install --agent <name>` | 装全家到指定智能体默认用户级技能目录（推荐） |
+| `install --dir <path>` | 装全家到指定目录，每个技能落在 `<path>/<slug>` |
+| `install <skill>... [--agent <name> \| --dir <path>]` | 只装指定的一个或多个技能 |
+| `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失、升级版本不一致的技能 |
+| `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
+| `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
+| `--force` | 已是最新也重新安装 |
+| `--skip-scan` | 跳过元信装前摘要（装了 yotta-verify 时默认自动启用） |
+| `--npm <path>` | 指定 npm 可执行文件 |
+| `--python <path>` | 指定 python 可执行文件（元信摘要用） |
+| `--verify <path>` | 指定 yotta_verify.py 路径 |
+| `-h, --help` / `-v, --version` | 帮助 / 版本 |
+
+不带命令直接给技能名时，等价于 `install <skill>`。
+
+支持 17 个智能体键名：`claude` `cursor` `codex` `gemini` `goose` `amp` `opencode` `windsurf`
+`workbuddy` `kiro` `trae` `trae-cn` `qwen` `comate` `codebuddy` `kimi` `agents`。
+未收录的智能体请用 `--dir` 指到它的技能目录（`.agents/skills` 不是通用目录）。
+
+## 版本策略
+
+- 默认 `range`：`npm pack <pkg>@<major>.x`——取清单同 major 的最新 patch，维护性更新随最新；
+- `--pin`：锁死清单精确版本，完全可复现；
+- 是否「已是最新」由目标 `<dir>/<slug>/SKILL.md` 的 frontmatter `version` 与清单比对，一致即跳过。
+
+## 安装
+
+以下四种方式任选，顺序即推荐优先级；本包一律从 **npm** 获取（GitHub 无代理较慢，npm 支持镜像）。
+
+### 方式一：npm 一行装（推荐）
+
+```text
+# 可选国内加速：npm config set registry https://registry.npmmirror.com
+npx -y @yottameta/yotta-skills install --agent <智能体名称>      # 装全家到指定智能体默认用户级技能目录
+npx -y @yottameta/yotta-skills install --dir <你的技能目录>     # 装全家到指定目录（如 ~/.codex/skills）
+```
+
+- `npx` 会自动拉取最新版 `yotta-skills`，无需单独安装步骤。
+- `--agent <name>` 自动装到该智能体默认用户级目录；`--list` 可查看各智能体默认目录。
+- `--dir <路径>` 装到指定的技能目录；未收录的智能体用 `--dir` 指到它的技能目录。
+- npmmirror 未同步新包（404）：加 `--registry=https://registry.npmjs.org/`（国内需代理），或稍等镜像缓存。
+
+### 方式二：git clone（开发者 / 有 git 环境）
+
+```text
+git clone https://github.com/YottaMeta/yotta-skills.git <你的技能目录>/yotta-skills
+cd <你的技能目录>/yotta-skills
+node bin/yotta-skills.js --list
+```
+
+### 方式三：GitHub 下载压缩包（手动 / 无 git 环境）
+
+在 GitHub 仓库 `YottaMeta/yotta-skills` 点 **Code → Download ZIP**，解压后直接在目录里跑
+`node bin/yotta-skills.js --list`，或把 `yotta-skills` 文件夹放进智能体技能目录。
+
+### 方式四：install.sh（多智能体一键脚本）
+
+```text
+bash install.sh --agent <name>   # 把本技能本身装到指定智能体默认用户级目录
+bash install.sh --dir <path>     # 把本技能本身装到指定目录
+bash install.sh --list           # 列出智能体 -> 默认目录
+```
+
+> 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
+
+## 全家技能清单
+
+22 个技能的 slug / 中文名 / 包名 / 版本 / 说明见 `references/skill-list.md`（机器权威源为
+`skills.json`）。家族分布：安全与护栏（12）/ 质量与工程（4）/ 记忆与上下文（3）/ 写作与表达（1）/
+工作流（1）/ 入口与引导（1）。
+
+## 工作原理
+
+对清单里每个技能：`npm pack <pkg>@<spec>` 到临时目录 → `tar -xzf` 解压 → 可选元信装前摘要 →
+替换 `<dest>/<slug>` → 汇总报告。细节见 `references/install-flow.md`；新手中文教程见
+`references/tutorial.md`。
+
+## 开发与校验
+
+```bash
+# 在技能目录内跑测试（12 个用例）
+npm test
+```
+
+测试覆盖 `--list`、临时目录安装断言、幂等、`--pin`、`update`、异常路径与元信 scan 集成
+（用 fake npm 不联网）。
+
+## 许可证
+
+MIT © YottaMeta —— 见 [LICENSE](./LICENSE)。

package/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: yotta-skills
+version: 0.1.0
+description: 元阁 —— 全家技能一键安装 CLI：一条命令把 YottaMeta 已发布的全部 yotta-* 技能（当前 22 个）装进指定智能体或目录；支持 --list 清单 / install / update / --dry-run 预览 / --pin 锁版本；幂等、零依赖（Node.js 18+）、纯 npm 生态，不内置任何技能本体。触发：需要批量安装或更新元阁全家技能、给某个智能体或目录一次性铺齐 yotta-* 技能、预览安装清单、锁版本安装时；或用户说 元阁/装全家/一次装齐/yotta-skills/install-all/更新全家 等。边界（Do NOT trigger）：只做「清单 + 下载 + 落位 + 汇总」，不含技能本体、不做技能内容开发、不 -g 污染全局；装前摘要仅供参考，安装决策由用户确认。
+license: MIT
+metadata:
+  zh_name: 元阁
+---
+
+# 元阁（yotta-skills）
+
+**全家技能一键安装 CLI**：一条 `npx -y @yottameta/yotta-skills` 把元阁已发布的全部
+`yotta-*` 技能（当前 22 个）装进指定智能体默认目录或任意目录——`--list` 看清单、
+`install` 一次装齐、`update` 增量更新、`--dry-run` 先预览、`--pin` 锁版本。
+
+每个技能仍走各自独立的 npm 包（版本源唯一）；本包只做「清单 + 下载 + 落位 + 汇总」，
+**不内置任何技能本体**，体积极小。运行依赖仅 Node.js 18+ / npm / 系统 tar。
+
+## 何时使用
+
+- 新装一个智能体（如 Codex / Claude Code / Cursor），想一次把元阁全家技能铺到位；
+- 给某个目录或智能体批量安装 / 更新 `yotta-*` 技能；
+- 安装前先预览会装哪些技能、什么版本；
+- 需要锁死清单版本、或强制重装。
+
+**Do NOT trigger**：
+
+- 本工具不做技能内容开发与审查，也不包含任何技能本体；
+- 装前摘要（元信 yotta-verify）仅供参考，不替代人工安装决策；
+- 不使用 `-g` 全局安装，不向未指定的位置写文件；
+- 网络不可用时安装会失败并给出明确错误，不伪造结果。
+
+## 快速使用
+
+```bash
+# 列出全家技能 + 版本 + 说明
+npx -y @yottameta/yotta-skills --list
+
+# 装全家到指定智能体默认用户级目录（推荐）
+npx -y @yottameta/yotta-skills install --agent codex
+
+# 装全家到任意目录（每个技能落在 <dir>/<slug>）
+npx -y @yottameta/yotta-skills install --dir ~/my-skills
+
+# 只装单个 / 多个技能
+npx -y @yottameta/yotta-skills install yotta-memory yotta-verify --dir ~/my-skills
+
+# 增量更新已装技能（补齐缺失 / 版本不一致）
+npx -y @yottameta/yotta-skills update --agent codex
+
+# 预览将安装清单（不联网、不改动）
+npx -y @yottameta/yotta-skills --dry-run
+```
+
+## 命令与选项
+
+| 命令 / 选项 | 作用 |
+|---|---|
+| `--list`（`-l`） | 列出全家技能 + 版本 + 说明；可加技能名过滤 |
+| `install --agent <name>` | 装全家到指定智能体默认用户级目录（推荐） |
+| `install --dir <path>` | 装全家到指定目录，每个技能落在 `<path>/<slug>` |
+| `install <skill>... [--agent <name> \| --dir <path>]` | 只装指定的一个或多个技能 |
+| `update [--agent <name> \| --dir <path>]` | 增量更新：补齐缺失技能、升级版本不一致的技能 |
+| `--dry-run` | 预览将执行的安装 / 更新清单；不联网、不改动 |
+| `--pin` | 锁死清单精确版本（默认 range：跟随同 major 最新 patch） |
+| `--force` | 已是最新也重新安装 |
+| `--skip-scan` | 跳过元信装前摘要（装了 yotta-verify 时默认自动启用） |
+| `--npm <path>` | 指定 npm 可执行文件 |
+| `--python <path>` | 指定 python 可执行文件（元信摘要用） |
+| `--verify <path>` | 指定 yotta_verify.py 路径 |
+| `-h, --help` / `-v, --version` | 帮助 / 版本 |
+
+不带命令直接给技能名时，等价于 `install <skill>`。
+
+## 版本策略
+
+- 默认 `range`：按清单 `major.x` 取 npm 最新 patch（如 `0.x`），维护性更新随最新；
+- `--pin`：锁死清单中的精确版本，完全可复现；
+- 是否「已是最新」由目标目录 `<slug>/SKILL.md` 的 frontmatter `version` 与清单比对，
+  一致即跳过（幂等）。
+
+## 元信装前摘要
+
+安装时若检测到元信（yotta-verify）引擎，会对每个待装技能先跑一次装前摘要并打印 verdict
+与计数——仅提示、不拦截；verdict 为 DO NOT INSTALL 时会额外提示人工复核。
+引擎查找顺序：`--verify` 指定路径 → 环境变量 `YOTTA_SKILLS_VERIFY` → 目标目录下已装的
+`yotta-verify/scripts/yotta_verify.py`。可用 `--skip-scan` 关闭。
+
+## 支持智能体
+
+17 个内置键名：`claude` `cursor` `codex` `gemini` `goose` `amp` `opencode` `windsurf`
+`workbuddy` `kiro` `trae` `trae-cn` `qwen` `comate` `codebuddy` `kimi` `agents`。
+未收录的智能体请用 `--dir` 指定其技能目录（`.agents/skills` 不是通用目录）。
+
+## 环境变量
+
+| 变量 | 作用 |
+|---|---|
+| `YOTTA_SKILLS_NPM` | 指定 npm 可执行文件（同 `--npm`） |
+| `YOTTA_SKILLS_NPM_FLAGS` | 追加传给 `npm pack` 的参数（按空白拆分，如 `--registry=...`） |
+| `YOTTA_SKILLS_PYTHON` | 指定 python 可执行文件（元信摘要用，同 `--python`） |
+| `YOTTA_SKILLS_VERIFY` | 指定 yotta_verify.py 路径（同 `--verify`） |
+| `YOTTA_SKILLS_MANIFEST` | 指定技能清单 JSON 路径（默认随包 skills.json） |
+
+## 常见问题
+
+- **npmmirror 全新包 404**：镜像同步有延迟，通过 `YOTTA_SKILLS_NPM_FLAGS` 追加
+  `--registry=https://registry.npmjs.org/`（国内需代理）或等待镜像缓存后重试。
+- **未收录智能体**：`--agent <name>` 报未收录时，改用 `--dir` 指到它的技能目录。
+- **Windows 下 npm 报错**：CLI 已内置 npm-cli.js 解析，无需额外处理；如需覆盖用 `--npm`。
+- **某技能安装失败**：汇总报告会列出失败原因，可单装该技能排查。
+
+## 参考
+
+- 全家技能清单（人工可读版）：`references/skill-list.md`（机器权威源为 `skills.json`）。
+- 内部机制：`references/install-flow.md`。
+- 新手中文教程：`references/tutorial.md`。