diff --git a/openspec/changes/archive/2026-02-25-optimize-skills-structure/.openspec.yaml b/openspec/changes/archive/2026-02-25-optimize-skills-structure/.openspec.yaml
new file mode 100644
index 0000000..e331c97
--- /dev/null
+++ b/openspec/changes/archive/2026-02-25-optimize-skills-structure/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-25
diff --git a/openspec/changes/archive/2026-02-25-optimize-skills-structure/design.md b/openspec/changes/archive/2026-02-25-optimize-skills-structure/design.md
new file mode 100644
index 0000000..b7b1a46
--- /dev/null
+++ b/openspec/changes/archive/2026-02-25-optimize-skills-structure/design.md
@@ -0,0 +1,76 @@
+## Context
+
+当前项目包含 4 个 skills（lyxy-runner-python、lyxy-runner-js、lyxy-reader-office、lyxy-kb），每个 SKILL.md 文件内容在 200-300 行之间。根据 `document/the-complete-guide-to-building-skill.md` 中的渐进式披露原则，SKILL.md 应保持精简（建议 5000 字以内），详细文档应放在 `references/` 目录中。
+
+**当前状态**：
+- SKILL.md 包含完整的工作流程、示例、错误处理、最佳实践等所有内容
+- 无 references/ 目录结构
+- 每次 Claude 加载 skill 时需要处理全部内容
+
+## Goals / Non-Goals
+
+**Goals:**
+- 遵循三层渐进式披露结构：YAML 前置元数据 → SKILL.md 核心指令 → references/ 详细文档
+- 减少 skill 加载时的 token 消耗
+- 保持 lyxy-runner-python 和 lyxy-runner-js 的 description 宽泛性
+- 为 4 个现有 skills 创建 references/ 目录并迁移内容
+
+**Non-Goals:**
+- 不修改 skill 的功能逻辑
+- 不修改 scripts/ 目录中的可执行代码
+- 不新增 skill 或删除现有 skill
+
+## Decisions
+
+### 决策 1：三层结构内容划分
+
+| 层级 | 位置 | 内容 | 加载时机 |
+|-----|------|------|---------|
+| 第一层 | YAML 前置元数据 | name、description、compatibility | 始终加载到系统提示 |
+| 第二层 | SKILL.md 正文 | 核心工作流、关键命令、快速参考 | Claude 判断相关时加载 |
+| 第三层 | references/*.md | 详细示例、错误处理、最佳实践、API 参考 | 按需导航和发现 |
+
+**理由**：遵循官方指南的渐进式披露原则，最小化 token 消耗的同时保持完整能力。
+
+### 决策 2：SKILL.md 保留内容
+
+每个 SKILL.md 正文保留以下核心部分：
+1. **Purpose**：简要说明用途和关键依赖
+2. **When to Use**：适用/不适用场景（简化版）
+3. **Quick Reference**：核心命令表格或流程图
+4. **Workflow**：简化的执行步骤
+5. **References 链接**：指向 references/ 中详细文档的链接
+
+**理由**：保留足够信息让 Claude 完成任务，详细内容按需加载。
+
+### 决策 3：references/ 目录结构
+
+```
+references/
+├── examples.md          # 详细示例
+├── error-handling.md    # 错误处理和故障排除
+├── best-practices.md    # 最佳实践和注意事项
+└── api-reference.md     # API/命令参数详细说明（可选）
+```
+
+**理由**：按主题分类，便于 Claude 按需定位和加载。
+
+### 决策 4：Description 格式
+
+采用统一格式：`[做什么] + [何时使用] + [关键能力]`
+
+- lyxy-runner-python：保持 "Any task that requires Python processing should use this skill."（宽泛）
+- lyxy-runner-js：保持 "Any task that requires Javascript/Typescript processing should use this skill."（宽泛）
+- lyxy-reader-office：保持当前描述，已包含具体文件类型和操作
+- lyxy-kb：可优化添加用户触发短语
+
+**理由**：runner skills 需要宽泛以匹配所有相关任务，reader/kb skills 可以更具体以精准触发。
+
+## Risks / Trade-offs
+
+| 风险 | 缓解措施 |
+|-----|---------|
+| references/ 文件未被 Claude 发现 | 在 SKILL.md 中明确列出 references/ 文件并说明用途 |
+| 拆分后信息不完整 | 核心工作流程保留在 SKILL.md，确保基本任务可完成 |
+| 迁移过程中遗漏内容 | 逐个 skill 处理，对比前后内容确保完整性 |
+| 文件数量增加 | references/ 文件按需加载，不影响初始 token 消耗 |
diff --git a/openspec/changes/archive/2026-02-25-optimize-skills-structure/proposal.md b/openspec/changes/archive/2026-02-25-optimize-skills-structure/proposal.md
new file mode 100644
index 0000000..0346d66
--- /dev/null
+++ b/openspec/changes/archive/2026-02-25-optimize-skills-structure/proposal.md
@@ -0,0 +1,30 @@
+## Why
+
+当前 skills 的 SKILL.md 文件内容较长（200-300 行），未遵循渐进式披露（Progressive Disclosure）原则。根据 skill 编写指南，应采用三层结构：YAML 前置元数据（触发判断）→ SKILL.md 正文（核心指令）→ references/（详细文档）。这样可以减少 token 消耗，提高 Claude 的响应效率。
+
+## What Changes
+
+- **结构优化**：为每个 skill 创建 `references/` 目录，将详细文档、示例、错误处理等内容从 SKILL.md 正文移至 references/
+- **SKILL.md 精简**：保留核心工作流程和关键指令，将详细说明改为链接到 references/ 中的文档
+- **Description 优化**：确保 description 同时包含「做什么」和「何时使用」两部分，便于 Claude 判断是否加载
+- **lyxy-runner-python/js 保持宽泛**：这两个 runner skill 的 description 需要保持宽泛，以便匹配所有 Python/JS 处理任务
+
+## Capabilities
+
+### New Capabilities
+
+- `skill-progressive-disclosure`: 定义 skill 渐进式披露的三层结构规范，包括 YAML 前置元数据、SKILL.md 正文、references/ 目录的职责划分和内容组织方式
+
+### Modified Capabilities
+
+（无现有 spec 需要修改）
+
+## Impact
+
+- **文件结构变更**：每个 skill 目录新增 `references/` 子目录
+- **SKILL.md 重构**：4 个 skills 的 SKILL.md 文件需要精简，详细内容迁移到 references/
+  - `skills/lyxy-runner-python/SKILL.md`
+  - `skills/lyxy-runner-js/SKILL.md`
+  - `skills/lyxy-reader-office/SKILL.md`
+  - `skills/lyxy-kb/SKILL.md`
+- **向后兼容**：功能不变，仅优化文档结构，**无破坏性变更**
diff --git a/openspec/changes/archive/2026-02-25-optimize-skills-structure/specs/skill-progressive-disclosure/spec.md b/openspec/changes/archive/2026-02-25-optimize-skills-structure/specs/skill-progressive-disclosure/spec.md
new file mode 100644
index 0000000..6bbfe99
--- /dev/null
+++ b/openspec/changes/archive/2026-02-25-optimize-skills-structure/specs/skill-progressive-disclosure/spec.md
@@ -0,0 +1,77 @@
+## ADDED Requirements
+
+### Requirement: 三层渐进式披露结构
+
+每个 skill 目录 SHALL 采用三层渐进式披露结构，按加载时机分为：第一层（YAML 前置元数据）、第二层（SKILL.md 正文）、第三层（references/ 目录）。
+
+#### Scenario: skill 目录包含完整三层结构
+- **WHEN** 检查任意 skill 目录结构
+- **THEN** 目录 SHALL 包含 SKILL.md 文件和 references/ 子目录
+
+#### Scenario: 第一层始终加载
+- **WHEN** Claude 启动会话时
+- **THEN** 所有 skill 的 YAML 前置元数据 SHALL 被加载到系统提示中
+
+### Requirement: YAML 前置元数据内容规范
+
+YAML 前置元数据 SHALL 仅包含触发判断所需的最小信息，使 Claude 能够判断何时使用该 skill。
+
+#### Scenario: 必需字段
+- **WHEN** 编写 SKILL.md 的 YAML 前置元数据
+- **THEN** SHALL 包含 name 和 description 字段
+
+#### Scenario: description 格式
+- **WHEN** 编写 description 字段
+- **THEN** SHALL 同时包含「做什么」和「何时使用」两部分信息
+
+#### Scenario: description 长度限制
+- **WHEN** 检查 description 字段
+- **THEN** 内容 SHALL 少于 1024 个字符
+
+#### Scenario: runner skill 的 description 宽泛性
+- **WHEN** skill 用途为通用脚本执行（如 Python/JavaScript runner）
+- **THEN** description SHALL 保持宽泛，以匹配所有相关处理任务
+
+### Requirement: SKILL.md 正文内容规范
+
+SKILL.md 正文 SHALL 包含核心工作流程和关键指令，保持精简以减少 token 消耗。
+
+#### Scenario: SKILL.md 必需章节
+- **WHEN** 编写 SKILL.md 正文
+- **THEN** SHALL 包含以下章节：Purpose、When to Use、Quick Reference、Workflow、References 链接
+
+#### Scenario: SKILL.md 长度建议
+- **WHEN** 检查 SKILL.md 总字数
+- **THEN** 建议控制在 5000 字以内（含 YAML 前置元数据）
+
+#### Scenario: 详细内容迁移
+- **WHEN** SKILL.md 包含详细示例、完整错误处理、最佳实践等冗长内容
+- **THEN** 这些内容 SHALL 迁移到 references/ 目录，SKILL.md 中保留链接引用
+
+### Requirement: references 目录结构规范
+
+每个 skill SHALL 包含 references/ 子目录，用于存放按需加载的详细文档。
+
+#### Scenario: references 目录存在性
+- **WHEN** 检查 skill 目录结构
+- **THEN** SHALL 存在 references/ 子目录
+
+#### Scenario: references 文件分类
+- **WHEN** 组织 references/ 目录内容
+- **THEN** SHALL 按主题分类为独立的 markdown 文件，如 examples.md、error-handling.md、best-practices.md
+
+#### Scenario: SKILL.md 引用 references
+- **WHEN** SKILL.md 需要引用详细文档
+- **THEN** SHALL 在 SKILL.md 中明确列出 references/ 中的文件并说明用途
+
+### Requirement: 内容迁移完整性
+
+从 SKILL.md 迁移内容到 references/ 时，SHALL 确保所有原有信息被完整保留。
+
+#### Scenario: 迁移前后对比
+- **WHEN** 完成单个 skill 的内容迁移
+- **THEN** references/ 中的文件 SHALL 包含原 SKILL.md 中被移除的所有详细内容
+
+#### Scenario: 功能不变性
+- **WHEN** 完成结构优化后
+- **THEN** skill 的功能逻辑 SHALL 保持不变，仅文档结构发生变化
diff --git a/openspec/changes/archive/2026-02-25-optimize-skills-structure/tasks.md b/openspec/changes/archive/2026-02-25-optimize-skills-structure/tasks.md
new file mode 100644
index 0000000..fca4d88
--- /dev/null
+++ b/openspec/changes/archive/2026-02-25-optimize-skills-structure/tasks.md
@@ -0,0 +1,45 @@
+## 1. lyxy-runner-python 结构优化
+
+- [x] 1.1 创建 `skills/lyxy-runner-python/references/` 目录
+- [x] 1.2 提取示例代码到 `references/examples.md`
+- [x] 1.3 提取错误处理内容到 `references/error-handling.md`
+- [x] 1.4 提取最佳实践和注意事项到 `references/best-practices.md`
+- [x] 1.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
+- [x] 1.6 在 SKILL.md 末尾添加 References 链接章节
+- [x] 1.7 验证 description 保持宽泛（"Any task that requires Python processing..."）
+
+## 2. lyxy-runner-js 结构优化
+
+- [x] 2.1 创建 `skills/lyxy-runner-js/references/` 目录
+- [x] 2.2 提取示例代码到 `references/examples.md`
+- [x] 2.3 提取错误处理内容到 `references/error-handling.md`
+- [x] 2.4 提取最佳实践和输出处理到 `references/best-practices.md`
+- [x] 2.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
+- [x] 2.6 在 SKILL.md 末尾添加 References 链接章节
+- [x] 2.7 验证 description 保持宽泛（"Any task that requires Javascript/Typescript processing..."）
+
+## 3. lyxy-reader-office 结构优化
+
+- [x] 3.1 创建 `skills/lyxy-reader-office/references/` 目录
+- [x] 3.2 提取详细示例到 `references/examples.md`
+- [x] 3.3 提取解析器说明和依赖安装到 `references/parsers.md`
+- [x] 3.4 提取错误处理和限制说明到 `references/error-handling.md`
+- [x] 3.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
+- [x] 3.6 在 SKILL.md 末尾添加 References 链接章节
+
+## 4. lyxy-kb 结构优化
+
+- [x] 4.1 创建 `skills/lyxy-kb/references/` 目录
+- [x] 4.2 提取目录结构和文件格式详细说明到 `references/structure.md`
+- [x] 4.3 提取文档生命周期和处理策略到 `references/workflow.md`
+- [x] 4.4 提取渐进式查询策略到 `references/query-strategy.md`
+- [x] 4.5 精简 SKILL.md，保留 Purpose、When to Use、Quick Reference、Workflow 章节
+- [x] 4.6 在 SKILL.md 末尾添加 References 链接章节
+- [x] 4.7 优化 description 添加用户触发短语
+
+## 5. 验证与收尾
+
+- [x] 5.1 对比每个 skill 的原始 SKILL.md 和重构后内容，确保信息完整
+- [x] 5.2 验证每个 skill 的 references/ 目录包含必要文件
+- [x] 5.3 验证每个 SKILL.md 的 References 章节正确链接到 references/ 文件
+- [x] 5.4 验证所有 description 符合格式要求（<1024 字符）
diff --git a/openspec/specs/skill-progressive-disclosure/spec.md b/openspec/specs/skill-progressive-disclosure/spec.md
new file mode 100644
index 0000000..0629028
--- /dev/null
+++ b/openspec/specs/skill-progressive-disclosure/spec.md
@@ -0,0 +1,83 @@
+# skill-progressive-disclosure
+
+## Purpose
+
+定义 skill 的渐进式披露（Progressive Disclosure）结构规范，将 skill 内容按加载时机分为三层：YAML 前置元数据、SKILL.md 正文、references/ 详细文档。通过分层加载减少 token 消耗，提高 Claude 的响应效率。
+
+## Requirements
+
+### Requirement: 三层渐进式披露结构
+
+每个 skill 目录 SHALL 采用三层渐进式披露结构，按加载时机分为：第一层（YAML 前置元数据）、第二层（SKILL.md 正文）、第三层（references/ 目录）。
+
+#### Scenario: skill 目录包含完整三层结构
+- **WHEN** 检查任意 skill 目录结构
+- **THEN** 目录 SHALL 包含 SKILL.md 文件和 references/ 子目录
+
+#### Scenario: 第一层始终加载
+- **WHEN** Claude 启动会话时
+- **THEN** 所有 skill 的 YAML 前置元数据 SHALL 被加载到系统提示中
+
+### Requirement: YAML 前置元数据内容规范
+
+YAML 前置元数据 SHALL 仅包含触发判断所需的最小信息，使 Claude 能够判断何时使用该 skill。
+
+#### Scenario: 必需字段
+- **WHEN** 编写 SKILL.md 的 YAML 前置元数据
+- **THEN** SHALL 包含 name 和 description 字段
+
+#### Scenario: description 格式
+- **WHEN** 编写 description 字段
+- **THEN** SHALL 同时包含「做什么」和「何时使用」两部分信息
+
+#### Scenario: description 长度限制
+- **WHEN** 检查 description 字段
+- **THEN** 内容 SHALL 少于 1024 个字符
+
+#### Scenario: runner skill 的 description 宽泛性
+- **WHEN** skill 用途为通用脚本执行（如 Python/JavaScript runner）
+- **THEN** description SHALL 保持宽泛，以匹配所有相关处理任务
+
+### Requirement: SKILL.md 正文内容规范
+
+SKILL.md 正文 SHALL 包含核心工作流程和关键指令，保持精简以减少 token 消耗。
+
+#### Scenario: SKILL.md 必需章节
+- **WHEN** 编写 SKILL.md 正文
+- **THEN** SHALL 包含以下章节：Purpose、When to Use、Quick Reference、Workflow、References 链接
+
+#### Scenario: SKILL.md 长度建议
+- **WHEN** 检查 SKILL.md 总字数
+- **THEN** 建议控制在 5000 字以内（含 YAML 前置元数据）
+
+#### Scenario: 详细内容迁移
+- **WHEN** SKILL.md 包含详细示例、完整错误处理、最佳实践等冗长内容
+- **THEN** 这些内容 SHALL 迁移到 references/ 目录，SKILL.md 中保留链接引用
+
+### Requirement: references 目录结构规范
+
+每个 skill SHALL 包含 references/ 子目录，用于存放按需加载的详细文档。
+
+#### Scenario: references 目录存在性
+- **WHEN** 检查 skill 目录结构
+- **THEN** SHALL 存在 references/ 子目录
+
+#### Scenario: references 文件分类
+- **WHEN** 组织 references/ 目录内容
+- **THEN** SHALL 按主题分类为独立的 markdown 文件，如 examples.md、error-handling.md、best-practices.md
+
+#### Scenario: SKILL.md 引用 references
+- **WHEN** SKILL.md 需要引用详细文档
+- **THEN** SHALL 在 SKILL.md 中明确列出 references/ 中的文件并说明用途
+
+### Requirement: 内容迁移完整性
+
+从 SKILL.md 迁移内容到 references/ 时，SHALL 确保所有原有信息被完整保留。
+
+#### Scenario: 迁移前后对比
+- **WHEN** 完成单个 skill 的内容迁移
+- **THEN** references/ 中的文件 SHALL 包含原 SKILL.md 中被移除的所有详细内容
+
+#### Scenario: 功能不变性
+- **WHEN** 完成结构优化后
+- **THEN** skill 的功能逻辑 SHALL 保持不变，仅文档结构发生变化
diff --git a/skills/lyxy-kb/SKILL.md b/skills/lyxy-kb/SKILL.md
index f97bfc8..6ea653e 100644
--- a/skills/lyxy-kb/SKILL.md
+++ b/skills/lyxy-kb/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: lyxy-kb
-description: 基于文件的个人知识库管理 skill，提供知识项目的目录结构规范、文档解析入库、渐进式问答等底层能力定义。配合 commands/lyxy-kb/ 下的 command 使用。
+description: 基于文件的个人知识库管理 skill。当用户说"创建知识库"、"初始化知识项目"、"入库文档"、"知识问答"、"基于文档回答"时使用。支持文档解析入库、增量摘要、渐进式问答。配合 /lyxy-kb-init、/lyxy-kb-ingest、/lyxy-kb-ask 等 command 使用。
 compatibility: 依赖 lyxy-reader-office skill 解析 office 文档（.docx/.pdf/.pptx/.xlsx），依赖 lyxy-runner-python skill 执行 Python 脚本。
 ---
 
@@ -30,7 +30,7 @@ compatibility: 依赖 lyxy-reader-office skill 解析 office 文档（.docx/.pdf
 - 需要跨多个知识项目关联查询
 - 需要多人协作或权限控制
 
-## 配套 Commands
+## Quick Reference
 
 | Command | 触发方式 | 说明 |
 |---------|----------|------|
@@ -39,255 +39,38 @@ compatibility: 依赖 lyxy-reader-office skill 解析 office 文档（.docx/.pdf
 | rebuild | `/lyxy-kb-rebuild <name>` | 全量重新生成 project.md |
 | ask | `/lyxy-kb-ask <name>` | 基于知识库进行会话问答 |
 
-## 项目名称规则
+## Workflow
 
-项目名称只允许使用以下字符：
-- 中文字符
-- 英文字母（a-z、A-Z）
-- 数字（0-9）
-- 短横线（-）
-- 下划线（_）
-
-**不允许包含空格或其他特殊字符。** 不符合规则时应提示用户修改。
-
-## 知识项目目录结构
-
-每个知识项目是当前工作目录（CWD）下的一个子目录，包含以下固定结构：
+### 知识项目目录结构
 
 ```
 <project-name>/
 ├── project.md          # 高度摘要 + 文件索引
 ├── manifest.json       # 增量追踪
-├── parsed/             # 解析后的 markdown（中间产物）
+├── parsed/             # 解析后的 markdown
 ├── sources/            # 待处理区（用户放入原始文档）
 └── archive/            # 原始文件备份（带时间戳）
 ```
 
-### 各目录/文件职责
+### 基本工作流程
 
-| 路径 | 职责 |
-|------|------|
-| `project.md` | 项目的高度摘要和文件索引，作为问答时的入口文件 |
-| `manifest.json` | 记录已处理文件的元信息，用于增量检测和版本追踪 |
-| `parsed/` | 存放解析后的 markdown 文件，便于大模型读取分析 |
-| `sources/` | 用户放入待处理文档的目录，解析后文件会被移走 |
-| `archive/` | 原始文件的备份，每个文件都带时间戳后缀 |
+1. **初始化**：使用 `/lyxy-kb-init <name>` 创建项目目录结构
+2. **入库**：将文档放入 `sources/`，执行 `/lyxy-kb-ingest <name>`
+3. **问答**：使用 `/lyxy-kb-ask <name>` 基于知识库回答问题
 
-### 结构完整性验证
-
-执行任何 command（ingest / rebuild / ask）时，必须先验证项目目录结构是否完整，即以下 5 项是否全部存在：
-- `<project-name>/project.md`
-- `<project-name>/manifest.json`
-- `<project-name>/parsed/`
-- `<project-name>/sources/`
-- `<project-name>/archive/`
-
-若不完整，提示用户先执行 `/lyxy-kb-init <project-name>`，终止当前操作。
-
-## project.md 格式规范
-
-```markdown
-# <项目名称>
-
-## 概述
-（高度总结的项目信息，几百字以内）
-
-## 关键信息
-（从所有文档中提炼的核心要点）
-
-## 文件索引
-
-| 文件名 | 解析文件 | 最新归档 | 摘要 |
-|--------|----------|----------|------|
-| 需求文档 | parsed/需求文档.md | archive/需求文档_202602181600.docx | 简要摘要... |
-
-## 更新记录
-- 2026-02-18 16:00: 解析 需求文档.docx
-```
-
-### 更新策略
-
-**增量追加**（默认，由 ingest 触发）：
-- 新文件：在文件索引表追加新行，在更新记录追加条目
-- 已有文件更新：覆盖文件索引表中对应行的最新归档路径和摘要
-- 概述和关键信息部分**不**自动更新
-
-**全量重写**（由 rebuild 触发）：
-- 读取所有 parsed/*.md 文件
-- 重新生成概述、关键信息、文件索引
-- 保留历史更新记录，追加本次 rebuild 条目
-
-## manifest.json 结构
-
-```json
-{
-  "project": "<项目名称>",
-  "created_at": "2026-02-18T16:00",
-  "last_ingest": "2026-02-18T17:25",
-  "files": [
-    {
-      "name": "需求文档",
-      "ext": ".docx",
-      "parsed": "parsed/需求文档.md",
-      "versions": [
-        {
-          "archived": "archive/需求文档_202602181600.docx",
-          "hash": "sha256:abc123...",
-          "ingested_at": "2026-02-18T16:00"
-        }
-      ]
-    }
-  ]
-}
-```
-
-### 字段说明
-
-| 字段 | 说明 |
-|------|------|
-| `project` | 项目名称 |
-| `created_at` | 项目创建时间 |
-| `last_ingest` | 最近一次 ingest 的时间 |
-| `files[].name` | 文件名（不含扩展名） |
-| `files[].ext` | 原始文件扩展名 |
-| `files[].parsed` | 解析产物的相对路径 |
-| `files[].versions` | 版本历史数组 |
-| `files[].versions[].archived` | 归档文件的相对路径 |
-| `files[].versions[].hash` | 文件内容的 SHA-256 哈希（使用 `sha256sum` 命令计算） |
-| `files[].versions[].ingested_at` | 该版本的入库时间 |
-
-## 文件类型解析策略
-
-| 文件类型 | 解析方式 |
-|----------|----------|
-| `.docx`, `.pdf`, `.pptx`, `.xlsx` | 使用名为 **lyxy-reader-office** 的 skill 解析 |
-| 其他所有文件（`.md`, `.txt`, `.csv`, `.json`, `.xml`, `.yaml`, `.yml`, `.log`, `.html` 等） | 直接读取文件内容 |
-
-### Office 文档解析
-
-解析 office 文档时，必须查找当前环境中名为 **lyxy-reader-office** 的 skill，阅读其 SKILL.md 获取具体的执行方式和命令。
-
-**如果环境中不存在 lyxy-reader-office skill，且没有其他可替代的文档解析 skill，则提示用户无法处理 office 文档，中止整个 ingest 流程。**
-
-### sources/ 扫描规则
-
-扫描 sources/ 时**递归检查所有子目录**中的文件。parsed 产物的路径仍为 `parsed/<文件名>.md`（扁平化存放），不保留 sources 中的子目录结构。
-
-### 空文件处理
-
-sources/ 中 0 字节的空文件应**跳过处理**，不解析、不归档、不更新 manifest。处理完成后向用户列出被跳过的空文件列表，提示用户检查。
-
-### 解析失败处理
-
-如果某个文件解析失败（如文档损坏、解析器报错），该文件**保留在 sources/ 中不移动**，报告错误信息，继续处理其他文件。
-
-## parsed 文件元信息标记
-
-每个 parsed markdown 文件头部必须包含元信息注释：
-
-```markdown
-<!-- source: 技术方案.pdf -->
-<!-- archived: archive/技术方案_202602181725.pdf -->
-<!-- parsed_at: 2026-02-18 17:25 -->
-
-# 技术方案
-（文档正文内容...）
-```
-
-| 元信息 | 说明 |
-|--------|------|
-| `source` | 原始文件名（含扩展名） |
-| `archived` | 对应的归档文件相对路径 |
-| `parsed_at` | 解析时间（YYYY-MM-DD HH:mm 格式） |
-
-## 文档生命周期
-
-```
-用户放入 sources/（支持子目录）
-       │
-       ▼
-   检查文件（跳过空文件、检测冲突）
-       │
-       ▼
-   解析文件内容（失败则保留在 sources/）
-       │
-       ├──▶ 写入 parsed/<文件名>.md（含头部元信息）
-       │
-       ├──▶ 移动原始文件到 archive/<文件名_YYYYMMDDHHmm>.<ext>
-       │
-       ├──▶ 更新 manifest.json
-       │
-       └──▶ 增量更新 project.md（追加文件索引和更新记录）
-```
-
-### 归档命名规则
-
-所有进入 archive 的文件都必须带时间戳后缀，格式为 `<文件名_YYYYMMDDHHmm>.<扩展名>`，即使只有一个版本。
-
-示例：
-- `需求文档.docx` → `archive/需求文档_202602181600.docx`
-- `技术方案.pdf`（第二次入库）→ `archive/技术方案_202602181725.pdf`
-
-### 同名文件更新
-
-同名同扩展名的文件再次入库时：
-- `parsed/` 中的 markdown 文件被覆盖为最新版本
-- `archive/` 中保留所有历史版本（每个版本独立的时间戳文件）
-- `manifest.json` 中该文件条目的 `versions` 数组追加新版本记录
-
-## 同名不同扩展名冲突检测
-
-因为 parsed 产物以文件名（不含扩展名）+ `.md` 命名，同名不同扩展名的文件会产生冲突。
-
-### 检测规则
-
-1. **sources/ 内部检测**：扫描 sources/ 中所有文件（含子目录），如果存在同名但不同扩展名的文件（如 `技术方案.pdf` 和 `技术方案.docx`），拒绝处理并提示用户重命名
-2. **与已入库文件检测**：将 sources/ 中文件的名称（不含扩展名）与 manifest.json 中已有记录对比，如果名称相同但扩展名不同，拒绝处理并提示用户重命名
-
-### 处理方式
-
-冲突文件不予处理，保留在 sources/ 中，提示用户重命名后重新执行 ingest。非冲突文件正常处理。
-
-## 渐进式查询策略
-
-问答时采用分层加载策略，节省 token：
+### 渐进式查询策略
 
 1. **读取 project.md**：获取项目概述和文件索引（低 token 开销）
-2. **判断相关文件**：根据用户问题和文件索引中的摘要，判断需要查阅哪些 parsed 文件
+2. **判断相关文件**：根据用户问题和摘要判断需要查阅哪些 parsed 文件
 3. **按需加载**：读取相关 parsed 文件的全部或部分内容
 4. **回答并标注来源**：基于获取的信息回答问题
 
-### 来源引用格式
+## References
 
-回答中引用具体信息时，使用以下格式标注来源：
+详细文档请参阅 `references/` 目录：
 
-```
-根据《文件名》(parsed/文件名.md)，...
-```
-
-多个来源时分别标注各信息点的来源文件。
-
-### 无相关信息
-
-当知识库中未找到与用户问题相关的信息时，明确告知用户，不编造答案。
-
-### 空知识库
-
-如果 project.md 文件索引为空（尚无已入库文件），应告知用户知识库为空，建议先使用 `/lyxy-kb-ingest` 入库文档。
-
-## Notes
-
-### 依赖关系
-
-| 依赖 | 用途 |
+| 文件 | 内容 |
 |------|------|
-| lyxy-reader-office | 解析 .docx、.pdf、.pptx、.xlsx 文件为 markdown |
-| lyxy-runner-python | 通过 uv 执行 lyxy-reader-office 的 Python 解析脚本 |
-
-### 限制
-
-- 不支持向量化语义搜索
-- 不支持跨知识项目关联查询
-- 不支持文档版本对比或 diff
-- 不支持多用户协作或权限控制
-- 大量文件全量重写时 token 消耗较高
+| `references/structure.md` | 目录结构规范、project.md 格式、manifest.json 结构、parsed 元信息标记 |
+| `references/workflow.md` | 文档生命周期、归档命名规则、冲突检测、解析策略 |
+| `references/query-strategy.md` | 渐进式查询策略、来源引用格式、依赖关系、限制说明 |
diff --git a/skills/lyxy-kb/references/query-strategy.md b/skills/lyxy-kb/references/query-strategy.md
new file mode 100644
index 0000000..dd786c1
--- /dev/null
+++ b/skills/lyxy-kb/references/query-strategy.md
@@ -0,0 +1,43 @@
+# 渐进式查询策略
+
+## 分层加载策略
+
+问答时采用分层加载策略，节省 token：
+
+1. **读取 project.md**：获取项目概述和文件索引（低 token 开销）
+2. **判断相关文件**：根据用户问题和文件索引中的摘要，判断需要查阅哪些 parsed 文件
+3. **按需加载**：读取相关 parsed 文件的全部或部分内容
+4. **回答并标注来源**：基于获取的信息回答问题
+
+## 来源引用格式
+
+回答中引用具体信息时，使用以下格式标注来源：
+
+```
+根据《文件名》(parsed/文件名.md)，...
+```
+
+多个来源时分别标注各信息点的来源文件。
+
+## 无相关信息
+
+当知识库中未找到与用户问题相关的信息时，明确告知用户，不编造答案。
+
+## 空知识库
+
+如果 project.md 文件索引为空（尚无已入库文件），应告知用户知识库为空，建议先使用 `/lyxy-kb-ingest` 入库文档。
+
+## 依赖关系
+
+| 依赖 | 用途 |
+|------|------|
+| lyxy-reader-office | 解析 .docx、.pdf、.pptx、.xlsx 文件为 markdown |
+| lyxy-runner-python | 通过 uv 执行 lyxy-reader-office 的 Python 解析脚本 |
+
+## 限制
+
+- 不支持向量化语义搜索
+- 不支持跨知识项目关联查询
+- 不支持文档版本对比或 diff
+- 不支持多用户协作或权限控制
+- 大量文件全量重写时 token 消耗较高
diff --git a/skills/lyxy-kb/references/structure.md b/skills/lyxy-kb/references/structure.md
new file mode 100644
index 0000000..6eeac41
--- /dev/null
+++ b/skills/lyxy-kb/references/structure.md
@@ -0,0 +1,125 @@
+# 知识项目目录结构
+
+## 目录结构
+
+每个知识项目是当前工作目录（CWD）下的一个子目录，包含以下固定结构：
+
+```
+<project-name>/
+├── project.md          # 高度摘要 + 文件索引
+├── manifest.json       # 增量追踪
+├── parsed/             # 解析后的 markdown（中间产物）
+├── sources/            # 待处理区（用户放入原始文档）
+└── archive/            # 原始文件备份（带时间戳）
+```
+
+### 各目录/文件职责
+
+| 路径 | 职责 |
+|------|------|
+| `project.md` | 项目的高度摘要和文件索引，作为问答时的入口文件 |
+| `manifest.json` | 记录已处理文件的元信息，用于增量检测和版本追踪 |
+| `parsed/` | 存放解析后的 markdown 文件，便于大模型读取分析 |
+| `sources/` | 用户放入待处理文档的目录，解析后文件会被移走 |
+| `archive/` | 原始文件的备份，每个文件都带时间戳后缀 |
+
+### 结构完整性验证
+
+执行任何 command（ingest / rebuild / ask）时，必须先验证项目目录结构是否完整，即以下 5 项是否全部存在：
+- `<project-name>/project.md`
+- `<project-name>/manifest.json`
+- `<project-name>/parsed/`
+- `<project-name>/sources/`
+- `<project-name>/archive/`
+
+若不完整，提示用户先执行 `/lyxy-kb-init <project-name>`，终止当前操作。
+
+## 项目名称规则
+
+项目名称只允许使用以下字符：
+- 中文字符
+- 英文字母（a-z、A-Z）
+- 数字（0-9）
+- 短横线（-）
+- 下划线（_）
+
+**不允许包含空格或其他特殊字符。** 不符合规则时应提示用户修改。
+
+## project.md 格式规范
+
+```markdown
+# <项目名称>
+
+## 概述
+（高度总结的项目信息，几百字以内）
+
+## 关键信息
+（从所有文档中提炼的核心要点）
+
+## 文件索引
+
+| 文件名 | 解析文件 | 最新归档 | 摘要 |
+|--------|----------|----------|------|
+| 需求文档 | parsed/需求文档.md | archive/需求文档_202602181600.docx | 简要摘要... |
+
+## 更新记录
+- 2026-02-18 16:00: 解析 需求文档.docx
+```
+
+## manifest.json 结构
+
+```json
+{
+  "project": "<项目名称>",
+  "created_at": "2026-02-18T16:00",
+  "last_ingest": "2026-02-18T17:25",
+  "files": [
+    {
+      "name": "需求文档",
+      "ext": ".docx",
+      "parsed": "parsed/需求文档.md",
+      "versions": [
+        {
+          "archived": "archive/需求文档_202602181600.docx",
+          "hash": "sha256:abc123...",
+          "ingested_at": "2026-02-18T16:00"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 字段说明
+
+| 字段 | 说明 |
+|------|------|
+| `project` | 项目名称 |
+| `created_at` | 项目创建时间 |
+| `last_ingest` | 最近一次 ingest 的时间 |
+| `files[].name` | 文件名（不含扩展名） |
+| `files[].ext` | 原始文件扩展名 |
+| `files[].parsed` | 解析产物的相对路径 |
+| `files[].versions` | 版本历史数组 |
+| `files[].versions[].archived` | 归档文件的相对路径 |
+| `files[].versions[].hash` | 文件内容的 SHA-256 哈希（使用 `sha256sum` 命令计算） |
+| `files[].versions[].ingested_at` | 该版本的入库时间 |
+
+## parsed 文件元信息标记
+
+每个 parsed markdown 文件头部必须包含元信息注释：
+
+```markdown
+<!-- source: 技术方案.pdf -->
+<!-- archived: archive/技术方案_202602181725.pdf -->
+<!-- parsed_at: 2026-02-18 17:25 -->
+
+# 技术方案
+（文档正文内容...）
+```
+
+| 元信息 | 说明 |
+|--------|------|
+| `source` | 原始文件名（含扩展名） |
+| `archived` | 对应的归档文件相对路径 |
+| `parsed_at` | 解析时间（YYYY-MM-DD HH:mm 格式） |
diff --git a/skills/lyxy-kb/references/workflow.md b/skills/lyxy-kb/references/workflow.md
new file mode 100644
index 0000000..6f20439
--- /dev/null
+++ b/skills/lyxy-kb/references/workflow.md
@@ -0,0 +1,86 @@
+# 文档生命周期和处理策略
+
+## 文档生命周期
+
+```
+用户放入 sources/（支持子目录）
+       │
+       ▼
+   检查文件（跳过空文件、检测冲突）
+       │
+       ▼
+   解析文件内容（失败则保留在 sources/）
+       │
+       ├──▶ 写入 parsed/<文件名>.md（含头部元信息）
+       │
+       ├──▶ 移动原始文件到 archive/<文件名_YYYYMMDDHHmm>.<ext>
+       │
+       ├──▶ 更新 manifest.json
+       │
+       └──▶ 增量更新 project.md（追加文件索引和更新记录）
+```
+
+## 归档命名规则
+
+所有进入 archive 的文件都必须带时间戳后缀，格式为 `<文件名_YYYYMMDDHHmm>.<扩展名>`，即使只有一个版本。
+
+示例：
+- `需求文档.docx` → `archive/需求文档_202602181600.docx`
+- `技术方案.pdf`（第二次入库）→ `archive/技术方案_202602181725.pdf`
+
+## 同名文件更新
+
+同名同扩展名的文件再次入库时：
+- `parsed/` 中的 markdown 文件被覆盖为最新版本
+- `archive/` 中保留所有历史版本（每个版本独立的时间戳文件）
+- `manifest.json` 中该文件条目的 `versions` 数组追加新版本记录
+
+## 同名不同扩展名冲突检测
+
+因为 parsed 产物以文件名（不含扩展名）+ `.md` 命名，同名不同扩展名的文件会产生冲突。
+
+### 检测规则
+
+1. **sources/ 内部检测**：扫描 sources/ 中所有文件（含子目录），如果存在同名但不同扩展名的文件（如 `技术方案.pdf` 和 `技术方案.docx`），拒绝处理并提示用户重命名
+2. **与已入库文件检测**：将 sources/ 中文件的名称（不含扩展名）与 manifest.json 中已有记录对比，如果名称相同但扩展名不同，拒绝处理并提示用户重命名
+
+### 处理方式
+
+冲突文件不予处理，保留在 sources/ 中，提示用户重命名后重新执行 ingest。非冲突文件正常处理。
+
+## 文件类型解析策略
+
+| 文件类型 | 解析方式 |
+|----------|----------|
+| `.docx`, `.pdf`, `.pptx`, `.xlsx` | 使用名为 **lyxy-reader-office** 的 skill 解析 |
+| 其他所有文件（`.md`, `.txt`, `.csv`, `.json`, `.xml`, `.yaml`, `.yml`, `.log`, `.html` 等） | 直接读取文件内容 |
+
+### Office 文档解析
+
+解析 office 文档时，必须查找当前环境中名为 **lyxy-reader-office** 的 skill，阅读其 SKILL.md 获取具体的执行方式和命令。
+
+**如果环境中不存在 lyxy-reader-office skill，且没有其他可替代的文档解析 skill，则提示用户无法处理 office 文档，中止整个 ingest 流程。**
+
+### sources/ 扫描规则
+
+扫描 sources/ 时**递归检查所有子目录**中的文件。parsed 产物的路径仍为 `parsed/<文件名>.md`（扁平化存放），不保留 sources 中的子目录结构。
+
+### 空文件处理
+
+sources/ 中 0 字节的空文件应**跳过处理**，不解析、不归档、不更新 manifest。处理完成后向用户列出被跳过的空文件列表，提示用户检查。
+
+### 解析失败处理
+
+如果某个文件解析失败（如文档损坏、解析器报错），该文件**保留在 sources/ 中不移动**，报告错误信息，继续处理其他文件。
+
+## 更新策略
+
+**增量追加**（默认，由 ingest 触发）：
+- 新文件：在文件索引表追加新行，在更新记录追加条目
+- 已有文件更新：覆盖文件索引表中对应行的最新归档路径和摘要
+- 概述和关键信息部分**不**自动更新
+
+**全量重写**（由 rebuild 触发）：
+- 读取所有 parsed/*.md 文件
+- 重新生成概述、关键信息、文件索引
+- 保留历史更新记录，追加本次 rebuild 条目
diff --git a/skills/lyxy-reader-office/SKILL.md b/skills/lyxy-reader-office/SKILL.md
index ee73976..fb87a92 100644
--- a/skills/lyxy-reader-office/SKILL.md
+++ b/skills/lyxy-reader-office/SKILL.md
@@ -14,21 +14,6 @@ compatibility: Requires Python 3.6+. DOCX/PPTX/XLSX 无需额外依赖（XML 原
 
 **依赖选项**：此 skill 必须优先使用 lyxy-runner-python skill 执行，不可用时降级到直接 Python 执行。
 
-### 必须使用 lyxy-runner-python
-
-如果环境中存在 lyxy-runner-python skill，**必须**使用它来执行 parser.py 脚本：
-- lyxy-runner-python 使用 uv 管理依赖，自动安装所需的第三方库
-- 环境隔离，不污染系统 Python
-- 跨平台兼容（Windows/macOS/Linux）
-
-### 降级到直接执行
-
-**仅当** lyxy-runner-python skill 不存在时，才降级到直接 Python 执行：
-- 需要用户手动安装依赖
-- DOCX/PPTX/XLSX 无需依赖也可通过 XML 原生解析工作
-- PDF 至少需要安装 pypdf
-- **禁止自动执行 pip install**，仅向用户提示安装建议
-
 ## When to Use
 
 任何需要读取或解析 .docx、.xlsx、.pptx、.pdf 文件内容的任务都应使用此 skill。
@@ -41,100 +26,12 @@ compatibility: Requires Python 3.6+. DOCX/PPTX/XLSX 无需额外依赖（XML 原
 - **内容搜索**：在文档中搜索关键词或模式
 - **PDF OCR**：对扫描版 PDF 启用 OCR 高精度解析
 
-### 不适用场景
-- 需要提取图片内容（仅支持纯文本）
-- 需要保留复杂的格式信息（字体、颜色、布局）
-- 需要编辑或修改文档
-- 需要处理 .doc、.xls、.ppt 等旧格式
-
 ### 触发词
+- 中文："读取/解析/打开 docx/word/xlsx/excel/pptx/pdf 文档"
+- 英文："read/parse/extract docx/word/xlsx/excel/pptx/powerpoint/pdf"
+- 文件扩展名：`.docx`、`.xlsx`、`.pptx`、`.pdf`
 
-**中文触发词**
-- "读取/解析/打开 docx/word 文档"
-- "读取/解析/打开 xlsx/excel 文件"
-- "读取/解析/打开 pptx/ppt 文件"
-- "读取/解析/打开 pdf 文件"
-
-**英文触发词**
-- "read/parse/extract docx/word/xlsx/excel/pptx/powerpoint/pdf"
-
-**文件扩展名**
-- `.docx`、`.xlsx`、`.pptx`、`.pdf`
-
-## Capabilities
-
-### 1. 全文转换为 Markdown
-将完整文档解析为 Markdown 格式，移除图片但保留文本格式（标题、列表、表格、粗体、斜体等）。
-
-各格式的输出特点：
-- **DOCX**：标准 Markdown 文档结构
-- **PPTX**：每张幻灯片以 `## Slide N` 为标题，幻灯片之间以 `---` 分隔
-- **XLSX**：以 `## SheetName` 区分工作表，数据以 Markdown 表格呈现
-- **PDF**：纯文本流，使用 `--high-res` 可启用 OCR 版面分析识别标题
-
-### 2. 获取文档元信息
-- 字数统计（`-c` 参数）
-- 行数统计（`-l` 参数）
-
-### 3. 标题列表提取
-提取文档中所有 1-6 级标题（`-t` 参数），按原始层级关系返回。
-
-### 4. 指定章节内容提取
-根据标题名称提取特定章节的完整内容（`-tc` 参数），包含上级标题链和所有下级内容。
-
-### 5. 正则表达式搜索
-在文档中搜索关键词或模式（`-s` 参数），支持自定义上下文行数（`-n` 参数，默认 2 行）。
-
-### 6. PDF OCR 高精度模式
-对 PDF 文件启用 OCR 版面分析（`--high-res` 参数），适用于扫描版 PDF 或需要识别标题层级的场景。
-
-## Execution
-
-### 详细用法参考
-
-**执行前请阅读 `scripts/README.md`**，其中包含：
-- 完整的命令行参数说明
-- 各格式的依赖安装指南（pip 和 uv 方式）
-- 解析器优先级和对比
-- 输出格式说明
-- 错误处理和常见问题
-
-### 基本语法
-
-```bash
-python parser.py <file_path> [options]
-```
-
-### 使用 lyxy-runner-python 执行（必须优先使用）
-
-```bash
-# DOCX - 推荐依赖
-uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
-
-# PPTX - 推荐依赖
-uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.pptx
-
-# XLSX - 推荐依赖
-uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.xlsx
-
-# PDF - 推荐依赖
-uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf
-
-# PDF OCR 高精度模式
-uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf --high-res
-```
-
-> **注意**：以上为最小推荐依赖，更多解析器依赖和完整安装命令请查阅 `scripts/README.md` 的安装部分。
-
-### 降级到直接 Python 执行
-
-仅当 lyxy-runner-python skill 不存在时使用：
-
-```bash
-python3 skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
-```
-
-### 互斥参数
+## Quick Reference
 
 | 参数 | 说明 |
 |------|------|
@@ -142,71 +39,36 @@ python3 skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
 | `-c` | 字数统计 |
 | `-l` | 行数统计 |
 | `-t` | 提取所有标题 |
-| `-tc <name>` | 提取指定标题的章节内容（name 不含 # 号） |
+| `-tc <name>` | 提取指定标题的章节内容 |
 | `-s <pattern>` | 正则表达式搜索 |
-| `-n <num>` | 与 `-s` 配合，指定上下文行数（默认 2） |
+| `-n <num>` | 与 `-s` 配合，指定上下文行数 |
 | `--high-res` | PDF 专用，启用 OCR 版面分析 |
 
-## Examples
+## Workflow
+
+1. **检查依赖**：优先使用 lyxy-runner-python，否则降级到直接 Python 执行
+2. **选择格式**：根据文件扩展名自动识别格式
+3. **执行解析**：调用 `scripts/parser.py` 并传入参数
+4. **输出结果**：返回 Markdown 格式内容或统计信息
+
+### 基本语法
 
-### 提取完整文档内容
 ```bash
-# DOCX
-uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/report.docx
+# 使用 lyxy-runner-python（推荐）
+uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
 
-# PPTX
-uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/slides.pptx
-
-# XLSX
-uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/data.xlsx
-
-# PDF
-uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/doc.pdf
+# 降级到直接执行
+python3 skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
 ```
 
-### 获取文档字数
-```bash
-uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -c /path/to/report.docx
-```
+## References
 
-### 提取所有标题
-```bash
-uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -t /path/to/report.docx
-```
+详细文档请参阅 `references/` 目录：
 
-### 提取指定章节
-```bash
-uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -tc "第一章" /path/to/report.docx
-```
+| 文件 | 内容 |
+|------|------|
+| `references/examples.md` | 各格式完整提取、字数统计、标题提取、章节提取、搜索等示例 |
+| `references/parsers.md` | 解析器说明、依赖安装、各格式输出特点、能力说明 |
+| `references/error-handling.md` | 限制说明、最佳实践、依赖执行策略 |
 
-### 搜索关键词
-```bash
-uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -s "关键词" -n 3 /path/to/report.docx
-```
-
-### PDF OCR 高精度解析
-```bash
-uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/scanned.pdf --high-res
-```
-
-## Notes
-
-### 多策略解析降级
-
-每种文件格式配备多个解析器，按优先级依次尝试，前一个失败自动回退到下一个。详细的解析器优先级和对比请查阅 `scripts/README.md`。
-
-### 限制
-
-- 不支持图片提取（仅纯文本）
-- 不支持复杂的格式保留（字体、颜色、布局等）
-- 不支持文档编辑或修改
-- 仅支持 .docx、.xlsx、.pptx、.pdf 格式（不支持 .doc、.xls、.ppt 等旧格式）
-- PDF 无内置 XML 原生解析，至少需要安装 pypdf
-
-### 最佳实践
-
-1. **必须优先使用 lyxy-runner-python**：如果环境中存在，必须使用 lyxy-runner-python 执行脚本
-2. **查阅 README**：详细参数、依赖安装、解析器对比等信息请阅读 `scripts/README.md`
-3. **大文件处理**：对于大文档，建议使用章节提取（`-tc`）或搜索（`-s`）来限制处理范围
-4. **PDF 标题**：PDF 是版面描述格式，默认不含语义化标题；需要标题层级时使用 `--high-res`
-5. **禁止自动安装**：降级到直接 Python 执行时，仅向用户提示安装依赖，不得自动执行 pip install
+> **详细用法**：请阅读 `scripts/README.md` 获取完整的命令行参数和依赖安装指南。
diff --git a/skills/lyxy-reader-office/references/error-handling.md b/skills/lyxy-reader-office/references/error-handling.md
new file mode 100644
index 0000000..75d5d44
--- /dev/null
+++ b/skills/lyxy-reader-office/references/error-handling.md
@@ -0,0 +1,41 @@
+# 错误处理和限制说明
+
+## 限制
+
+- 不支持图片提取（仅纯文本）
+- 不支持复杂的格式保留（字体、颜色、布局等）
+- 不支持文档编辑或修改
+- 仅支持 .docx、.xlsx、.pptx、.pdf 格式（不支持 .doc、.xls、.ppt 等旧格式）
+- PDF 无内置 XML 原生解析，至少需要安装 pypdf
+
+## 最佳实践
+
+1. **必须优先使用 lyxy-runner-python**：如果环境中存在，必须使用 lyxy-runner-python 执行脚本
+2. **查阅 README**：详细参数、依赖安装、解析器对比等信息请阅读 `scripts/README.md`
+3. **大文件处理**：对于大文档，建议使用章节提取（`-tc`）或搜索（`-s`）来限制处理范围
+4. **PDF 标题**：PDF 是版面描述格式，默认不含语义化标题；需要标题层级时使用 `--high-res`
+5. **禁止自动安装**：降级到直接 Python 执行时，仅向用户提示安装依赖，不得自动执行 pip install
+
+## 依赖执行策略
+
+### 必须使用 lyxy-runner-python
+
+如果环境中存在 lyxy-runner-python skill，**必须**使用它来执行 parser.py 脚本：
+- lyxy-runner-python 使用 uv 管理依赖，自动安装所需的第三方库
+- 环境隔离，不污染系统 Python
+- 跨平台兼容（Windows/macOS/Linux）
+
+### 降级到直接执行
+
+**仅当** lyxy-runner-python skill 不存在时，才降级到直接 Python 执行：
+- 需要用户手动安装依赖
+- DOCX/PPTX/XLSX 无需依赖也可通过 XML 原生解析工作
+- PDF 至少需要安装 pypdf
+- **禁止自动执行 pip install**，仅向用户提示安装建议
+
+## 不适用场景
+
+- 需要提取图片内容（仅支持纯文本）
+- 需要保留复杂的格式信息（字体、颜色、布局）
+- 需要编辑或修改文档
+- 需要处理 .doc、.xls、.ppt 等旧格式
diff --git a/skills/lyxy-reader-office/references/examples.md b/skills/lyxy-reader-office/references/examples.md
new file mode 100644
index 0000000..3c894f8
--- /dev/null
+++ b/skills/lyxy-reader-office/references/examples.md
@@ -0,0 +1,55 @@
+# 示例
+
+## 提取完整文档内容
+
+```bash
+# DOCX
+uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/report.docx
+
+# PPTX
+uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/slides.pptx
+
+# XLSX
+uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/data.xlsx
+
+# PDF
+uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/doc.pdf
+```
+
+## 获取文档字数
+
+```bash
+uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -c /path/to/report.docx
+```
+
+## 提取所有标题
+
+```bash
+uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -t /path/to/report.docx
+```
+
+## 提取指定章节
+
+```bash
+uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -tc "第一章" /path/to/report.docx
+```
+
+## 搜索关键词
+
+```bash
+uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py -s "关键词" -n 3 /path/to/report.docx
+```
+
+## PDF OCR 高精度解析
+
+```bash
+uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/scanned.pdf --high-res
+```
+
+## 降级到直接 Python 执行
+
+仅当 lyxy-runner-python skill 不存在时使用：
+
+```bash
+python3 skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
+```
diff --git a/skills/lyxy-reader-office/references/parsers.md b/skills/lyxy-reader-office/references/parsers.md
new file mode 100644
index 0000000..514f9c1
--- /dev/null
+++ b/skills/lyxy-reader-office/references/parsers.md
@@ -0,0 +1,58 @@
+# 解析器说明和依赖安装
+
+## 多策略解析降级
+
+每种文件格式配备多个解析器，按优先级依次尝试，前一个失败自动回退到下一个。
+
+详细的解析器优先级和对比请查阅 `scripts/README.md`。
+
+## 依赖安装
+
+### 使用 uv（推荐）
+
+```bash
+# DOCX - 推荐依赖
+uv run --with "markitdown[docx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.docx
+
+# PPTX - 推荐依赖
+uv run --with "markitdown[pptx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.pptx
+
+# XLSX - 推荐依赖
+uv run --with "markitdown[xlsx]" skills/lyxy-reader-office/scripts/parser.py /path/to/file.xlsx
+
+# PDF - 推荐依赖
+uv run --with "markitdown[pdf]" --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf
+
+# PDF OCR 高精度模式
+uv run --with docling --with pypdf skills/lyxy-reader-office/scripts/parser.py /path/to/file.pdf --high-res
+```
+
+> **注意**：以上为最小推荐依赖，更多解析器依赖和完整安装命令请查阅 `scripts/README.md` 的安装部分。
+
+## 各格式输出特点
+
+- **DOCX**：标准 Markdown 文档结构
+- **PPTX**：每张幻灯片以 `## Slide N` 为标题，幻灯片之间以 `---` 分隔
+- **XLSX**：以 `## SheetName` 区分工作表，数据以 Markdown 表格呈现
+- **PDF**：纯文本流，使用 `--high-res` 可启用 OCR 版面分析识别标题
+
+## 能力说明
+
+### 1. 全文转换为 Markdown
+将完整文档解析为 Markdown 格式，移除图片但保留文本格式（标题、列表、表格、粗体、斜体等）。
+
+### 2. 获取文档元信息
+- 字数统计（`-c` 参数）
+- 行数统计（`-l` 参数）
+
+### 3. 标题列表提取
+提取文档中所有 1-6 级标题（`-t` 参数），按原始层级关系返回。
+
+### 4. 指定章节内容提取
+根据标题名称提取特定章节的完整内容（`-tc` 参数），包含上级标题链和所有下级内容。
+
+### 5. 正则表达式搜索
+在文档中搜索关键词或模式（`-s` 参数），支持自定义上下文行数（`-n` 参数，默认 2 行）。
+
+### 6. PDF OCR 高精度模式
+对 PDF 文件启用 OCR 版面分析（`--high-res` 参数），适用于扫描版 PDF 或需要识别标题层级的场景。
diff --git a/skills/lyxy-runner-js/SKILL.md b/skills/lyxy-runner-js/SKILL.md
index f3e2437..85806c1 100644
--- a/skills/lyxy-runner-js/SKILL.md
+++ b/skills/lyxy-runner-js/SKILL.md
@@ -8,319 +8,69 @@ compatibility: Requires Bun runtime (https://bun.sh)
 
 基于 Bun 的 JavaScript/TypeScript 执行技能，提供隔离的脚本执行和自动依赖管理。
 
-## 快速参考
+## Purpose
 
-根据您的需求选择使用方式：
+**必需依赖**: 此 skill 需要 Bun 运行时，不兼容其他 JavaScript 运行时。
 
-| 场景      | 描述                     | 命令                               |
-| --------- | ------------------------ | ---------------------------------- |
-| **场景1** | 直接执行已存在的脚本文件 | `bun <script-file>`                |
-| **场景2** | 在指定路径创建脚本并执行 | 使用 Write 工具创建 → `bun <path>` |
-| **场景3** | 使用临时路径执行（默认） | 生成临时路径 → `bun <temp-file>`   |
+Bun 特性：
+- 自动检测和下载依赖（无需 package.json）
+- 即时转译 TypeScript
+- 跨平台兼容（Windows/macOS/Linux）
 
-**重要提示：** 所有场景在执行脚本前都必须先检查 Bun 环境：`bun --version`
+**重要**: 如果 Bun 未安装，立即停止任务并引导用户安装。禁止使用 nodejs、npm、yarn、pnpm 等替代工具。
 
-## 前置条件
+## When to Use
 
-### 安装 Bun
+任何 JavaScript/TypeScript 处理任务都应使用此 skill。
 
-lyxy-runner-js 需要安装 Bun。Bun 是一个快速的 JavaScript 运行时，内置包管理器。
+### 典型场景
+- **数据处理**: JSON/CSV 解析、数据转换
+- **API 交互**: HTTP 请求、Web API 调用
+- **文件操作**: 文件读写、批量处理
+- **脚本自动化**: 构建脚本、任务自动化
 
-**macOS/Linux:**
+### 不适用场景
+- ✗ 需要 Node.js 特定 API（如部分原生模块）
+- ✗ 需要持久化进程（如服务器）
+
+## Quick Reference
+
+| 场景 | 描述 | 命令 |
+|------|------|------|
+| 场景1 | 直接执行已存在的脚本 | `bun <script-file>` |
+| 场景2 | 在指定路径创建脚本并执行 | 使用 Write 工具创建 → `bun <path>` |
+| 场景3 | 使用临时路径执行（默认） | 生成临时路径 → `bun <temp-file>` |
+
+**重要**: 所有场景执行前必须先检查 Bun 环境：`bun --version`
+
+## Workflow
+
+1. **检查 Bun 环境**：执行 `bun --version`，失败则停止并提示安装
+2. **选择执行场景**：根据用户意图选择场景1/2/3
+3. **执行脚本**：使用 `bun <script>` 运行
+4. **捕获输出**：stdout/stderr 分别处理
+
+### 临时路径执行（场景3）
 
 ```bash
-curl -fsSL https://bun.sh/install | bash
-```
-
-**Windows:**
-
-```powershell
-powershell -c "irm bun.sh/install.ps1 | iex"
-```
-
-**验证安装:**
-
-```bash
-bun --version
-```
-
-## 使用流程
-
-**执行流程决策树：**
-
-1. **步骤1：检查 Bun 环境**
-   - 执行：`bun --version`
-   - 失败 → 输出错误信息（包含安装说明）并停止执行
-   - 成功 → 进入下一步
-   - **重要：** 禁止使用 nodejs、npm、yarn、pnpm 等其他工具
-
-2. **步骤2：选择执行场景**
-   - 场景1：用户提供了已存在的脚本文件路径？
-     - 是 → 直接执行：`bun <script-file>`
-     - 否 → 进入下一步
-   - 场景2：用户指定了脚本的生成路径？
-     - 是 → 使用 Write 工具创建脚本，然后执行
-     - 否 → 进入场景3
-
-3. **场景3（默认）**：使用临时路径执行
-   - 生成临时文件路径
-   - 将脚本内容写入临时文件
-   - 使用 Bun 运行脚本
-   - 临时文件由系统自动处理
-
----
-
-### 场景1：执行已存在的脚本文件
-
-```bash
-# 步骤 1: 检查 Bun 是否已安装
-bun --version
-
-# 步骤 2: 直接执行已存在的脚本
-bun ./scripts/my-script.js
-
-# 脚本的输出将自动显示
-```
-
-**关键特点：**
-- ✅ **无需生成临时文件** - 直接执行用户提供的脚本
-- ✅ **保持脚本位置** - 脚本留在原位置，不会被移动或复制
-- ✅ **简洁快速** - 跳过文件生成步骤，直接执行
-
-### 场景2：在指定路径创建并执行脚本
-
-```bash
-# 步骤 1: 检查 Bun 是否已安装
-bun --version
-
-# 步骤 2: 使用 Write 工具在指定路径创建脚本
-# (以下步骤由大模型使用 Write 工具完成)
-# write content to "./scripts/new-script.js"
-
-const greeting = "Hello from custom path!";
-console.log(greeting);
-
-# 步骤 3: 执行脚本
-bun ./scripts/new-script.js
-```
-
-**关键特点：**
-- ✅ **自定义路径** - 脚本创建到用户指定的位置
-- ✅ **持久化存储** - 脚本文件保存在指定位置，不会被自动清理
-   - ✅ **灵活控制** - 用户可以精确控制脚本位置和命名
-
-### 场景3：使用临时路径执行（默认流程）
-
-当用户未提供任何路径信息时，使用临时路径执行脚本（默认流程）：
-
-#### 基础示例
-
-```bash
-# 步骤 1: 检查 Bun 是否已安装
-bun --version
-
-# 步骤 2: 生成临时文件路径
+# 生成临时文件路径
 TEMP_FILE=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js js)
 
-# 步骤 3: 将脚本内容写入临时文件
+# 写入脚本内容
 cat <<EOF > "$TEMP_FILE"
-const greeting = "Hello from lyxy-runner-js!";
-console.log(greeting);
+console.log("Hello from lyxy-runner-js!");
 EOF
 
-# 步骤 4: 执行脚本
+# 执行脚本
 bun "$TEMP_FILE"
-
-# 步骤 5: 输出已在上面捕获
-# 临时文件将由系统自动清理
 ```
 
-#### TypeScript 示例
+## References
 
-```bash
-# 生成 TypeScript 临时文件
-TEMP_TS=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js ts)
+详细文档请参阅 `references/` 目录：
 
-# 写入 TypeScript 脚本
-cat <<EOF > "$TEMP_TS"
-const message: string = 'TypeScript execution';
-console.log(message);
-EOF
-
-# 执行 - Bun 会自动转译 TypeScript
-bun "$TEMP_TS"
-```
-
-**Bun 自动处理：**
-- 检测 `import` 语句
-- 即时转译 TypeScript
-- 下载并缓存依赖（到 `~/.bun/install/cache`）
-- 无需 `package.json` 或手动安装
-
-## 依赖管理
-
-Bun 提供自动依赖管理，无需手动配置：
-
-### 导入外部包
-
-```javascript
-// ESM import（推荐）
-import axios from 'axios'
-import lodash from 'lodash'
-
-// CommonJS import（也支持）
-const axios = require('axios')
-```
-
-首次执行带有外部导入的脚本时，Bun 会：
-
-1. 分析导入
-2. 从 npm 下载缺失的依赖
-3. 全局缓存到 `~/.bun/install/cache`
-4. 后续运行使用缓存版本
-
-### 不需要 package.json
-
-与 Node.js 不同，你无需创建 `package.json` 或单独运行 `bun install`。Bun 在运行时自动处理所有操作。
-
-## 辅助函数 API
-
-### `get_temp_path.js`
-
-为脚本执行生成唯一的临时文件路径。
-
-**CLI 使用方式:**
-
-```bash
-bun skills/lyxy-runner-js/scripts/get_temp_path.js <extension>
-```
-
-**参数:**
-
-- `extension` (可选): 文件扩展名。默认为 `js`。常用值: `js`, `ts`, `mjs`, `mts`
-
-**输出:** 返回类似 `/var/folders/.../lyxy-runner-js-1234567890-abc123.js` 的路径
-
-**路径格式:**
-
-- 使用操作系统临时目录（Unix 上为 `/tmp`，Windows 上为 `%TEMP%`）
-- 前缀: `lyxy-runner-js-`
-- 时间戳: 自纪元以来的毫秒数
-- 随机字符串: 7 字符字母数字
-- 扩展名: 参数中提供的值
-
-**示例:**
-
-```bash
-$ bun skills/lyxy-runner-js/scripts/get_temp_path.js js
-/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-na6ujx.js
-
-$ bun skills/lyxy-runner-js/scripts/get_temp_path.js ts
-/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-v8yzt.ts
-```
-
-## 错误处理
-
-### 未安装 Bun
-
-**症状:** `bun --version` 失败或返回 "command not found: bun"
-
-**错误处理：**
-
-当检测到 Bun 未安装时，必须：
-
-1. **停止执行** - 不进行任何后续操作
-2. **输出明确错误信息** - 清晰说明 "Bun 运行时未安装" 或类似提示
-3. **提供安装说明** - 参考"前置条件"章节的安装命令
-
-**重要限制：**
-
-- ❌ **禁止自动安装** - 不要尝试自动安装 Bun，由用户自行决定
-- ❌ **禁止使用其他工具** - 不要尝试使用 nodejs、npm、yarn、pnpm 等其他 JavaScript 运行时或包管理工具
-- ❌ **禁止格式转换** - 不要建议用户将脚本转换为其他运行时格式
-
-**正确做法：**
-
-- ✅ 仅输出错误信息和安装说明
-- ✅ 等待用户安装 Bun 后再继续
-- ✅ 保持使用 Bun 作为唯一运行时
-
-### 脚本语法错误
-
-Bun 提供详细的语法错误信息：
-
-```bash
-$ bun "$TEMP_FILE"
-error: Unexpected token
-   --> /var/folders/.../script.js:2:10
-    |
-  2 |   const = 123;
-    |          ^
-```
-
-错误信息包括：
-
-- 文件路径和行号
-- 错误的确切位置
-- 问题描述
-
-### 运行时错误
-
-运行时错误包含完整的堆栈跟踪：
-
-```bash
-$ bun "$TEMP_FILE"
-ReferenceError: foo is not defined
-    at script.js:3:5
-    at main (script.js:1:1)
-```
-
-### 其他错误
-
-其他任何形式的错误都原样输出
-
-## 输出处理
-
-### 标准输出
-
-所有 `console.log()`, `console.info()`, `console.warn()` 输出都到 stdout：
-
-```bash
-bun "$TEMP_FILE"  # stdout 由调用代码捕获
-```
-
-### 错误输出
-
-`console.error()` 输出到 stderr：
-
-```bash
-bun "$TEMP_FILE" 2>error.log  # 单独捕获 stderr
-```
-
-### 退出码
-
-脚本可以设置自定义退出码：
-
-```javascript
-process.exit(1) // 错误
-process.exit(0) // 成功
-```
-
-调用者接收这些退出码以确定执行状态。
-
-## 临时文件管理
-
-执行后 **不会主动删除** 临时文件。这是设计使然：
-
-- 操作系统自动管理临时目录空间
-- 文件可以保留用于调试目的
-- 大多数操作系统定期清理旧的临时文件
-
-## 最佳实践
-
-1. **始终先检查 Bun 环境** - 所有场景第一步都执行 `bun --version`
-2. **根据用户意图选择场景** - 查看快速参考选择合适的使用方式
-3. **单独处理 stdout/stderr** - 以区分输出和错误
-4. **检查退出码** - 以检测脚本失败
-5. **使用 ESM imports** - 使用 `import from` 编写现代 JavaScript
-6. **捕获并显示错误** - 以帮助用户调试问题
+| 文件 | 内容 |
+|------|------|
+| `references/examples.md` | 各场景完整示例、TypeScript 示例、依赖管理示例 |
+| `references/error-handling.md` | Bun 未安装、语法错误、运行时错误处理 |
+| `references/best-practices.md` | 输出处理、临时文件管理、辅助函数 API |
diff --git a/skills/lyxy-runner-js/references/best-practices.md b/skills/lyxy-runner-js/references/best-practices.md
new file mode 100644
index 0000000..317281f
--- /dev/null
+++ b/skills/lyxy-runner-js/references/best-practices.md
@@ -0,0 +1,83 @@
+# 最佳实践和输出处理
+
+## 最佳实践
+
+1. **始终先检查 Bun 环境** - 所有场景第一步都执行 `bun --version`
+2. **根据用户意图选择场景** - 查看快速参考选择合适的使用方式
+3. **单独处理 stdout/stderr** - 以区分输出和错误
+4. **检查退出码** - 以检测脚本失败
+5. **使用 ESM imports** - 使用 `import from` 编写现代 JavaScript
+6. **捕获并显示错误** - 以帮助用户调试问题
+
+## 输出处理
+
+### 标准输出
+
+所有 `console.log()`, `console.info()`, `console.warn()` 输出都到 stdout：
+
+```bash
+bun "$TEMP_FILE"  # stdout 由调用代码捕获
+```
+
+### 错误输出
+
+`console.error()` 输出到 stderr：
+
+```bash
+bun "$TEMP_FILE" 2>error.log  # 单独捕获 stderr
+```
+
+### 退出码
+
+脚本可以设置自定义退出码：
+
+```javascript
+process.exit(1) // 错误
+process.exit(0) // 成功
+```
+
+调用者接收这些退出码以确定执行状态。
+
+## 临时文件管理
+
+执行后 **不会主动删除** 临时文件。这是设计使然：
+
+- 操作系统自动管理临时目录空间
+- 文件可以保留用于调试目的
+- 大多数操作系统定期清理旧的临时文件
+
+## 辅助函数 API
+
+### `get_temp_path.js`
+
+为脚本执行生成唯一的临时文件路径。
+
+**CLI 使用方式:**
+
+```bash
+bun skills/lyxy-runner-js/scripts/get_temp_path.js <extension>
+```
+
+**参数:**
+
+- `extension` (可选): 文件扩展名。默认为 `js`。常用值: `js`, `ts`, `mjs`, `mts`
+
+**输出:** 返回类似 `/var/folders/.../lyxy-runner-js-1234567890-abc123.js` 的路径
+
+**路径格式:**
+
+- 使用操作系统临时目录（Unix 上为 `/tmp`，Windows 上为 `%TEMP%`）
+- 前缀: `lyxy-runner-js-`
+- 时间戳: 自纪元以来的毫秒数
+- 随机字符串: 7 字符字母数字
+- 扩展名: 参数中提供的值
+
+**示例:**
+
+```bash
+$ bun skills/lyxy-runner-js/scripts/get_temp_path.js js
+/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-na6ujx.js
+
+$ bun skills/lyxy-runner-js/scripts/get_temp_path.js ts
+/var/folders/8m/0hm18pdd7ts2bwp0530drz500000gn/T/lyxy-runner-js-1770257905333-v8yzt.ts
+```
diff --git a/skills/lyxy-runner-js/references/error-handling.md b/skills/lyxy-runner-js/references/error-handling.md
new file mode 100644
index 0000000..06b9e2a
--- /dev/null
+++ b/skills/lyxy-runner-js/references/error-handling.md
@@ -0,0 +1,71 @@
+# 错误处理
+
+## 未安装 Bun
+
+**症状:** `bun --version` 失败或返回 "command not found: bun"
+
+**错误处理：**
+
+当检测到 Bun 未安装时，必须：
+
+1. **停止执行** - 不进行任何后续操作
+2. **输出明确错误信息** - 清晰说明 "Bun 运行时未安装" 或类似提示
+3. **提供安装说明** - 参考下方安装命令
+
+**安装 Bun：**
+
+**macOS/Linux:**
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+**Windows:**
+```powershell
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
+
+**重要限制：**
+
+- ❌ **禁止自动安装** - 不要尝试自动安装 Bun，由用户自行决定
+- ❌ **禁止使用其他工具** - 不要尝试使用 nodejs、npm、yarn、pnpm 等其他 JavaScript 运行时或包管理工具
+- ❌ **禁止格式转换** - 不要建议用户将脚本转换为其他运行时格式
+
+**正确做法：**
+
+- ✅ 仅输出错误信息和安装说明
+- ✅ 等待用户安装 Bun 后再继续
+- ✅ 保持使用 Bun 作为唯一运行时
+
+## 脚本语法错误
+
+Bun 提供详细的语法错误信息：
+
+```bash
+$ bun "$TEMP_FILE"
+error: Unexpected token
+   --> /var/folders/.../script.js:2:10
+    |
+  2 |   const = 123;
+    |          ^
+```
+
+错误信息包括：
+
+- 文件路径和行号
+- 错误的确切位置
+- 问题描述
+
+## 运行时错误
+
+运行时错误包含完整的堆栈跟踪：
+
+```bash
+$ bun "$TEMP_FILE"
+ReferenceError: foo is not defined
+    at script.js:3:5
+    at main (script.js:1:1)
+```
+
+## 其他错误
+
+其他任何形式的错误都原样输出。
diff --git a/skills/lyxy-runner-js/references/examples.md b/skills/lyxy-runner-js/references/examples.md
new file mode 100644
index 0000000..a9d60b0
--- /dev/null
+++ b/skills/lyxy-runner-js/references/examples.md
@@ -0,0 +1,104 @@
+# 示例
+
+## 场景1：执行已存在的脚本文件
+
+```bash
+# 步骤 1: 检查 Bun 是否已安装
+bun --version
+
+# 步骤 2: 直接执行已存在的脚本
+bun ./scripts/my-script.js
+
+# 脚本的输出将自动显示
+```
+
+**关键特点：**
+- ✅ **无需生成临时文件** - 直接执行用户提供的脚本
+- ✅ **保持脚本位置** - 脚本留在原位置，不会被移动或复制
+- ✅ **简洁快速** - 跳过文件生成步骤，直接执行
+
+## 场景2：在指定路径创建并执行脚本
+
+```bash
+# 步骤 1: 检查 Bun 是否已安装
+bun --version
+
+# 步骤 2: 使用 Write 工具在指定路径创建脚本
+# (以下步骤由大模型使用 Write 工具完成)
+# write content to "./scripts/new-script.js"
+
+const greeting = "Hello from custom path!";
+console.log(greeting);
+
+# 步骤 3: 执行脚本
+bun ./scripts/new-script.js
+```
+
+**关键特点：**
+- ✅ **自定义路径** - 脚本创建到用户指定的位置
+- ✅ **持久化存储** - 脚本文件保存在指定位置，不会被自动清理
+- ✅ **灵活控制** - 用户可以精确控制脚本位置和命名
+
+## 场景3：使用临时路径执行（默认流程）
+
+### 基础示例
+
+```bash
+# 步骤 1: 检查 Bun 是否已安装
+bun --version
+
+# 步骤 2: 生成临时文件路径
+TEMP_FILE=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js js)
+
+# 步骤 3: 将脚本内容写入临时文件
+cat <<EOF > "$TEMP_FILE"
+const greeting = "Hello from lyxy-runner-js!";
+console.log(greeting);
+EOF
+
+# 步骤 4: 执行脚本
+bun "$TEMP_FILE"
+
+# 步骤 5: 输出已在上面捕获
+# 临时文件将由系统自动清理
+```
+
+### TypeScript 示例
+
+```bash
+# 生成 TypeScript 临时文件
+TEMP_TS=$(bun skills/lyxy-runner-js/scripts/get_temp_path.js ts)
+
+# 写入 TypeScript 脚本
+cat <<EOF > "$TEMP_TS"
+const message: string = 'TypeScript execution';
+console.log(message);
+EOF
+
+# 执行 - Bun 会自动转译 TypeScript
+bun "$TEMP_TS"
+```
+
+## 依赖管理示例
+
+### 导入外部包
+
+```javascript
+// ESM import（推荐）
+import axios from 'axios'
+import lodash from 'lodash'
+
+// CommonJS import（也支持）
+const axios = require('axios')
+```
+
+首次执行带有外部导入的脚本时，Bun 会：
+
+1. 分析导入
+2. 从 npm 下载缺失的依赖
+3. 全局缓存到 `~/.bun/install/cache`
+4. 后续运行使用缓存版本
+
+### 不需要 package.json
+
+与 Node.js 不同，你无需创建 `package.json` 或单独运行 `bun install`。Bun 在运行时自动处理所有操作。
diff --git a/skills/lyxy-runner-python/SKILL.md b/skills/lyxy-runner-python/SKILL.md
index e967183..0cd0c15 100644
--- a/skills/lyxy-runner-python/SKILL.md
+++ b/skills/lyxy-runner-python/SKILL.md
@@ -38,55 +38,7 @@ description: Any task that requires Python processing should use this skill.
 - ✗ 需要命令行参数
 - ✗ 需要从stdin读取
 
-## Automatic Dependency Parsing
-
-分析import语句，提取外部包名，排除标准库。
-
-### 标准库（排除）
-**核心**: os, sys, pathlib, shutil, json, csv, re, datetime, math
-**网络**: http.client, urllib, socket, io, logging
-**高级**: itertools, functools, typing, dataclasses, enum
-
-### 解析规则
-1. 提取：`import pandas` → `pandas`, `from numpy import array` → `numpy`
-2. 排除标准库
-3. 去重
-
-### 示例
-```python
-import pandas as pd
-import numpy as np
-import json  # 标准库，排除
-from pathlib import Path  # 标准库，排除
-
-# 结果: [pandas, numpy]
-```
-
-## Smart Project Detection
-
-### 检测命令
-```bash
-uv sync --dry-run
-```
-
-### 判断逻辑
-- Exit code 0 → uv项目
-- 非零退出码 → 非uv项目
-- 失败 → 回退到非uv项目模式（使用`--with`），不阻塞执行
-
-## Path Handling
-
-### 三层逻辑
-1. **用户指定存储路径** → 写入指定路径
-2. **用户指定现有脚本** → 直接执行
-3. **未指定** → 临时文件
-
-```bash
-# 临时文件获取
-temp_file_path=$(uv run ./scripts/get_temp_path.py)
-```
-
-## Execution Commands
+## Quick Reference
 
 | 场景 | 命令 |
 |------|------|
@@ -94,154 +46,20 @@ temp_file_path=$(uv run ./scripts/get_temp_path.py)
 | 非uv+有依赖 | `uv run --with pkg1 --with pkg2 <script_path>` |
 | 非uv+无依赖 | `uv run <script_path>` |
 
-**特点**:
-- uv项目：使用项目环境，无`--with`
-- 非uv有依赖：每个`--with`创建隔离环境
-- 非uv无依赖：使用标准Python环境
-
 ## Workflow
 
-**步骤1**: 解析依赖（见"Automatic Dependency Parsing"）
+1. **解析依赖**：分析import语句，提取外部包名（排除标准库）
+2. **检测项目**：执行`uv sync --dry-run`判断是否为uv项目
+3. **确定路径**：用户指定路径 → 现有脚本 → 临时文件
+4. **构造命令**：根据项目类型和依赖构造执行命令
+5. **执行脚本**：运行并捕获输出
 
-**步骤2**: 检测项目（见"Smart Project Detection"）
+## References
 
-**步骤3**: 确定路径（见"Path Handling"）
+详细文档请参阅 `references/` 目录：
 
-**步骤4**: 构造并执行命令（见"Execution Commands"）
-
-执行命令并捕获输出。
-
-## Error Handling
-
-### uv未安装
-
-**检测**: `uv`命令失败
-
-**错误消息**:
-```
-uv not found
-
-此skill依赖uv工具运行Python脚本。
-
-请安装uv: https://docs.astral.sh/uv/getting-started/installation/
-
-安装命令示例：
-  curl -LsSf https://astral.sh/uv/install.sh | sh    # Linux/macOS
-  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows
-```
-
-**重要提示**:
-- **立即停止任务**，等待用户安装uv后再继续
-- **不要尝试使用**：python, pip, poetry, venv, virtualenv等
-- **不要自动安装**uv
-- 用户安装uv完成后，可以重新执行任务
-
-**操作**: 立即停止所有执行，等待用户安装uv
-
-### 其他错误
-
-| 场景 | 错误消息 | 操作 |
-|------|---------|------|
-| 项目检测失败 | 回退到非uv模式，使用`--with` | 警告后继续 |
-| 依赖解析不准确 | 依赖可能不完整<br>Traceback: [traceback] | 停止，保留脚本调试 |
-| 语法错误 | Python语法错误: [描述]<br>文件: <path><br>行号: <line> | 停止 |
-| 路径权限问题 | 无法写入: <path><br>建议: 使用临时文件模式 | 回退到临时文件 |
-
-## Examples
-
-### 示例1: 数据分析
-```python
-import pandas as pd
-import numpy as np
-
-df = pd.read_csv('data.csv')
-print(f"形状: {df.shape}")
-print(df.describe())
-```
-**执行**: `uv run --with pandas --with numpy /tmp/script_xxx.py`
-
-### 示例2: API交互
-```python
-import requests
-
-resp = requests.get('https://api.github.com/repos/python/cpython')
-data = resp.json()
-print(f"仓库: {data['full_name']}, Stars: {data['stargazers_count']}")
-```
-**执行**: `uv run --with requests /tmp/script_xxx.py`
-
-### 示例3: 文件操作
-```python
-import os
-import glob
-
-for i, file in enumerate(glob.glob('*.txt')):
-    os.rename(file, f"file_{i:03d}.txt")
-```
-**执行**: `uv run /tmp/script_xxx.py`（无依赖）
-
-### 示例4: uv项目内执行
-```python
-import pandas as pd
-from my_project import helper
-
-df = pd.read_csv('data.csv')
-result = helper.process(df)
-print(result)
-```
-**执行**: `uv run scripts/data_process.py`（使用项目环境）
-
-### 示例5: 用户指定路径
-```python
-import requests
-
-resp = requests.get('https://api.example.com/data')
-print(f"处理完成: {len(resp.json())} 条")
-```
-**执行**: `uv run --with requests scripts/api_analyzer.py`（写入指定路径）
-
-## Notes
-
-### 为什么使用uv？
-| 特性 | 优势 |
+| 文件 | 内容 |
 |------|------|
-| 环境隔离 | 不污染系统Python |
-| 自动依赖 | `--with`语法，无需pip install |
-| 快速启动 | 比venv快10-100倍 |
-| 项目集成 | 自动检测uv项目 |
-| 零配置 | 开箱即用，无需PEP 723 |
-
-### 最佳实践
-1. **依赖解析**: 排除标准库；失败时检查遗漏依赖；复杂项目用uv项目模式
-2. **路径**: 用户指定优先；临时文件用于自主生成；跨平台由辅助脚本保证
-3. **错误**: 预期错误脚本内处理；意外错误立即停止；检测失败自动回退
-4. **清理**: 临时文件使用系统目录，自动清理，失败时手动删除
-
-### 限制
-- ✗ 不支持命令行参数、stdin输入、持久化环境
-- ✗ 使用uv默认Python版本（项目可在pyproject.toml指定）
-- ✗ 依赖解析可能不完整（动态导入、条件导入可能遗漏）
-- ✗ 项目检测可能误判（网络问题导致回退）
-
-### uv工具要求
-
-- **uv是此skill的必需依赖，不可替代**
-- **不支持**: python, pip, poetry, venv, virtualenv
-- 如果检测到uv未安装，必须停止任务并引导用户安装
-- 不要尝试使用替代方案或自动安装uv
-
-## Workflow Summary
-
-**完整流程**:
-1. 解析import语句，提取外部包名（排除标准库）
-2. 执行`uv sync --dry-run`检测项目
-3. 确定脚本路径（用户指定/现有脚本/临时文件）
-4. 构造执行命令（根据项目类型和依赖）
-5. 执行并捕获输出
-
-**关键特点**:
-- 自动依赖解析：分析import自动提取
-- 智能项目检测：自动识别uv项目
-- 灵活路径：支持指定/现有/临时三种模式
-- 跨平台：自动适配Windows/macOS/Linux
-- 环境隔离：独立虚拟环境
+| `references/examples.md` | 数据分析、API交互、文件操作等完整示例 |
+| `references/error-handling.md` | uv未安装、依赖解析失败等错误处理指南 |
+| `references/best-practices.md` | 依赖解析、路径处理、项目检测等最佳实践 |
diff --git a/skills/lyxy-runner-python/references/best-practices.md b/skills/lyxy-runner-python/references/best-practices.md
new file mode 100644
index 0000000..fe0c352
--- /dev/null
+++ b/skills/lyxy-runner-python/references/best-practices.md
@@ -0,0 +1,86 @@
+# 最佳实践和注意事项
+
+## 为什么使用uv？
+
+| 特性 | 优势 |
+|------|------|
+| 环境隔离 | 不污染系统Python |
+| 自动依赖 | `--with`语法，无需pip install |
+| 快速启动 | 比venv快10-100倍 |
+| 项目集成 | 自动检测uv项目 |
+| 零配置 | 开箱即用，无需PEP 723 |
+
+## 最佳实践
+
+1. **依赖解析**: 排除标准库；失败时检查遗漏依赖；复杂项目用uv项目模式
+2. **路径**: 用户指定优先；临时文件用于自主生成；跨平台由辅助脚本保证
+3. **错误**: 预期错误脚本内处理；意外错误立即停止；检测失败自动回退
+4. **清理**: 临时文件使用系统目录，自动清理，失败时手动删除
+
+## 限制
+
+- ✗ 不支持命令行参数、stdin输入、持久化环境
+- ✗ 使用uv默认Python版本（项目可在pyproject.toml指定）
+- ✗ 依赖解析可能不完整（动态导入、条件导入可能遗漏）
+- ✗ 项目检测可能误判（网络问题导致回退）
+
+## uv工具要求
+
+- **uv是此skill的必需依赖，不可替代**
+- **不支持**: python, pip, poetry, venv, virtualenv
+- 如果检测到uv未安装，必须停止任务并引导用户安装
+- 不要尝试使用替代方案或自动安装uv
+
+## 自动依赖解析详细说明
+
+分析import语句，提取外部包名，排除标准库。
+
+### 标准库（排除）
+
+**核心**: os, sys, pathlib, shutil, json, csv, re, datetime, math
+**网络**: http.client, urllib, socket, io, logging
+**高级**: itertools, functools, typing, dataclasses, enum
+
+### 解析规则
+
+1. 提取：`import pandas` → `pandas`, `from numpy import array` → `numpy`
+2. 排除标准库
+3. 去重
+
+### 示例
+
+```python
+import pandas as pd
+import numpy as np
+import json  # 标准库，排除
+from pathlib import Path  # 标准库，排除
+
+# 结果: [pandas, numpy]
+```
+
+## 智能项目检测
+
+### 检测命令
+
+```bash
+uv sync --dry-run
+```
+
+### 判断逻辑
+
+- Exit code 0 → uv项目
+- 非零退出码 → 非uv项目
+- 失败 → 回退到非uv项目模式（使用`--with`），不阻塞执行
+
+## 路径处理
+
+### 三层逻辑
+
+1. **用户指定存储路径** → 写入指定路径
+2. **用户指定现有脚本** → 直接执行
+3. **未指定** → 临时文件
+
+```bash
+# 临时文件获取
+temp_file_path=$(uv run ./scripts/get_temp_path.py)
+```
diff --git a/skills/lyxy-runner-python/references/error-handling.md b/skills/lyxy-runner-python/references/error-handling.md
new file mode 100644
index 0000000..64635bd
--- /dev/null
+++ b/skills/lyxy-runner-python/references/error-handling.md
@@ -0,0 +1,35 @@
+# 错误处理
+
+## uv未安装
+
+**检测**: `uv`命令失败
+
+**错误消息**:
+```
+uv not found
+
+此skill依赖uv工具运行Python脚本。
+
+请安装uv: https://docs.astral.sh/uv/getting-started/installation/
+
+安装命令示例：
+  curl -LsSf https://astral.sh/uv/install.sh | sh    # Linux/macOS
+  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows
+```
+
+**重要提示**:
+- **立即停止任务**，等待用户安装uv后再继续
+- **不要尝试使用**：python, pip, poetry, venv, virtualenv等
+- **不要自动安装**uv
+- 用户安装uv完成后，可以重新执行任务
+
+**操作**: 立即停止所有执行，等待用户安装uv
+
+## 其他错误
+
+| 场景 | 错误消息 | 操作 |
+|------|---------|------|
+| 项目检测失败 | 回退到非uv模式，使用`--with` | 警告后继续 |
+| 依赖解析不准确 | 依赖可能不完整<br>Traceback: [traceback] | 停止，保留脚本调试 |
+| 语法错误 | Python语法错误: [描述]<br>文件: <path><br>行号: <line> | 停止 |
+| 路径权限问题 | 无法写入: <path><br>建议: 使用临时文件模式 | 回退到临时文件 |
diff --git a/skills/lyxy-runner-python/references/examples.md b/skills/lyxy-runner-python/references/examples.md
new file mode 100644
index 0000000..7393fce
--- /dev/null
+++ b/skills/lyxy-runner-python/references/examples.md
@@ -0,0 +1,62 @@
+# 示例
+
+## 示例1: 数据分析
+
+```python
+import pandas as pd
+import numpy as np
+
+df = pd.read_csv('data.csv')
+print(f"形状: {df.shape}")
+print(df.describe())
+```
+
+**执行**: `uv run --with pandas --with numpy /tmp/script_xxx.py`
+
+## 示例2: API交互
+
+```python
+import requests
+
+resp = requests.get('https://api.github.com/repos/python/cpython')
+data = resp.json()
+print(f"仓库: {data['full_name']}, Stars: {data['stargazers_count']}")
+```
+
+**执行**: `uv run --with requests /tmp/script_xxx.py`
+
+## 示例3: 文件操作
+
+```python
+import os
+import glob
+
+for i, file in enumerate(glob.glob('*.txt')):
+    os.rename(file, f"file_{i:03d}.txt")
+```
+
+**执行**: `uv run /tmp/script_xxx.py`（无依赖）
+
+## 示例4: uv项目内执行
+
+```python
+import pandas as pd
+from my_project import helper
+
+df = pd.read_csv('data.csv')
+result = helper.process(df)
+print(result)
+```
+
+**执行**: `uv run scripts/data_process.py`（使用项目环境）
+
+## 示例5: 用户指定路径
+
+```python
+import requests
+
+resp = requests.get('https://api.example.com/data')
+print(f"处理完成: {len(resp.json())} 条")
+```
+
+**执行**: `uv run --with requests scripts/api_analyzer.py`（写入指定路径）