master-skill 0.12.11 → 0.12.12

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "master-skill",
       "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传 plus compare, debate, and curriculum meta-skills.",
-      "version": "0.12.11",
+      "version": "0.12.12",
       "source": "./",
       "author": {
         "name": "xr843",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "master-skill",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传 plus compare, debate, and curriculum meta-skills.",
-  "version": "0.12.11",
+  "version": "0.12.12",
   "author": {
     "name": "xr843",
     "email": "xr843@users.noreply.github.com"
@@ -9,6 +9,10 @@
   "homepage": "https://github.com/xr843/Master-skill",
   "repository": "https://github.com/xr843/Master-skill",
   "license": "MIT",
+  "skills": [
+    "./",
+    "./prebuilt/"
+  ],
   "keywords": [
     "buddhism",
     "chinese-buddhism",

package/.codex/INSTALL.md

@@ -3,35 +3,42 @@
 ## Quick Install
 
 ```bash
-# Clone the repository
 git clone https://github.com/xr843/Master-skill.git ~/.codex/master-skill
-
-# Create skills symlink
-ln -sf ~/.codex/master-skill/prebuilt ~/.agents/skills/master-skill
-ln -sf ~/.codex/master-skill/SKILL.md ~/.agents/skills/create-master/SKILL.md
+mkdir -p ~/.agents/skills
+ln -sfn ~/.codex/master-skill/prebuilt ~/.agents/skills/master-skill
+ln -sfn ~/.codex/master-skill ~/.agents/skills/create-master
 ```
 
-Restart Codex to discover the new skills.
+Restart Codex. It should list 20 skills: 15 personas, 4 teaching modes, and
+`create-master`. Codex names a skill found under a linked directory after that
+directory, so they appear as `master-skill:master-huineng`,
+`master-skill:compare-masters`, and so on.
+
+Measured with Codex CLI 0.153.4 on Linux, isolated HOME, 2026-09-16
+(`codex debug prompt-input` shows the skills the model is given):
+
+- Without the `mkdir -p`, both `ln` commands fail on a machine where
+  `~/.agents/skills` does not exist yet.
+- `create-master` must be a link to the whole checkout. A link to the root
+  `SKILL.md` alone is a file symlink, and Codex skips it; the generator also
+  needs the `prompts/` and `references/` beside it.
+- `npx master-skill install` installs to `~/.claude/skills/`, which Codex does
+  not read.
 
 ## Windows (PowerShell)
 
+Not re-verified; mirrors the steps above.
+
 ```powershell
 git clone https://github.com/xr843/Master-skill.git "$env:USERPROFILE\.codex\master-skill"
+New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills" | Out-Null
 cmd /c mklink /J "$env:USERPROFILE\.agents\skills\master-skill" "$env:USERPROFILE\.codex\master-skill\prebuilt"
+cmd /c mklink /J "$env:USERPROFILE\.agents\skills\create-master" "$env:USERPROFILE\.codex\master-skill"
 ```
 
 ## Available Skills After Install
 
-- `/xuanzang` — Xuanzang (Yogacara)
-- `/kumarajiva` — Kumarajiva (Madhyamaka)
-- `/huineng` — Huineng (Chan/Zen)
-- `/zhiyi` — Zhiyi (Tiantai)
-- `/fazang` — Fazang (Huayan)
-- `/yinguang` — Yinguang (Pure Land)
-- `/ouyi` — Ouyi (Tiantai-Pure Land)
-- `/xuyun` — Xuyun (Chan, Five Schools)
-- `/compare-masters` — Multi-tradition comparison
-- `/create-master` — Generate new master
+Run `npx master-skill list` for the current list with descriptions.
 
 ## Tool Mapping
 

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "master-skill",
   "displayName": "Master Skill",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传.",
-  "version": "0.12.11",
+  "version": "0.12.12",
   "author": {
     "name": "xr843",
     "email": "xr843@users.noreply.github.com"

package/.opencode/INSTALL.md

@@ -2,36 +2,49 @@
 
 ## Quick Install
 
-Add to your `opencode.json`:
+```bash
+npx master-skill install --all
+```
+
+OpenCode reads `~/.claude/skills/` without any configuration, and that is where
+this installs. `opencode debug skill` should list 20 skills: 15 personas, 4
+teaching modes, and `create-master`.
+
+## From a Checkout
+
+Point `skills.paths` in `opencode.json` at the checkout's `prebuilt/`:
 
 ```json
 {
-  "plugin": ["master-skill@git+https://github.com/xr843/Master-skill.git"]
+  "skills": { "paths": ["/absolute/path/to/Master-skill/prebuilt"] }
 }
 ```
 
-OpenCode will automatically install and register all skills.
+That gives the 19 skills under `prebuilt/`. `create-master` lives at the
+repository root, outside it.
 
 ## Pin a Version
 
+```bash
+npx master-skill@<version> install --all
+```
+
+## Not a Plugin
+
+Earlier versions of this page said to add
+
 ```json
-{
-  "plugin": ["master-skill@git+https://github.com/xr843/Master-skill.git#v0.3.0"]
-}
+{ "plugin": ["master-skill@git+https://github.com/xr843/Master-skill.git"] }
 ```
 
+OpenCode plugins are JavaScript modules, and this repository ships none. With
+that entry `opencode debug skill` lists none of these skills.
+
+Measured with OpenCode 1.18.13 on Linux, isolated HOME, 2026-09-16.
+
 ## Available Skills After Install
 
-- `/xuanzang` — Xuanzang (Yogacara)
-- `/kumarajiva` — Kumarajiva (Madhyamaka)
-- `/huineng` — Huineng (Chan/Zen)
-- `/zhiyi` — Zhiyi (Tiantai)
-- `/fazang` — Fazang (Huayan)
-- `/yinguang` — Yinguang (Pure Land)
-- `/ouyi` — Ouyi (Tiantai-Pure Land)
-- `/xuyun` — Xuyun (Chan, Five Schools)
-- `/compare-masters` — Multi-tradition comparison
-- `/create-master` — Generate new master
+Run `npx master-skill list` for the current list with descriptions.
 
 ## Tool Mapping
 

package/README.md

@@ -139,7 +139,7 @@ Master-skill 是由 [FoJin](https://fojin.app) 驱动的佛教 AI 祖师人格
 - **HARD-GATE 铁律**：`/create-master` 与预置法师内置红线——教义断言、修行指导与文本解释必须引用该 persona 声明的来源（CBETA / BDRC / Toh / SuttaCentral / PTS / 合规编纂开示），不得捏造来源 ID，不得为虚构人物建角色
 - **二阶段独立审查**：生成管线在写入前强制经过"教义准确性 → 风格一致性"两轮独立审查，FAIL 自动修复最多 2 轮
 - **自动化保真度测试**：211 条夹具（每位祖师 10+ 条，`compare-masters` 元技能 18 条）检查关键词与引用覆盖，每条评分回答另经离线引文审计；CI 在每个 PR 与 main 上做结构校验（dry-run）；实跑评分支持 Anthropic / DeepSeek / Gemini（`--provider`），需要对应的 API key，作为本地/发版前手动步骤执行——最近一次全量运行与逐条裁定见[下文](#保真度评测当前数据)
-- **多平台统一插件**：Claude Code、Cursor、Codex CLI、OpenCode、Gemini CLI 共用一份 `prebuilt/`，session-start hook 跨平台注入法师列表
+- **多平台共用一份 `prebuilt/`**：Claude Code、Cursor、Codex CLI、OpenCode、Gemini CLI 各有装法（见 [docs/install.md](docs/install.md)，Codex / OpenCode / Gemini 三端均为实测过的步骤）
 - **NPX 一键安装**：`npx master-skill install master-zhiyi` 直接部署到 Claude Code
 - **离线工具链**：`scripts/cite.py`（CBETA 引用查询）、`scripts/query.py`（离线语义检索）、`scripts/validate.py`（frontmatter linter）
 - **FoJin 数据桥**：接入 [fojin.app](https://fojin.app) 的 10K+ 篇文本、678K+ 条语义向量与 110K+ 实体的知识图谱（另登记 600+ 个数据源）
@@ -190,7 +190,7 @@ npx master-skill doctor                 # 检查本地安装与运行路径
 npx master-skill update --all           # 升级：重装全部并清掉旧文件
 ```
 
-装好后在对话里直接调 `/master-huineng`、`/compare-masters` 等。
+装好后在对话里直接调 `/master-huineng`、`/compare-masters` 等。npx 装到 `~/.claude/skills/`，Claude Code 与 OpenCode 读取这里；**Codex CLI 与 Gemini CLI 不读**，请按 docs/install.md 的对应小节安装。
 
 > 五端安装细节（Claude Code 插件 / Cursor / OpenCode / Codex CLI / Gemini CLI）、
 > 全局安装、教学模式用法、`/create-master` 自定义生成

package/README_EN.md

@@ -157,7 +157,7 @@ This project is built out of respect for Buddhist traditions. All content is gen
 - **HARD-GATE discipline**: Both `/create-master` and every prebuilt master require doctrinal claims, practice guidance, and text interpretation to cite that persona's declared sources (CBETA / BDRC / Toh / SuttaCentral / PTS / compliant compiled teachings); fabricated source IDs and fictional personas are forbidden
 - **Two-stage independent review**: The generation pipeline forces a "doctrinal accuracy → voice consistency" review before write; FAIL triggers up to 2 rounds of automatic repair
 - **Automated fidelity tests**: 211 fixtures (10+ per master, 18 for the `compare-masters` meta-skill) check keyword and citation coverage, and every graded answer also goes through the offline citation audit; CI runs a structural dry-run on every PR and on `main`; graded runs support Anthropic / DeepSeek / Gemini (`--provider`) with the matching API key, as a manual local/pre-release step — the latest full run and its case-by-case adjudication are [below](#fidelity-evaluation-current-data)
-- **Unified multi-platform plugin**: Claude Code, Cursor, Codex CLI, OpenCode, and Gemini CLI share one `prebuilt/` tree, with a session-start hook injecting the master list on every platform
+- **One `prebuilt/` tree across platforms**: Claude Code, Cursor, Codex CLI, OpenCode, and Gemini CLI each install it differently (see [docs/install.en.md](docs/install.en.md); the Codex, OpenCode, and Gemini steps are measured)
 - **NPX one-shot install**: `npx master-skill install master-zhiyi` drops skills straight into Claude Code
 - **Offline toolchain**: `scripts/cite.py` (CBETA lookup), `scripts/query.py` (offline semantic search), `scripts/validate.py` (frontmatter linter)
 - **FoJin data bridge**: Connected to [fojin.app](https://fojin.app) — 10K+ texts, 678K+ semantic embeddings, a knowledge graph of 110K+ entities, and 600+ registered data sources
@@ -208,7 +208,7 @@ npx master-skill doctor                 # check the local install and runtime pa
 npx master-skill update --all           # upgrade: reinstall everything, clearing stale files
 ```
 
-Once installed, invoke `/master-huineng`, `/compare-masters`, etc. directly in chat.
+Once installed, invoke `/master-huineng`, `/compare-masters`, etc. directly in chat. npx installs to `~/.claude/skills/`, which Claude Code and OpenCode read; **Codex CLI and Gemini CLI do not**, so use their sections in docs/install.en.md.
 
 > Per-platform setup (Claude Code plugin / Cursor / OpenCode / Codex CLI / Gemini CLI),
 > global install, teaching-mode usage, and `/create-master`

package/SKILL.md

@@ -94,7 +94,7 @@ API 故障 / 超时 / 数据阈值 / 引用规则细节 → `references/workflow
 
 将审查通过的名称、传承、宗派、时代、语言、`teaching_content`、`voice_content`、`sources` 与同一 `citation_contract` 写入 `generated-master.json`，再运行 `${CLAUDE_SKILL_DIR}/tools/master_builder.py --spec generated-master.json --output "${CLAUDE_SKILL_DIR}/masters/"`。生成器统一写入 `masters/master-{slug}/`，且 `SKILL.md` 的 name 为 `master-{slug}`；随后运行 `${CLAUDE_SKILL_DIR}/tools/verify_sources.py --final-check "${CLAUDE_SKILL_DIR}/masters/master-{slug}/"`。该终验离线检查四个必需文件、目录/name 一致性，以及 `meta.json` 的来源清单、家族 ID、声明归属和 contract；它不解析 `teaching.md` 自由文本，也不保证外部站点可达。
 
-OpenClaw / Claude Code 注册路径 → `references/workflow-details.md` §Step 5。
+终验通过后运行 `${CLAUDE_SKILL_DIR}/tools/master_builder.py --register "${CLAUDE_SKILL_DIR}/masters/master-{slug}"`：Claude Code 只加载 `~/.claude/skills/<名字>/SKILL.md`，不扫 `masters/`，不注册就无法用 `/master-{slug}` 调用。按输出的 `invoke` 告知用户；`restart_required` 为真时提示重启；报 `not replacing` 时不得覆盖同名 skill，交由用户决定。细节与 OpenClaw 注册 → `references/workflow-details.md` §角色注册（按运行环境）。
 
 ## 追加材料、纠正、管理命令
 
@@ -102,7 +102,7 @@ OpenClaw / Claude Code 注册路径 → `references/workflow-details.md` §Step
 - **纠正模式**：用户说"他不会这样说话/他应该更严厉" → 加载 `prompts/correction_handler.md`；以 `## Correction` 块追加到 teaching.md / voice.md 末尾；patch 递增。
 - **管理命令**：`/list-masters`（列出所有，标 `[预置]`/`[自定义]`）、`/master-rollback <slug> <version>`（回滚，自动归档当前）、`/delete-master <slug>`（删除，预置不可删，需二次确认）。
 
-冲突处理策略、版本号细节、用户确认文案 → `references/workflow-details.md` §追加纠正管理。
+冲突处理策略、版本号细节、用户确认文案 → `references/workflow-details.md` §追加材料、纠正、管理命令细则。
 
 ## 执行优先级（运行时）
 

package/bin/cli.mjs

@@ -435,6 +435,101 @@ function cmdUninstall(names) {
   return failed;
 }
 
+// Every file `install` copies for this skill, relative to its install dir.
+// Mirrors cmdInstall: a persona or mode copies its whole source directory; the
+// generator copies its bundle_paths. `masters/` holds the user's generated
+// personas and `__pycache__` is written by running the tools, so neither is
+// part of what the package installed.
+function expectedInstallFiles(skill) {
+  const src = path.join(PACKAGE_ROOT, skill.source);
+  const roots =
+    skill.kind === "generator"
+      ? skill.bundle_paths.filter((bundlePath) => bundlePath !== "masters")
+      : ["."];
+  const files = [];
+  const walk = (rel) => {
+    const abs = path.join(src, rel);
+    if (!fs.existsSync(abs)) return;
+    if (fs.statSync(abs).isDirectory()) {
+      if (path.basename(abs) === "__pycache__") return;
+      for (const entry of fs.readdirSync(abs)) {
+        walk(rel === "." ? entry : path.join(rel, entry));
+      }
+    } else if (!abs.endsWith(".pyc")) {
+      files.push(rel);
+    }
+  };
+  for (const root of roots) walk(root);
+  return files;
+}
+
+// What is actually under the skills directory. Until 2026-09-17 doctor only
+// checked the package's own sources, and reported "ok" (exit 0) with an
+// installed SKILL.md deleted, a persona's references/ gone, the generator's
+// tools/ gone, an install from an older version — and with nothing installed.
+// A skill that is simply not installed is not a problem: installing one master
+// is a normal choice.
+function installedProblems() {
+  const problems = [];
+  for (const skill of catalogSkills()) {
+    const dest = path.join(SKILLS_DIR, skill.install_dir);
+    if (!fs.existsSync(dest)) continue;
+    if (!fs.existsSync(path.join(dest, "SKILL.md"))) {
+      problems.push({
+        code: "installed-missing-skill-md",
+        name: skill.name,
+        message: `${skill.name} is installed without SKILL.md — run: master-skill install ${skill.name}`,
+      });
+      continue;
+    }
+    const missing = [];
+    const changed = [];
+    for (const rel of expectedInstallFiles(skill)) {
+      const installed = path.join(dest, rel);
+      if (!fs.existsSync(installed)) {
+        missing.push(rel);
+      } else if (
+        !fs.readFileSync(installed).equals(
+          fs.readFileSync(path.join(PACKAGE_ROOT, skill.source, rel))
+        )
+      ) {
+        changed.push(rel);
+      }
+    }
+    if (missing.length) {
+      problems.push({
+        code: "installed-incomplete",
+        name: skill.name,
+        message: `${skill.name} is missing ${missing.length} installed file(s), e.g. ${missing[0]} — run: master-skill install ${skill.name}`,
+      });
+    }
+    if (changed.length) {
+      problems.push({
+        code: "installed-outdated",
+        name: skill.name,
+        message: `${skill.name} differs from package ${pkgVersion()} in ${changed.length} file(s), e.g. ${changed[0]} — run: master-skill update --all`,
+      });
+    }
+  }
+
+  // Personas registered by create-master are links into create-master/masters/;
+  // uninstalling the generator leaves them pointing at nothing.
+  if (fs.existsSync(SKILLS_DIR)) {
+    for (const entry of fs.readdirSync(SKILLS_DIR, { withFileTypes: true })) {
+      if (!entry.isSymbolicLink()) continue;
+      const link = path.join(SKILLS_DIR, entry.name);
+      if (!fs.existsSync(link)) {
+        problems.push({
+          code: "dangling-link",
+          name: entry.name,
+          message: `${entry.name} links to ${fs.readlinkSync(link)}, which no longer exists`,
+        });
+      }
+    }
+  }
+  return problems;
+}
+
 function doctorData() {
   const masters = availableMasters();
   const installed = installedSkillDirs();
@@ -453,6 +548,7 @@ function doctorData() {
     name: skill.name,
     message: `${skill.name} is missing SKILL.md`,
   }));
+  problems.push(...installedProblems());
 
   return {
     packageVersion: pkgVersion(),

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "master-skill",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 prebuilt masters across 印度/汉传/藏传/南传.",
-  "version": "0.12.11",
+  "version": "0.12.12",
   "contextFileName": "GEMINI.md"
 }

package/hooks/session_start.py

@@ -25,13 +25,24 @@ import json
 import os
 import re
 import sys
+import unicodedata
 from pathlib import Path
 
-# Whitelist: CJK Unified, ASCII alphanumerics, fullwidth parens, space, · _ ( ) -
-# Everything else — backticks, dollars, quotes, slashes, control characters —
-# is dropped. An attacker who lands a malicious SKILL.md (or a contributor with
-# a typo) must not be able to reach the system prompt through it.
-_ALLOWED = re.compile(r"[^一-鿿0-9A-Za-z _\-·（）()]", re.UNICODE)
+# Whitelist: CJK Unified, ASCII alphanumerics, Latin letters with diacritics,
+# fullwidth parens and solidus, space, · _ ( ) -
+# Everything else — backticks, dollars, quotes, ASCII slashes, control, format
+# and bidi characters — is dropped. An attacker who lands a malicious SKILL.md
+# (or a contributor with a typo) must not be able to reach the system prompt
+# through it.
+#
+# The Latin ranges are letters only: À-Ö Ø-ö ø-ÿ (Latin-1 without × and ÷),
+# Latin Extended-A, and Latin Extended Additional. Until 2026-09-16 they were
+# absent, and five of fifteen shipped lineages reached the model altered:
+# "(Mahāvihāra)" as "(Mahvihra)", and "三论宗/中观" as the single made-up term
+# "三论宗中观" because the slash was deleted rather than kept. An ASCII slash is
+# still never emitted — it could read as a slash command — so it becomes the
+# fullwidth "／", which keeps the "A or B" meaning.
+_ALLOWED = re.compile(r"[^一-鿿0-9A-Za-zÀ-ÖØ-öø-ſḀ-ỿ _\-·（）()／]", re.UNICODE)
 _CONTROL = re.compile(r"[\x00-\x1f\x7f-\x9f]")
 _WHITESPACE = re.compile(r"\s+")
 
@@ -61,8 +72,10 @@ _LINEAGE_LINE = re.compile(r"^lineage:[ \t]*(.*)$", re.MULTILINE)
 
 def sanitize_lineage(raw: str) -> str:
     """Normalize one raw `lineage:` frontmatter value for prompt splicing."""
-    text = _CONTROL.sub("", raw or "")
-    text = _ALLOWED.sub("", text)
+    # NFC first: a decomposed "ā" (a + U+0304) would otherwise lose its
+    # combining macron and silently become "a".
+    text = _CONTROL.sub("", unicodedata.normalize("NFC", raw or ""))
+    text = _ALLOWED.sub("", text.replace("/", "／"))
     text = _WHITESPACE.sub(" ", text).strip()
     return text[:MAX_LINEAGE_CHARS]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "master-skill",
-  "version": "0.12.11",
+  "version": "0.12.12",
   "type": "module",
   "description": "FoJin-powered Buddhist AI persona framework — source-grounded, boundary-aware, fidelity-tested, runtime-ready. 15 pre-built masters across 印度 / 汉传 / 藏传 / 南传, plus /compare-masters, /master-debate, and /master-curriculum.",
   "bin": {
@@ -16,7 +16,7 @@
     "validate:versions": "python3 scripts/check-manifest-versions.py",
     "test:hook": "bash hooks/tests/test_session_start.sh && bash hooks/tests/test_run_hook.sh && bash hooks/tests/test_run_hook_cmd.sh",
     "test:cli": "node --test tests/cli.test.mjs",
-    "test": "python3 scripts/check-gate-liveness.py && python3 scripts/validate.py --strict && python3 scripts/validate-citation-references.py && python3 scripts/validate-citation-templates.py && python3 scripts/validate-self-audit-sources.py && python3 scripts/validate-citation-contract.py && python3 scripts/validate-cross-critique.py && python3 scripts/validate-lore-triggers-content.py --strict && python3 scripts/validate-quote-attribution.py && python3 scripts/validate-promptfoo-configs.py && python3 scripts/validate-fidelity.py && python3 scripts/validate-persona-fidelity.py && python3 scripts/check-manifest-versions.py && python3 scripts/validate-routing.py && python3 scripts/validate-fixture-terms.py && python3 scripts/verify-adjudication.py && python3 scripts/test-fidelity.py --all --dry-run && node --test tests/cli.test.mjs && python3 -m pytest tests/ scripts/tests/ -q",
+    "test": "python3 scripts/check-gate-liveness.py && python3 scripts/validate.py --strict && python3 scripts/validate-citation-references.py && python3 scripts/validate-citation-templates.py && python3 scripts/validate-self-audit-sources.py && python3 scripts/validate-citation-contract.py && python3 scripts/validate-cross-critique.py && python3 scripts/validate-lore-triggers-content.py --strict && python3 scripts/validate-quote-attribution.py && python3 scripts/validate-section-references.py && python3 scripts/validate-promptfoo-configs.py && python3 scripts/validate-fidelity.py && python3 scripts/validate-persona-fidelity.py && python3 scripts/check-manifest-versions.py && python3 scripts/validate-routing.py && python3 scripts/validate-fixture-terms.py && python3 scripts/verify-adjudication.py && python3 scripts/test-fidelity.py --all --dry-run && node --test tests/cli.test.mjs && python3 -m pytest tests/ scripts/tests/ -q",
     "test:smoke": "python3 scripts/test-fidelity.py --master yinguang --max-tests 1",
     "prepack": "node bin/cli.mjs list"
   },

package/prebuilt/master-ajahn-chah/SKILL.md

@@ -29,15 +29,15 @@ verified_at: 2026-05-02
 
 用户问题类型 →
 - **正念 / 觉知 / 看自己的心**（sati / awareness / mindfulness）
-  → 读 `sources/teachings-excerpts.md` §正念与觉知 + `references/teaching.md` §心的训练
+  → 读 `sources/teachings-excerpts.md` §正念与觉知、§心的训练 + `references/teaching.md` §四念处与正念
 - **放下 / 执取 / 痛苦的根源**（letting go / clinging / dukkha）
-  → 读 `sources/teachings-excerpts.md` §放下 + `references/teaching.md` §苦与放下
+  → 读 `sources/teachings-excerpts.md` §放下 + `references/teaching.md` §放下
 - **三法印 / 无常 / 无我**（anicca / dukkha / anatta）
   → 读 `sources/sutta-excerpts.md` §三法印 + `references/teaching.md` §三法印
 - **禅修方法 / 出入息念 / 妄念多**（anapanasati / 散乱）
-  → 读 `sources/teachings-excerpts.md` §禅修与出入息念 + `references/teaching.md` §禅那与毗婆舍那
+  → 读 `sources/teachings-excerpts.md` §禅修与出入息念 + `references/teaching.md` §出入息念
 - **戒律 / 出家生活 / 杜多行**（vinaya / dhutanga / 头陀）
-  → 读 `references/teaching.md` §戒与森林生活
+  → 读 `references/teaching.md` §戒定慧三学、§杜多行 + `sources/teachings-excerpts.md` §日常生活与中道
 - **风格对话**（"想和阿姜查交流"/角色扮演）
   → 读 `references/voice.md` 建立人格（**内化即可，勿向用户复述此步**），再按上述分类响应
 - **离线摘录覆盖不到已声明来源的所需位置**（具体卷次 / 已声明来源的章节未收录 / `sources/` 检索为空）

package/prebuilt/master-ajahn-chah/sources/sutta-excerpts.md

@@ -9,7 +9,7 @@
 
 ### 五蕴非我经（Anattalakkhaṇa Sutta）
 
-佛陀第二次说法对象——五位最初弟子。佛说："比丘们，色（rūpa）非我；受（vedanā）非我；想（saññā）非我；行（saṅkhārā）非我；识（viññāṇa）非我。何以故？若色是我，色不应病；若色是我，应能令色'如是、不如是'。诸比丘，色是无常、苦、变易法，故非我、非我所、非我体。受、想、行、识亦复如是。"
+佛陀第二次说法对象——五位最初弟子。经文要旨（非逐字译文）：色（rūpa）非我——若色是我，色就不会招致病苦，也能令色如是、不如是；正因色非我，色才招致病苦，也不能令色如是、不如是。受（vedanā）、想（saññā）、行（saṅkhārā）、识（viññāṇa）亦然。佛继而以问答引导五比丘：色是常还是无常？比丘答无常。无常者是苦是乐？答苦。无常、苦、变易之法，可视之为此是我所、此是我、此是我体吗？答不可。故一切色，无论过去未来现在、内外、粗细、劣胜、远近，皆应以正慧如实观为此非我所、此非我、此非我体；受、想、行、识亦然。
 
 听此说法已，五比丘漏尽，证阿罗汉果。
 
@@ -35,7 +35,7 @@
 
 ### 念处经 / 大念处经（Satipaṭṭhāna / Mahāsatipaṭṭhāna Sutta）
 
-佛说："诸比丘，此一行道，能令众生清净、超越愁悲、灭除苦忧、得正理、证涅槃，所谓四念处。何为四？比丘于身观身、于受观受、于心观心、于法观法，热忱、正知、正念，远离世间贪忧。"
+经文要旨（非逐字译文）：此一行道能令众生清净、超越愁悲、灭除苦忧、得正理、证涅槃，即四念处——比丘于身观身、于受观受、于心观心、于法观法，热忱、正知、正念，远离世间贪忧。
 
 **四念处之要**：
 - **身念处**：观身呼吸、行住坐卧、身体三十二分、四界（地水火风）、墓地九相
@@ -100,7 +100,7 @@
 
 ### 一切经（Sabba Sutta）
 
-佛说："何为一切？眼与色、耳与声、鼻与香、舌与味、身与触、意与法——此乃一切。除此之外若有人言别有'一切'，唯口言尔，问之则不能答。"
+经文要旨（非逐字译文）：一切，即眼与色、耳与声、鼻与香、舌与味、身与触、意与法。若有人说要舍此一切而另立一切，那只是言说：问之则不能答，更将陷于困恼——因为那已超出他所能了知的范围。
 
 **主旨**：将"世界"还原为六根六尘的当下经验，断除对超越实体（永恒灵魂、绝对实体）之执取。
 

package/prebuilt/master-atisha/SKILL.md

@@ -138,7 +138,7 @@ GET https://fojin.app/api/search/semantic?q=<URL编码查询>&top_k=5   # 语义
 | 怎么发菩提心 | `references/teaching.md` §菩提心 | 七因果 + 自他相换 / 金洲传承 |
 | 暇满人身为何重要 | `references/teaching.md` §下士道 | 《道灯论·下士道章》（Toh 4465）|
 | 阿底峡为什么入藏 | `references/teaching.md` §传承与背景 | 智光王邀请 + 律仪整顿 |
-| 噶当派的核心是什么 | `references/teaching.md` §噶当派精神 | 《父法·子法》传承 |
+| 噶当派的核心是什么 | `references/teaching.md` §依止善知识、§噶当六论 | 《父法·子法》传承 |
 | 怎么修拙火 / 灌顶 / 密法步骤 | — **拒答**：须具格上师亲传 | — |
 
 ## 教学路径（用于组织回答）

package/prebuilt/master-buddhaghosa/SKILL.md

@@ -142,7 +142,7 @@ GET https://fojin.app/api/search/semantic?q=<URL编码查询>&top_k=5   # 语义
 | 什么是戒定慧三学 | `sources/visuddhimagga-excerpts.md` §戒定慧 | 《Vism》§I–XXIII 总纲 + AN 3.88 |
 | 四十种业处是什么 | `sources/visuddhimagga-excerpts.md` §业处 | 《Vism》§III–XI |
 | 什么是七清净十六观智 | `sources/visuddhimagga-excerpts.md` §七清净 | 《Vism》§XVIII–XXII + MN 24 |
-| 出入息念怎么修 | `references/teaching.md` §业处 §出入息念 | 《Vism》§VIII §145–245 + MN 118 |
+| 出入息念怎么修 | `sources/visuddhimagga-excerpts.md` §出入息念 | 《Vism》§VIII §145–245 + MN 118 |
 | 缘起十二支怎么理解 | `references/teaching.md` §缘起 | 《Vism》§XVII + SN 12.2 |
 | 阿毗达摩心心所色怎么分 | `references/teaching.md` §阿毗达摩 | 《Vism》§XIV–XVII + Atthasālinī |
 | 教我具体的禅修步骤 | — 引导咨询具格禅师 | — |

package/prebuilt/master-mahasi-sayadaw/SKILL.md

@@ -36,9 +36,9 @@ verified_at: 2026-05-02
 - **标记法 / 腹部起伏主所缘**（Noting Method / rising falling）
   → 读 `sources/teachings-excerpts.md` §标记法 + `references/teaching.md` §标记法
 - **正念 / sati / 觉知不间断**
-  → 读 `sources/teachings-excerpts.md` §正念力 + 巴利经引（MN 10）
+  → 读 `sources/teachings-excerpts.md` §正念之要在持续 + `references/teaching.md` §正念力 + 巴利经引（MN 10）
 - **十六观智 / 七清净 / 进度参照**
-  → 读 `sources/teachings-excerpts.md` §十六观智 + `references/teaching.md` §观智次第
+  → 读 `sources/teachings-excerpts.md` §观智次第 + `references/teaching.md` §七清净与观智次第
 - **妄念多 / 散乱 / 怎么办**
   → 读 `sources/teachings-excerpts.md` §妄念多 + `references/teaching.md` §对治散乱
 - **刹那定 / 毗婆舍那禅那**（khaṇika-samādhi / vipassanā-jhāna）

package/prebuilt/master-mahasi-sayadaw/sources/teachings-excerpts.md

@@ -115,9 +115,9 @@
 
 马哈希内观法以四念处经为根本经典依据。
 
-经文核心：
+经文要旨（非逐字译文）：
 
-> "诸比丘，此一行道，能令众生清净、超越愁悲、灭除苦忧、得正理、证涅槃，所谓四念处。何为四？比丘于身观身、于受观受、于心观心、于法观法，热忱（ātāpī）、正知（sampajāno）、正念（satimā），远离世间贪忧。"
+此一行道能令众生清净、超越愁悲、灭除苦忧、得正理、证涅槃，即四念处——比丘于身观身、于受观受、于心观心、于法观法，热忱（ātāpī）、正知（sampajāno）、正念（satimā），远离世间贪忧。
 
 **四念处全面观察**：
 - **身念处**：呼吸、行住坐卧、身体三十二分、四界、墓地九相

package/prebuilt/master-milarepa/SKILL.md

@@ -27,11 +27,11 @@ verified_at: 2026-05-02
 
 用户问题类型 →
 - **苦行 / 闭关 / 山中修行**（雪山闭关 / 荨麻为食 / 一座修法）
-  → 读 `sources/namthar-excerpts.md` §雪山苦行 + `references/teaching.md` §出离与精进
+  → 读 `sources/namthar-excerpts.md` §雪山苦行 + `references/teaching.md` §出离心与精进闭关
 - **大手印 / 明空 / 本觉**（phyag chen / 心性 / rig pa）
-  → 读 `sources/grubum-excerpts.md` §大手印道歌 + `references/teaching.md` §大手印见地
+  → 读 `sources/grubum-excerpts.md` §大手印见地 + `references/teaching.md` §大手印见地
 - **那洛六法 / 拙火 / 气脉明点**（tummo / 中阴 / 梦观）
-  → 读 `sources/grubum-excerpts.md` §拙火与气脉 + `references/teaching.md` §那洛六法
+  → 读 `references/teaching.md` §那洛六法（只有名义与历史）；具体修法 `sources/grubum-excerpts.md` §本目录不收录之内容（故意不收，按 HARD-GATE 统一回应）
 - **业果 / 忏悔 / 黑魔术过往**（早年咒杀仇家 / 玛尔巴的折磨 / 净罪）
   → 读 `sources/namthar-excerpts.md` §业与忏悔
 - **上师瑜伽 / 玛尔巴 / 信心**（依止善知识 / 译师玛尔巴 / 信心生起）
@@ -134,7 +134,7 @@ GET https://fojin.app/api/search/semantic?q=<URL编码查询>&top_k=5   # 语义
 | 玛尔巴为什么折磨米拉日巴 | `sources/namthar-excerpts.md` §业与忏悔 | 《尊者传》(BDRC: W1GS56158) |
 | 怎么生起出离心 | `sources/grubum-excerpts.md` §出离 | 《道歌集·无常之歌》 |
 | 怎么修拙火（具体方法）| — **拒答**：须具格上师传授 | — |
-| 觉受 (nyams) 与证悟的区别 | `references/teaching.md` §觉受 vs 证悟 | 《道歌集》多处 |
+| 觉受 (nyams) 与证悟的区别 | `references/teaching.md` §觉受与证悟 | 《道歌集》多处 |
 
 ## 教学路径（用于组织回答）
 

package/prebuilt/master-ouyi/SKILL.md

@@ -46,7 +46,7 @@ verified_at: 2026-04-06
 - **天台教观**（教观纲宗 / 止观 / 一念心性）
   → 读 `references/teaching.md` §教宗天台 + `sources/jiaoguan-gangzong-excerpts.md`
 - **宗派融通**（性相融会 / 禅教律净 / 跨宗派）
-  → 读 `references/teaching.md` §融通 + `sources/mituo-yaojie-excerpts.md` §现前一念
+  → 读 `references/teaching.md` §融通 + `sources/mituo-yaojie-excerpts.md` §一念心性
 - **修行方法**（持名念佛 / 持戒 / 占察忏）
   → 读 `references/teaching.md` §修行方法
 - **风格对话**（"想和蕅益大师聊聊"/角色扮演请求）

package/prebuilt/master-tsongkhapa/SKILL.md

@@ -43,7 +43,7 @@ verified_at: 2026-05-02
 - **应成中观正见 / 空性 / 辨了不了义**
   → 读 `sources/lamrim-excerpts.md` §毗钵舍那（vipaśyanā）章 + `references/teaching.md` §应成中观
 - **戒律 / 三聚戒 / 律仪根本**
-  → 读 `references/teaching.md` §戒律根本
+  → 读 `references/teaching.md` §戒律为根本
 - **密宗 / 续部** → 仅介绍历史与原理，**不传授修法步骤**（参 HARD-GATE）
 - **格鲁派传承 / 甘丹寺 / 默朗钦摩 / 达赖班禅**
   → 读 `references/teaching.md` §传承与背景
@@ -152,8 +152,8 @@ GET https://fojin.app/api/search/semantic?q=<URL编码查询>&top_k=5   # 语义
 | 什么是三主要道 | `sources/lamrim-excerpts.md` §三主要道 | 《三主要道》(Lam gtso rnam gsum) |
 | 道次第怎么学 | `sources/lamrim-excerpts.md` §三士道 | 《菩提道次第广论》|
 | 应成中观和自续中观区别 | `references/teaching.md` §应成中观 | 《辨了不了义》+《入中论善显密意疏》|
-| 缘起性空怎么理解 | `references/teaching.md` §应成中观 §缘起性空 | 《辨了不了义》|
-| 戒定慧三学怎么学 | `references/teaching.md` §戒律根本 | 《广论》共下/中士道 |
+| 缘起性空怎么理解 | `references/teaching.md` §应成中观正见 | 《辨了不了义》|
+| 戒定慧三学怎么学 | `references/teaching.md` §戒律为根本 | 《广论》共下/中士道 |
 | 怎么修拙火 / 灌顶 / 生起圆满次第 | — **拒答**：须具格上师亲传 | — |
 | 格鲁派和宁玛派哪个好 | — **拒答**：不评判他派优劣 | — |
 

package/prebuilt/master-xuyun/SKILL.md

@@ -37,7 +37,7 @@ verified_at: 2026-04-06
 
 用户问题类型 →
 - **参禅方法**（话头 / 疑情 / 念佛是谁 / 禅七 / 行香坐禅）
-  → 读 `sources/lengyanjing-excerpts.md` §心性 + `references/teaching.md` §参话头
+  → 读 `sources/lengyanjing-excerpts.md` §七处征心 + `references/teaching.md` §参话头
 - **禅宗教义**（明心见性 / 本来面目 / 开悟 / 桶底脱落）
   → 读 `references/teaching.md` §核心教导 + `sources/tanjing-excerpts.md`
 - **持戒与丛林**（戒律 / 丛林规矩 / 日常修行）

package/prebuilt/master-zhiyi/SKILL.md

@@ -39,7 +39,7 @@ verified_at: 2026-04-06
 - **教义询问**（一念三千 / 三谛 / 五时八教 / 性具善恶）
   → 读 `references/teaching.md` + 引用 `sources/mohezhiguan-excerpts.md`
 - **修行方法**（止观 / 一心三观 / 四种三昧 / 六即判位）
-  → 读 `sources/mohezhiguan-excerpts.md` §止觀法門 + 必要时 `references/teaching.md` §修行方法
+  → 读 `sources/mohezhiguan-excerpts.md` §圆顿止观开篇、§二十五方便、§一心三观、§六即佛 + 必要时 `references/teaching.md` §修行方法
 - **判教体系**（藏通别圆 / 化仪四教 / 五时分判）
   → 读 `references/teaching.md` §判教 + `sources/fahua-xuanyi-excerpts.md`
 - **法华经义理**（开权显实 / 会三归一 / 穷子喻）
@@ -138,7 +138,7 @@ GET https://fojin.app/api/search/semantic?q=<URL编码查询>&top_k=5   # 语义
 | 三谛圆融怎么理解 | `references/teaching.md` §三谛圆融 | 《法華玄義》卷二，T1716 |
 | 五时八教怎么分 | `references/teaching.md` §判教 | 《法華玄義》卷一，T1716 |
 | 止观怎么修 | `sources/mohezhiguan-excerpts.md` §二十五方便 | 《摩訶止觀》卷四，T1911 |
-| 一心三观 | `sources/mohezhiguan-excerpts.md` §一心三觀 | 《摩訶止觀》卷五，T1911 |
+| 一心三观 | `sources/mohezhiguan-excerpts.md` §一心三观 | 《摩訶止觀》卷五，T1911 |
 | 四种三昧 | `references/teaching.md` §四种三昧 | 《摩訶止觀》卷二，T1911 |
 | 性具善恶 | `references/teaching.md` §性具 | 《觀音玄義》卷上，T1726 |
 | 入门从哪开始 | — | 《修習止觀坐禪法要》（小止觀），T1915 |

package/references/workflow-details.md

@@ -235,7 +235,7 @@ FAIL → 自动修复后重审。
 ## Step 5：写入文件细则
 
 ```bash
-python3 ${CLAUDE_SKILL_DIR}/tools/master_builder.py --spec generated-master.json --output masters/
+python3 "${CLAUDE_SKILL_DIR}/tools/master_builder.py" --spec generated-master.json --output "${CLAUDE_SKILL_DIR}/masters/"
 ```
 
 `generated-master.json` 是审查通过后的生成规格，必含 `name`、`tradition`、`school`、`era`、
@@ -245,7 +245,7 @@ python3 ${CLAUDE_SKILL_DIR}/tools/master_builder.py --spec generated-master.json
 ### 生成后终验
 
 ```bash
-python3 ${CLAUDE_SKILL_DIR}/tools/verify_sources.py --final-check masters/master-{slug}/
+python3 "${CLAUDE_SKILL_DIR}/tools/verify_sources.py" --final-check "${CLAUDE_SKILL_DIR}/masters/master-{slug}/"
 ```
 
 `--final-check` 离线验证 persona 目录包含 `SKILL.md`、`teaching.md`、`voice.md`、`meta.json`，
@@ -255,8 +255,8 @@ python3 ${CLAUDE_SKILL_DIR}/tools/verify_sources.py --final-check masters/master
 ### 生成目录结构
 
 ```
-masters/master-{slug}/
-├── SKILL.md          # /master-{slug} 触发（完整角色定义）
+${CLAUDE_SKILL_DIR}/masters/master-{slug}/
+├── SKILL.md          # 注册后由 /master-{slug} 触发（完整角色定义）
 ├── teaching.md       # 教义体系（可单独使用）
 ├── voice.md          # 说法风格（可单独使用）
 └── meta.json         # 元数据（版本、生成时间、数据来源）
@@ -265,9 +265,27 @@ masters/master-{slug}/
 ### 角色注册（按运行环境）
 
 **Claude Code 用户**
-1. 生成的 SKILL.md 已放置在 `masters/master-{slug}/`
-2. 确保 `masters/` 在 Claude Code skill 搜索路径中（检查 `.claude/settings.json` 的 `skillDirs` 配置）
-3. 完成后自动可通过 `/master-{slug}` 触发
+
+终验通过后注册：
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/tools/master_builder.py" --register "${CLAUDE_SKILL_DIR}/masters/master-{slug}"
+```
+
+它在 `~/.claude/skills/master-{slug}` 建一个指向生成目录的链接（Windows 上建 junction），输出 JSON：
+
+- `invoke`：调用命令，照此告知用户；
+- `restart_required: true`：`~/.claude/skills/` 是这次才建的，需重启 Claude Code 才会被发现；否则当前会话内即可调用；
+- 退出码 1 且提示 `not replacing`：同名 skill 已存在（例如重新生成了一位预置祖师）。**不要删除或覆盖它**，把情况告诉用户，由用户决定改名或自行移除。
+
+为什么需要这一步：Claude Code 只加载 `<skills 目录>/<名字>/SKILL.md`，不往下扫，也没有 `skillDirs` 之类的设置。
+2026-09-16 用 Claude Code 2.1.273 在隔离配置中实测：放在 `~/.claude/skills/create-master/masters/` 下的 persona
+不出现在 `/skills` 里；注册出链接后，同一会话内即出现。生成目录留在 `masters/` 是为了让
+`master-skill update` 更新运行时的时候不丢失用户生成的 persona。
+
+以插件方式安装时，`${CLAUDE_SKILL_DIR}` 是按版本号区分的插件缓存目录：`claude plugin update` 之后
+它换到新版本目录，新目录下的 `masters/` 是空的（实测 0.12.11 → 0.12.12）。要长期保留自己生成的 persona，
+请用 `npx master-skill install create-master` 或 git clone 方式安装生成器。
 
 **OpenClaw 用户**
 1. 将 `masters/master-{slug}/` 复制到 OpenClaw 的 skills 目录
@@ -278,8 +296,8 @@ masters/master-{slug}/
 
 ```
 已生成「{master_name}」教学角色
-  目录：masters/master-{slug}/
-  调用命令：/master-{slug}
+  目录：${CLAUDE_SKILL_DIR}/masters/master-{slug}/
+  调用命令：/master-{slug}（已注册到 ~/.claude/skills/master-{slug}）
   包含文件：SKILL.md, teaching.md, voice.md, meta.json
   数据来源：{n} 条经文，{m} 个知识图谱实体
 ```

package/scripts/validate-section-references.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Gate: a "read `file.md` §section" instruction must land on something.
+
+Every persona's SKILL.md routes a question to material: a decision tree says
+读 `references/teaching.md` §参话头, a Quick Reference row says the same. The
+model follows those pointers literally. Nothing checked that the section they
+name exists, and the files they point into have been rewritten many times since
+the routing was written — sections renamed to a book's real chapter titles,
+material moved from references/ to sources/.
+
+2026-09-16, measured across the repo: 18 of 198 section pointers in nine personas
+named a section the target file does not have, and so did one in the generator's
+own SKILL.md. Most were renames (§戒律根本 for 戒律为根本), but not all were
+harmless:
+
+  - master-milarepa routed 那洛六法 / 拙火 / 气脉明点 to
+    `sources/grubum-excerpts.md` §拙火与气脉. That file has no such section on
+    purpose — it lists tummo among what it deliberately does not hold, with the
+    answer to give instead. The pointer sent the model to look for exactly the
+    material the persona is forbidden to supply.
+  - master-mahasi-sayadaw routed 十六观智 to §十六观智 in an excerpt file whose
+    section is 观智次第 and which says the book numbers seventeen, not sixteen.
+  - master-ajahn-chah sent 心的训练 to references/teaching.md; the section is in
+    sources/teachings-excerpts.md.
+
+A section counts as present when the name appears, ignoring punctuation and
+spacing, in a heading of the target file or in a **bold label** — the persona
+docs use bold labels (**十念法**, **数息观**) as sub-section markers, and a model
+searching for the name finds either. Parenthesised glosses are optional on both
+sides of the match, so §觉受与证悟 finds `6. 觉受 (nyams) 与证悟 (rtogs pa) 的区分`.
+Prose may run on after a name (§版权分级 Tier B/C 流程), so trailing words split
+off by spaces are dropped one at a time; the first word must still be found.
+
+A path with a directory in it must name a file that exists even with no section.
+A bare `teaching.md` without one is prose — the generator docs name the files
+they produce that way — and is not a pointer.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+PREBUILT_DIR = ROOT / "prebuilt"
+
+# The docs the model is told to follow: every persona and mode, and the
+# generator skill with its references.
+DOC_GLOBS = ("prebuilt/**/*.md", "SKILL.md", "references/*.md")
+
+_PATH = re.compile(r"`((?:[\w-]+/)*[\w.-]+\.md)`")
+# A section name ends at the next separator a routing line uses: `+`, a table
+# pipe, CJK punctuation, a backtick or an opening gloss.
+_SECTIONS = re.compile(r"(?:[ \t、]*§[^§`+＋\n，、；;|。（）()]*)+")
+_SECTION = re.compile(r"§([^§、]*)")
+_BOLD = re.compile(r"\*\*([^*\n]+)\*\*")
+_GLOSS = re.compile(r"[（(][^（）()]*[）)]")
+_NUMBERING = re.compile(r"^\s*(?:\d+\.|[①-⑳])\s*")
+_NOISE = re.compile(r"[\s·、，,。.:：—\-–《》「」\"'`*§⚠️]")
+
+
+def _norm(text: str) -> str:
+    return _NOISE.sub("", _NUMBERING.sub("", text)).lower()
+
+
+def anchor_forms(anchor: str) -> set[str]:
+    """一个标题或粗体标签可被匹配的写法：连同括注，或去掉括注。"""
+    return {_norm(re.sub(r"[（）()]", "", anchor)), _norm(_GLOSS.sub("", anchor))}
+
+
+def anchors(lines: list[str]) -> list[str]:
+    found = [line.lstrip("#").strip() for line in lines if line.startswith("#")]
+    for line in lines:
+        found.extend(_BOLD.findall(line))
+    return found
+
+
+def section_present(name: str, lines: list[str]) -> bool:
+    forms = {form for anchor in anchors(lines) for form in anchor_forms(anchor)}
+    words = name.split()
+    while words:
+        wanted = _norm(" ".join(words))
+        if wanted and any(wanted in form for form in forms):
+            return True
+        words.pop()
+    return not _norm(name)
+
+
+def references(line: str) -> list[tuple[str, list[str]]]:
+    """[(路径, [小节名…])]：这一行里的每个文件指针及其所指小节。"""
+    out = []
+    for m in _PATH.finditer(line):
+        tail = _SECTIONS.match(line, m.end())
+        names = []
+        if tail:
+            names = [n.strip() for n in _SECTION.findall(tail.group(0)) if n.strip()]
+        out.append((m.group(1), names))
+    return out
+
+
+def _skill_root(doc: Path) -> Path:
+    rel = doc.relative_to(ROOT)
+    return ROOT / rel.parts[0] / rel.parts[1] if rel.parts[0] == "prebuilt" else ROOT
+
+
+def resolve(doc: Path, rel: str) -> Path | None:
+    for base in (_skill_root(doc), doc.parent, ROOT):
+        if (base / rel).is_file():
+            return base / rel
+    return None
+
+
+def dangling(docs: list[Path]) -> tuple[int, list[str]]:
+    """(检查过的指针数, [问题…])。"""
+    examined, problems = 0, []
+    cache: dict[Path, list[str]] = {}
+    for doc in docs:
+        for number, line in enumerate(doc.read_text(encoding="utf-8").splitlines(), 1):
+            if "{" in line:
+                continue  # 模板行，如 `prebuilt/{slug}/…` 下的 `references/teaching.md`
+            where = f"{doc.relative_to(ROOT)}:{number}"
+            for rel, names in references(line):
+                if "/" not in rel and not names:
+                    continue  # 裸文件名是行文，不是指针
+                examined += 1
+                target = resolve(doc, rel)
+                if target is None:
+                    problems.append(f"{where}  `{rel}` does not exist")
+                    continue
+                if target not in cache:
+                    cache[target] = target.read_text(encoding="utf-8").splitlines()
+                for name in names:
+                    if not section_present(name, cache[target]):
+                        problems.append(f"{where}  `{rel}` has no section §{name}")
+    return examined, problems
+
+
+def model_facing_docs() -> list[Path]:
+    return sorted({p for pattern in DOC_GLOBS for p in ROOT.glob(pattern) if p.is_file()})
+
+
+def main() -> int:
+    examined, problems = dangling(model_facing_docs())
+    if examined == 0:
+        print("FAIL: found no file pointers at all — this gate examined an empty set.")
+        return 1
+    if problems:
+        print(f"FAIL: {len(problems)} of {examined} file pointer(s) do not land:")
+        for problem in problems:
+            print(f"  {problem}")
+        print(
+            "\nThe model follows these pointers literally. A section that is not there\n"
+            "leaves it to improvise the material it was sent to read. Point at a heading\n"
+            "or **bold label** the file actually has, or drop the § and name the file."
+        )
+        return 1
+    print(f"OK: all {examined} file pointers land on a file and section that exist.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/tools/master_builder.py

@@ -309,6 +309,76 @@ def build_from_spec(spec: dict, output_dir: str) -> dict:
     }
 
 
+_SKILL_NAME = re.compile(r"^name:[ \t]*(\S+)[ \t]*$", re.MULTILINE)
+
+
+def register_teacher(teacher_dir: str, skills_dir: str) -> dict:
+    """Make a generated persona invocable by linking it into a skills directory.
+
+    The generator writes to `${CLAUDE_SKILL_DIR}/masters/master-{slug}/`, so that
+    `master-skill update` can carry generated personas across runtime updates.
+    Claude Code does not look there: it loads `<skills dir>/<name>/SKILL.md` and
+    scans no deeper. Measured 2026-09-16 with Claude Code 2.1.273 in an isolated
+    config, `/skills` listed a probe skill at `~/.claude/skills/master-control/`
+    and not one at `~/.claude/skills/create-master/masters/master-probe/`; a
+    directory symlink `~/.claude/skills/master-probe` made it appear in the same
+    session, without a restart.
+
+    An existing entry of the same name is never replaced: a user regenerating a
+    prebuilt master (`master-huineng`) must not overwrite the installed one.
+    """
+    teacher = Path(teacher_dir).resolve()
+    skill_md = teacher / "SKILL.md"
+    if not skill_md.is_file():
+        raise ValueError(f"{teacher} has no SKILL.md")
+    text = skill_md.read_text(encoding="utf-8")
+    frontmatter = text.split("---", 2)[1] if text.startswith("---") else ""
+    match = _SKILL_NAME.search(frontmatter)
+    if not match or match.group(1) != teacher.name:
+        raise ValueError(
+            f"SKILL.md name must equal the directory name {teacher.name!r} — "
+            "Claude Code invokes the skill by that name"
+        )
+
+    skills = Path(skills_dir).expanduser()
+    created_skills_dir = not skills.is_dir()
+    skills.mkdir(parents=True, exist_ok=True)
+    link = skills / teacher.name
+
+    if link.exists() or link.is_symlink():
+        if link.exists() and link.resolve() == teacher:
+            return {
+                "registered": str(link),
+                "target": str(teacher),
+                "invoke": f"/{teacher.name}",
+                "already_registered": True,
+                "restart_required": False,
+            }
+        raise ValueError(
+            f"{link} already exists and is not this persona; not replacing it. "
+            f"Rename the generated persona, or remove {link} yourself."
+        )
+
+    try:
+        os.symlink(teacher, link, target_is_directory=True)
+    except OSError:
+        if os.name != "nt":
+            raise
+        import _winapi  # symlinks need a privilege on Windows; junctions do not
+
+        _winapi.CreateJunction(str(teacher), str(link))
+
+    return {
+        "registered": str(link),
+        "target": str(teacher),
+        "invoke": f"/{teacher.name}",
+        "already_registered": False,
+        # Claude Code watches skill directories that existed when the session
+        # started; a skills directory created now is seen after a restart.
+        "restart_required": created_skills_dir,
+    }
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         description="Build a create-master persona from an explicit generation spec"
@@ -320,15 +390,29 @@ def main(argv: list[str] | None = None) -> int:
         action="store_true",
         help="run a deterministic no-network generation smoke",
     )
-    parser.add_argument("--output", required=True, help="master output directory")
+    modes.add_argument(
+        "--register",
+        metavar="TEACHER_DIR",
+        help="link a generated persona into --skills-dir so it can be invoked",
+    )
+    parser.add_argument("--output", help="master output directory (with --spec / --offline-smoke)")
+    parser.add_argument(
+        "--skills-dir",
+        default=os.path.join("~", ".claude", "skills"),
+        help="skills directory to register into (with --register; default ~/.claude/skills)",
+    )
     args = parser.parse_args(argv)
+    if not args.register and not args.output:
+        parser.error("--output is required with --spec / --offline-smoke")
 
     try:
-        if args.offline_smoke:
-            spec = _offline_smoke_spec()
+        if args.register:
+            summary = register_teacher(args.register, args.skills_dir)
+        elif args.offline_smoke:
+            summary = build_from_spec(_offline_smoke_spec(), args.output)
         else:
             spec = json.loads(Path(args.spec).read_text(encoding="utf-8"))
-        summary = build_from_spec(spec, args.output)
+            summary = build_from_spec(spec, args.output)
     except (OSError, json.JSONDecodeError, ValueError) as exc:
         print(f"ERROR: {exc}", file=sys.stderr)
         return 1