@yottameta/yotta-lesson 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# 更新日志
+
+## v0.1.1 (2026-10-01)
+
+- 文档修正：家族协同 / 边界 / 版权说明中元题的引用改为已发布实际口径（元题 = 按双向细目表从学校自备题库组卷 + 试卷结构校验，不生成题面，题面由题库提供）；同步更新中英 README 与 `references/copyright.md`。
+- 行为零变更：内核 / CLI / 退出码 / 门禁契约不变。
+- 新增文档契约回归：家族引用不得回退为「规划中 / (planned)」。
+
+## v0.1.0 (2026-09-24)
+
+初始发布：
+
+- 定位：元案 —— 本地、确定性的教案骨架与覆盖校验技能（零依赖，Python 3.8+ 标准库）；不联网、不调用模型、不内置教材与题目原文。
+- 输入：课标映射包 JSON（课题 / 知识点 / 重难点 / 易错点 / 课标来源）+ 可选结构配置 JSON（每课时分钟、环节与比例、必填环节、环节关键词）。
+- 能力：教案骨架生成（学习目标带来源、重难点与易错点、五环节 + 分钟级时间分配、板书与评价清单）、覆盖检查（`knowledge_missing` / `stage_missing` / `source_missing` / `time_missing` / `minutes_mismatch`）、映射包 list / show / validate。
+- 时间分配：最大余数法，各环节分钟合计精确等于「课时 × 每课时分钟」。
+- CLI：`plan` / `check` / `map` / `template`；退出码 0 / 1 / 2 / 3 / 4；支持 `--periods`、`--format md|json`、`--out`、`--stdin`、`--gate findings=<n>`。
+- 测试：55 项，Python 3.8.20 / 3.11.9 / 3.13.15 全绿；合成样例（完整教案 / 缺口教案）端到端通过。
+- 文档：SKILL.md + references（map-format / plan-format / copyright）+ 中英 README + 四方式安装 + banner。

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,12 @@
+# NOTICE — YottaMeta 品牌声明
+
+「YottaMeta」「元案」「yotta-lesson」以及本家族各技能名称（yotta-* 前缀）是 YottaMeta 的品牌与标识。
+
+本软件以 MIT 许可证开源，任何人均可自由使用、修改与分发。若你在其基础上制作派生作品：
+
+1. 不得继续使用 YottaMeta 或本家族名称（yotta-*、元案 等）作为派生作品的名称；
+2. 不得暗示派生作品由 YottaMeta 官方维护、认可或与之存在关联；
+3. 建议在派生作品中明确声明「与 YottaMeta 官方无关联」。
+
+本技能由 YottaMeta 全新实现（零依赖自研 + 中文教学）；不内置教材、课标与题目原文，
+映射包只记录结构性元数据，示例中的课标来源为占位样例。

package/README.md

@@ -0,0 +1,156 @@
+<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-lesson banner" width="100%" />
+</p>
+
+<h1 align="center">yotta-lesson · 元案 (YuanAn)</h1>
+
+<p align="center">YottaMeta's <b>deterministic lesson-plan skeleton and coverage checker</b>: turn a curriculum
+map into a lesson skeleton whose stage times add up exactly and whose objectives each carry a
+<b>curriculum-standard source</b>, then check an existing lesson plan for <b>missing knowledge points,
+missing stages, missing citations and time mismatches</b>.</p>
+<p align="center">Pure Python 3.8+ standard library, zero dependencies; local-only — no network, no model
+calls, no textbook or exam text bundled.</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-lesson"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-lesson" /></a>
+</p>
+
+## What it is
+
+yotta-lesson reads a curriculum map (lesson id, knowledge points, key points, difficulties,
+misconceptions, standard reference) plus an optional structure config, then produces:
+
+- a lesson-plan skeleton — objectives with sources, key/difficult points, misconception reminders,
+  five stages with minute-level time allocation, board-work and evaluation checklist;
+- a coverage check — run against an existing lesson text to list structural gaps with reasons.
+
+It is a preparation aid. It does not write objectives on the teacher's behalf, does not generate
+exercise content, and does not ship any textbook or exam material.
+
+## Core value
+
+- **Exact time allocation** — largest-remainder allocation, so stage minutes always sum to
+  `periods × minutes_per_period`.
+- **Traceable objectives** — every objective carries the `standard` reference from the map.
+- **Deterministic checks** — the same lesson text, map and config produce the same gap list.
+- **Local and zero-dependency** — Python 3.8+ standard library; no network, no model, no upload.
+- **Metadata only** — maps hold structural metadata, never textbook or question text.
+
+## Quick start
+
+Windows uses `python`, Linux / macOS use `python3`.
+
+```bash
+# 1. Create templates (curriculum map + structure config)
+python3 scripts/yotta_lesson.py template --output-dir ./lesson-template
+
+# 2. Build a lesson skeleton
+python3 scripts/yotta_lesson.py plan --map lesson-map.json --lesson L1
+
+# 3. Two-period variant as JSON
+python3 scripts/yotta_lesson.py plan --map lesson-map.json --lesson L1 --periods 2 --format json
+
+# 4. Check an existing lesson plan; fail CI when any gap appears
+python3 scripts/yotta_lesson.py check --plan plan.md --map lesson-map.json --lesson L1 --gate findings=1
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `plan --map <file> --lesson <id>` | Build a lesson-plan skeleton |
+| `plan --periods <n>` | Override the period count from the map |
+| `plan --format md\|json` | Markdown (default) or JSON output |
+| `check --plan <file>` | Check an existing lesson text for structural gaps |
+| `check --stdin` | Read the lesson text from standard input |
+| `check --gate findings=<n>` | Exit code 1 when the gap count reaches `n` |
+| `map list / show / validate` | Inspect or validate the curriculum map |
+| `template --output-dir <dir>` | Write starter map and structure config |
+| `--version` | Print the engine version |
+
+Exit codes: `0` ok ｜ `1` gate triggered ｜ `2` input error ｜ `3` map / config error ｜ `4` runtime error.
+
+## Curriculum map
+
+```json
+{
+  "schema_version": "1.0",
+  "subject": "数学",
+  "grade": "七年级上",
+  "lessons": [
+    {
+      "id": "L1",
+      "title": "认识一元一次方程",
+      "periods": 1,
+      "knowledge": ["一元一次方程的定义", "方程的解"],
+      "key_points": ["一元一次方程的定义"],
+      "difficulties": ["由实际问题抽象出方程"],
+      "misconceptions": ["把含未知数的式子都当方程"],
+      "standard": "义务教育数学课程标准（2022 年版）· 方程与不等式"
+    }
+  ]
+}
+```
+
+Full field list and error table: [references/map-format.md](references/map-format.md).
+
+## Gap kinds
+
+`knowledge_missing`, `stage_missing`, `source_missing`, `time_missing`, `minutes_mismatch` —
+definitions, report contract and exit codes: [references/plan-format.md](references/plan-format.md).
+
+## Copyright and boundaries
+
+- Maps store structural metadata only; no textbook, curriculum or exam text is bundled;
+- `standard` is a citation label for traceability, not an interpretation of the curriculum;
+- Output is a preparation aid — the teacher owns the final lesson design.
+
+Details: [references/copyright.md](references/copyright.md).
+
+## Installation
+
+### Option 1 — npx (recommended)
+
+```bash
+npx -y @yottameta/yotta-lesson --agent codex     # or: --agent claude | cursor | gemini | opencode ...
+npx -y @yottameta/yotta-lesson --dir <skills-dir>
+```
+
+### Option 2 — git clone
+
+```bash
+git clone https://github.com/YottaMeta/yotta-lesson.git <skills-dir>/yotta-lesson
+```
+
+### Option 3 — Download ZIP
+
+Download ZIP from https://github.com/YottaMeta/yotta-lesson and extract it into your agent's skills directory.
+
+### Option 4 — install.sh
+
+```bash
+bash install.sh --list
+bash install.sh --agent codex
+bash install.sh --dir <skills-dir>
+```
+
+## Works with
+
+- **yotta-mirror** — feed learning diagnostics back into the next lesson's focus;
+- **yotta-item** — assemble papers from a local item bank and run deterministic paper-structure checks (no item-text generation);
+- **yotta-present** — render the skeleton in a consistent, copyable layout;
+- **yotta-humanize** — natural-language polish for teacher-facing narratives;
+- **yotta-memory** — store map versions and skeleton summaries on request.
+
+## Requirements
+
+- Python 3.8+ (standard library only)
+- UTF-8 encoded JSON map and UTF-8 lesson text; no extra packages, no database, no service
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/README.zh-CN.md

@@ -0,0 +1,148 @@
+<p align="center"><b>语言</b>: 中文 · <a href="./README.md">English</a></p>
+
+<p align="center">
+  <img src="assets/banner.png" alt="yotta-lesson banner" width="100%" />
+</p>
+
+<h1 align="center">元案 yotta-lesson · 教案 / 学案</h1>
+
+<p align="center">YottaMeta 的<b>确定性教案骨架与覆盖校验技能</b>：把课标映射包变成教案骨架——
+环节时间精确到分钟、合计可校验，学习目标逐条带<b>课标来源</b>；再用一次确定性检查回答
+<b>「知识点、环节、来源、时间都齐了吗」</b>。</p>
+<p align="center">零依赖（Python 3.8+ 标准库），本地运行：不联网、不调用模型、不内置教材与题目原文。</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-lesson"><img alt="npm package" src="https://img.shields.io/npm/v/@yottameta/yotta-lesson" /></a>
+</p>
+
+## 这是什么
+
+元案读取课标映射包（课题 id、知识点、重难点、易错点、课标来源）与可选的结构配置，产出两样东西：
+
+- **教案骨架**：学习目标（带来源）、重难点与易错点、五环节 + 分钟级时间分配、板书与评价清单；
+- **覆盖检查**：对已有教案文本列出结构性缺口（未覆盖知识点、缺环节、缺来源、未标时间、合计时间不一致）。
+
+它是备课辅助：不替教师写教学目标、不生成题目内容、不内置教材与题目原文。
+
+## 核心价值
+
+- **时间精确**：最大余数法分配，各环节分钟合计恒等于「课时 × 每课时分钟」；
+- **来源可追**：每条学习目标都带映射包中的 `standard`；
+- **确定性检查**：同一份教案、映射包与配置，得到同一份缺口清单；
+- **本地零依赖**：Python 3.8+ 标准库，不联网、不调用模型、不上传教案；
+- **只存结构性元数据**：映射包不含教材正文与题目原文。
+
+## 快速开始
+
+Windows 使用 `python`，Linux / macOS 使用 `python3`。
+
+```bash
+# 1. 生成模板（映射包 + 结构配置）
+python3 scripts/yotta_lesson.py template --output-dir ./lesson-template
+
+# 2. 生成教案骨架
+python3 scripts/yotta_lesson.py plan --map lesson-map.json --lesson L1
+
+# 3. 两课时版本，输出 JSON
+python3 scripts/yotta_lesson.py plan --map lesson-map.json --lesson L1 --periods 2 --format json
+
+# 4. 检查已有教案，缺口 ≥ 1 时让 CI 失败
+python3 scripts/yotta_lesson.py check --plan plan.md --map lesson-map.json --lesson L1 --gate findings=1
+```
+
+## 命令一览
+
+| 命令 | 说明 |
+|---|---|
+| `plan --map <文件> --lesson <id>` | 生成教案骨架 |
+| `plan --periods <n>` | 覆盖映射包中的课时数 |
+| `plan --format md\|json` | 输出格式：Markdown（默认）或 JSON |
+| `check --plan <文件>` | 检查已有教案的结构性缺口 |
+| `check --stdin` | 从标准输入读取教案文本 |
+| `check --gate findings=<n>` | 缺口数量达到 n 时退出码 1 |
+| `map list / show / validate` | 映射包列表 / 详情 / 校验 |
+| `template --output-dir <目录>` | 生成映射包与结构配置模板 |
+| `--version` | 打印引擎版本 |
+
+退出码：`0` 正常 ｜ `1` 触发闸门 ｜ `2` 输入错误 ｜ `3` 映射或配置错误 ｜ `4` 运行时错误。
+
+## 映射包示例
+
+```json
+{
+  "schema_version": "1.0",
+  "subject": "数学",
+  "grade": "七年级上",
+  "lessons": [
+    {
+      "id": "L1",
+      "title": "认识一元一次方程",
+      "periods": 1,
+      "knowledge": ["一元一次方程的定义", "方程的解"],
+      "misconceptions": ["把含未知数的式子都当方程"],
+      "standard": "义务教育数学课程标准（2022 年版）· 方程与不等式"
+    }
+  ]
+}
+```
+
+完整字段与报错对照见 [references/map-format.md](references/map-format.md)。
+
+## 缺口类型
+
+`knowledge_missing`、`stage_missing`、`source_missing`、`time_missing`、`minutes_mismatch`——
+定义、报告契约与退出码见 [references/plan-format.md](references/plan-format.md)。
+
+## 版权与边界
+
+- 映射包只存结构性元数据，不内置教材、课标与题目原文；
+- `standard` 是引用标注（用于可追溯），不代表本技能对课标作出解释；
+- 输出为备课辅助，教学设计的最终决定由教师负责。
+
+细节见 [references/copyright.md](references/copyright.md)。
+
+## 安装
+
+### 方式一 — npx 一行装（推荐）
+
+```bash
+npx -y @yottameta/yotta-lesson --agent codex     # 亦可 --agent claude | cursor | gemini | opencode ...
+npx -y @yottameta/yotta-lesson --dir <技能目录>
+```
+
+### 方式二 — git clone
+
+```bash
+git clone https://github.com/YottaMeta/yotta-lesson.git <技能目录>/yotta-lesson
+```
+
+### 方式三 — 下载 ZIP
+
+在 https://github.com/YottaMeta/yotta-lesson 页面点 Code → Download ZIP，解压到智能体的技能目录。
+
+### 方式四 — install.sh
+
+```bash
+bash install.sh --list
+bash install.sh --agent codex
+bash install.sh --dir <技能目录>
+```
+
+## 与家族技能协同
+
+- **元镜 yotta-mirror**：用学情数据反哺下一轮备课的薄弱点；
+- **元题 yotta-item**：按双向细目表从学校自备题库组卷、并做试卷结构校验（不生成题面）；
+- **元呈 yotta-present**：把教案骨架渲染成统一格式；
+- **元真 yotta-humanize**：教师-facing 叙述文字去 AI 味；
+- **元忆 yotta-memory**：按需保存映射包版本与骨架摘要。
+
+## 运行要求
+
+- Python 3.8+（仅标准库）
+- UTF-8 的 JSON 映射包与教案文本；不需要额外依赖、数据库或服务
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE) 与 [NOTICE](NOTICE)。

package/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: yotta-lesson
+version: 0.1.1
+description: 元案 —— 本地、确定性的教案骨架与覆盖校验技能：按版本化课标映射包（课题 / 知识点 / 重难点 / 易错点 / 课标来源）生成教案骨架，环节时间按课时精确分配（合计 = 课时 × 每课时分钟），学习目标逐条标注课标来源；`check` 子命令对已有教案文本做确定性缺口检查（未覆盖知识点、缺必填环节、缺课标来源、未标时间、合计时间不一致），输出带证据的 Markdown / JSON 清单，支持 `--gate findings=<n>` CI 闸门；零依赖 Python 3.8+，核心不联网、不调用模型、不含教材与题目原文。触发：用户要写教案 / 学案骨架、按课标核对教案结构、检查教案是否覆盖知识点与环节、把教案结构检查接入自动化流程时。边界：只生成结构性骨架与缺口清单，不生成题目内容、不生成学生评语、不替代教师的教学设计判断；不联网、不上传教案与校本映射；不内置教材版权原文，课标引用以官方文本为准。
+license: MIT
+---
+
+# 元案（yotta-lesson）
+
+本地、确定性的教案骨架与覆盖校验技能。元案把「课标映射包」变成可复算的教案骨架，
+并把「这节课的知识点、环节、来源、时间齐了吗」变成一份确定性缺口清单。
+
+可信契约：
+
+- 教案骨架来自映射包与结构配置，同一输入得到同一结果（仅生成时间不同）；
+- 时间分配精确到分钟且合计可校验（课时 × 每课时分钟）；
+- 每条学习目标都带课标来源；缺口清单给出具体原因与关键词；
+- 核心路径不联网、不调用模型，教案与映射包只在本机流转。
+
+## 何时使用
+
+- 按学校自备的课标 / 单元映射，快速起一份结构完整的教案骨架；
+- 用 `check` 核对已有教案：知识点是否都覆盖、必填环节是否齐全、是否标了来源与时间；
+- 教研组统一教案结构（同一映射包 + 同一结构配置 = 同一套骨架口径）；
+- 把教案结构检查接入批处理或 CI（`--gate findings=<n>`）。
+
+**Do NOT trigger**：
+
+- 不生成题目与学案题目内容（组卷属元题，题面由学校题库提供），不生成学生评语；
+- 不替代教师的教学设计判断：骨架与清单是备课辅助，最终设计由教师定稿；
+- 不联网、不调用模型、不上传教案与校本映射；
+- 不内置教材与课标原文，只记录结构性元数据；引用请以官方文本为准。
+
+## 快速使用
+
+```bash
+# 生成映射包与结构配置模板
+python3 scripts/yotta_lesson.py template --output-dir ./lesson-template
+
+# 生成教案骨架（Markdown）
+python3 scripts/yotta_lesson.py plan --map lesson-map.json --lesson L1
+
+# 两课时版本 + JSON 输出
+python3 scripts/yotta_lesson.py plan --map lesson-map.json --lesson L1 --periods 2 --format json
+
+# 检查已有教案的覆盖缺口，并在缺口 ≥ 1 时让 CI 失败
+python3 scripts/yotta_lesson.py check --plan plan.md --map lesson-map.json --lesson L1 --gate findings=1
+
+# 映射包操作
+python3 scripts/yotta_lesson.py map validate --map lesson-map.json
+python3 scripts/yotta_lesson.py map list --map lesson-map.json
+```
+
+退出码：`0` 正常 ｜ `1` 触发 `--gate` ｜ `2` 输入错误 ｜ `3` 映射或配置错误 ｜ `4` 运行时错误。
+
+## 输入与输出
+
+- **课标映射包**：JSON，逐课题声明 `id` / `title` / `periods` / `knowledge` / `key_points` / `difficulties` / `misconceptions` / `standard`（课标来源，必填）；
+- **结构配置**（可选）：`minutes_per_period`、`stages`（环节与比例）、`required_stages`、`check_keywords`；
+- **输出**：教案骨架 Markdown + JSON（`schema_version 1.0`，含 `objectives` / `stages` / `checklist` / `findings` / `sources` / `disclaimer`）；
+- **缺口检查**：`knowledge_missing` / `stage_missing` / `source_missing` / `time_missing` / `minutes_mismatch`。
+
+字段规范见 `references/map-format.md`；报告契约见 `references/plan-format.md`。
+
+## 版权与边界
+
+- 映射包只存结构性元数据（课题 / 知识点 / 课标条目标识），不存教材正文与题目原文；
+- 课标引用以官方文本为准，本技能不做课标解读；
+- 输出为备课辅助，不用于教学评价结论。
+
+详见 `references/copyright.md`。
+
+## 家族协同
+
+- **元镜 yotta-mirror**：用学情数据反哺下一轮备课的薄弱点；
+- **元题 yotta-item**：按双向细目表从学校自备题库组卷、并做试卷结构校验（不生成题面）；
+- **元呈 yotta-present**：把教案骨架渲染成统一格式；
+- **元真 yotta-humanize**：教师-facing 叙述文字去 AI 味；
+- **元忆 yotta-memory**：按需保存映射包版本与教案骨架摘要。
+
+## 渐进披露
+
+- 映射包与结构配置：`references/map-format.md`
+- 骨架 / 检查报告契约与退出码：`references/plan-format.md`
+- 版权与使用边界：`references/copyright.md`
+
+按需读取，不必每次全读。

package/bin/install.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * yotta-lesson 跨平台安装器（YottaSkills）
+ * 用法:
+ *   npx -y @yottameta/yotta-lesson --agent <name>  # 按智能体默认用户级目录安装（推荐）
+ *   npx -y @yottameta/yotta-lesson --dir PATH      # 装到指定目录（用户改了目录的智能体）
+ *   npx -y @yottameta/yotta-lesson -g              # 安装到全部已知智能体用户级目录
+ *   npx -y @yottameta/yotta-lesson                 # 安装到检测到的项目级目录
+ *   npx -y @yottameta/yotta-lesson --list          # 列出智能体 -> 默认目录
+ */
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'yotta-lesson';
+const PKG_ROOT = path.join(__dirname, '..');
+
+// 智能体 -> 用户级默认技能目录（dirs 按优先级排列；--agent 装到第一个）
+// 依据官方文档：.agents/skills 并非通用目录，被 OpenCode / Cursor / Cline / Amp /
+// Kimi / Gemini CLI / GitHub Copilot 等读取；Claude Code 与 Codex 默认不读 .agents。
+const AGENT_DIRS = {
+  claude:    { label: 'Claude Code',      dirs: ['.claude/skills'] },
+  cursor:    { label: 'Cursor',           dirs: ['.cursor/skills', '.agents/skills'] },
+  codex:     { label: 'Codex',            dirs: ['.codex/skills'] }, // 特判：$CODEX_HOME/skills
+  gemini:    { label: 'Gemini CLI',       dirs: ['.gemini/skills', '.agents/skills'] },
+  goose:     { label: 'Goose',            dirs: ['.config/goose/skills', '.agents/skills'] },
+  amp:       { label: 'Amp',              dirs: ['.config/agents/skills', '.agents/skills'] },
+  opencode:  { label: 'OpenCode',         dirs: ['.config/opencode/skills'] }, // 特判：$XDG_CONFIG_HOME
+  windsurf:  { label: 'Windsurf',         dirs: ['.codeium/windsurf/skills'] },
+  workbuddy: { label: 'WorkBuddy',        dirs: ['.workbuddy/skills'] },
+  kiro:      { label: 'Kiro',             dirs: ['.kiro/skills'] },
+  trae:      { label: 'Trae Code CLI',    dirs: ['.traecli/skills'] },
+  'trae-cn': { label: 'Trae IDE（国内）',  dirs: ['.trae-cn/skills'] },
+  qwen:      { label: 'Qwen Code',        dirs: ['.qwen/skills'] },
+  comate:    { label: 'Comate 文心快码',   dirs: ['.comate/skills'] },
+  codebuddy: { label: 'CodeBuddy Code',   dirs: ['.codebuddy/skills'] },
+  kimi:      { label: 'Kimi Code CLI',    dirs: ['.kimi/skills'] },
+  agents:    { label: '通用 AGENTS.md',    dirs: ['.agents/skills'] },
+};
+
+// Codex 用户级目录特判：优先 $CODEX_HOME/skills，否则 ~/.codex/skills
+function codexUserDir() {
+  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  return path.join(base, 'skills');
+}
+
+// OpenCode 用户级目录特判：优先 $XDG_CONFIG_HOME/opencode/skills，否则 ~/.config/opencode/skills
+function opencodeUserDir() {
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'opencode', 'skills');
+}
+
+function resolveUserDir(rel) {
+  if (rel === '.codex/skills') return codexUserDir();
+  if (rel === '.config/opencode/skills') return opencodeUserDir();
+  return path.join(os.homedir(), rel);
+}
+
+function installTo(dest) {
+  const target = path.join(dest, SKILL_NAME);
+  fs.mkdirSync(target, { recursive: true });
+  copyDir(PKG_ROOT, target, new Set(['package.json', 'bin', 'node_modules', '.git']));
+  console.log('installed -> ' + target);
+}
+
+function copyDir(src, dst, skip) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(d, { recursive: true });
+      copyDir(s, d, skip);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function displayDir(rel) {
+  if (process.platform === 'win32') return '%USERPROFILE%\\' + rel.replace(/\//g, '\\');
+  return '~/' + rel;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const isGlobal = args.includes('-g') || args.includes('--global');
+  const list = args.includes('--list') || args.includes('-l');
+  let explicitDir = null;
+  const di = args.indexOf('--dir');
+  if (di !== -1 && args[di + 1]) explicitDir = args[di + 1];
+  let agent = null;
+  const ai = args.indexOf('--agent');
+  if (ai !== -1 && args[ai + 1]) agent = String(args[ai + 1]).toLowerCase();
+
+  if (list) {
+    console.log('智能体 -> 默认技能目录（--agent <name> 装到第一个，用户级）:');
+    for (const [key, v] of Object.entries(AGENT_DIRS)) {
+      const resolved = v.dirs.map(displayDir);
+      console.log('  ' + key.padEnd(10) + v.label.padEnd(18) + resolved.join('、'));
+    }
+    console.log('\n说明：Windows 用 %USERPROFILE%，Linux/macOS 用 ~；仅收录有官方默认目录的智能体。');
+    console.log('改了目录的请用 --dir <路径>，不要依赖默认位置；若设置了 CODEX_HOME / XDG_CONFIG_HOME，安装自动以该变量为准。');
+    return;
+  }
+
+  if (explicitDir) { installTo(explicitDir); return; }
+
+  if (agent) {
+    const info = AGENT_DIRS[agent];
+    if (!info) {
+      console.log('未收录智能体: ' + agent + '。请用 --dir <路径> 指定技能目录。');
+      console.log('可用: ' + Object.keys(AGENT_DIRS).join(', '));
+      return;
+    }
+    installTo(resolveUserDir(info.dirs[0]));
+    console.log('完成。');
+    return;
+  }
+
+  if (isGlobal) {
+    const seen = new Set();
+    for (const v of Object.values(AGENT_DIRS)) {
+      for (const d of v.dirs) {
+        if (seen.has(d)) continue;
+        seen.add(d);
+        installTo(resolveUserDir(d));
+      }
+    }
+    console.log('完成。');
+    return;
+  }
+
+  const PROJECT_DIRS = [
+    '.claude/skills',
+    '.cursor/skills',
+    '.codex/skills',
+    '.config/goose/skills',
+    '.config/agents/skills',
+    '.opencode/skills',
+    '.codeium/windsurf/skills',
+    '.workbuddy/skills',
+    '.kiro/skills',
+    '.traecli/skills',
+    '.gemini/skills',
+    '.trae-cn/skills',
+    '.qwen/skills',
+    '.comate/skills',
+    '.codebuddy/skills',
+    '.kimi/skills',
+    '.agents/skills',
+  ];
+  let installedAny = false;
+  for (const d of PROJECT_DIRS) {
+    if (fs.existsSync(d)) { installTo(d); installedAny = true; }
+  }
+  if (!installedAny) {
+    console.log('未检测到项目级智能体目录。可手动复制，或用 --agent <name> / -g 装到用户级。');
+  }
+}
+
+main();