Agent-Skills.md

Agent Skills: Learning Notes Organizer (v3)

整理与重构已有学习笔记：重划边界、归类重组、合并冗余、精简口语化表达；优化排版与可读性；为各部分补充引导与注释；按从基础到高级建立学习路径并打通知识关联；同时尽量保留原文 Markdown/HTML 强调标记（如 ==高亮==、<u>、Setext 标题等），输出结构清晰、可检索、便于长期维护的笔记体系。

UncategorizedID: z-soulx/ai-toolkit/learning-notes-organizer

Repository

z-soulx/ai-toolkit
z-soulxLicense: MIT
101

Install this agent skill to your local

pnpm dlx add-skill https://github.com/z-soulx/ai-toolkit/tree/HEAD/skills/notes/learning-notes-organizer

Skill Files

Browse the full folder contents for learning-notes-organizer.

Download Skill

Loading file tree…

skills/notes/learning-notes-organizer/SKILL.md

Skill Metadata

Name
learning-notes-organizer
Description
对 Markdown 学习笔记做结构重构与精修：两阶段 Plan-and-Execute 工作流——先诊断归类（出清单/大纲/映射/scaffold），再精修交付（重写正文、越界路由、资源追踪）。支持全文或指定章节两种 scope；支持只出清单或直接输出整理后正文。

Learning Notes Organizer (v3)

目标

将散乱的学习笔记重构成边界清晰、结构完整、渐进可学、可检索、长期可维护的笔记体系。

两阶段工作流（Plan-and-Execute）

Phase 1 — 诊断归类（Diagnose & Classify）

做什么： 只读不写，产出结构规划清单。

  1. 提取标题树（H1-H6），为每个标题输出一句话含义与一句话引导注释（"读完你会…"）
  2. 诊断问题：重复/交叉、过宽/过碎、顺序不合理（缺前置/高级内容提前）、命名不规范
  3. 提出新大纲（基础→机制→实践→坑点/优化，按内容需要调整）
  4. 旧→新映射表，每条标注动作标签（KEEP/MOVE/MERGE/SPLIT/RENAME/DROP/TBD）
  5. 重命名建议（仅列确实需要的）
  6. 若 scope=sections：标注指定章节的越界内容候选（粗粒度，Phase 2 细化）
  7. 若 scaffold=true：生成 <base>-待整理.md 框架文件（详见 Scaffold 格式）

输出： 清单（大纲/映射/重命名/问题），以及 scaffold 文件路径+内容（若启用）。

Phase 2 — 精修交付（Refactor & Deliver）

做什么： 对 scope 范围内的内容执行精修重写，并处理越界碎片。

  1. 章节精修：精简啰嗦、增强连贯、边界清晰、术语一致、标注学习路径关联
  2. 执行中越界路由：精修时发现不属于当前边界的碎片内容，路由到正确章节（或新增"待整理"子节暂存），并生成路由清单
  3. 资源追踪（asset_policy=place_correctly_and_track 时）：外链/图片零丢失，输出资源去向账本
    • 图片描述检测：扫描所有图片引用，检测 alt 为空、或 alt 仅为文件名（含扩展名如 .png/.jpg）、或为占位符（如"在这里插入图片描述"）的条目
    • 若发现 ≥1 张缺失语义描述的图片：在资源账本 G 中用 ⚠️ ALT_MISSING 标注，并在输出末尾提示："发现 N 张图片缺少语义描述，建议执行 /image-alt-title-filler 补全（账本中已标注）"
    • 不自动调用，由用户决定是否运行 image-alt-title-filler
  4. 范围外章节最小改动（仅允许接收路由内容，不做重写）

输出： 可直接替换的 Markdown + 越界路由清单 + 资源账本（若启用）。

参数

必填

  • target_file：目标 Markdown 文件路径

核心参数

| 参数 | 可选值 | 默认 | 说明 | |------|--------|------|------| | scope | full / sections: ["章节1", ...] | full | 全文 or 指定章节（支持标题名或路径） | | deliverable_mode | plan_only / full_refactor | full_refactor | 只做 Phase 1 / 两阶段都做 | | scaffold | true / false | false | 是否生成待整理框架文件（plan_only 时常用） |

资源策略

| 参数 | 可选值 | 默认 | |------|--------|------| | asset_policy | place_correctly_and_track / preserve_strict | place_correctly_and_track | | asset_ledger | required / off | required |

  • place_correctly_and_track：外链/图片优先归位到语义合适的位置；仅"倾向删除"的放入 资料参考；必须输出账本
  • preserve_strict：不移动资源，只修复断链格式；仍输出账本

执行步骤

deliverable_mode=plan_only

  1. Read：提取标题树 + 每节少量片段（判断主题归属，不通读全文）
  2. Diagnose：按 Phase 1 诊断归类
  3. Deliver：输出清单 A-D；若 scaffold=true，生成框架文件

deliverable_mode=full_refactor

  1. Read：通读全文（或指定章节全文 + 其余标题）
  2. Diagnose：Phase 1 诊断归类（必须先出清单供参考，再进入 Phase 2）
  3. Refactor：Phase 2 精修 + 越界路由
  4. Deliver：输出清单 A-D + 精修后正文 E + 路由清单 F + 资源账本 G（若启用）

输出格式

A) 新规划大纲（含引导注释）

H1 ...
  H2 ...（引导注释：读完你会…）
    H3 ...

B) 旧→新映射表

| 旧标题（含层级） | 动作 | 新标题路径 | 图片 | 备注 | |-----------------|------|-----------|------|------|

动作标签：KEEP / MOVE / MERGE / SPLIT / RENAME / DROP / TBD

图片列：—（无图）/ ✓（有图且有 alt）/ ⚠️（有图但缺 alt/title）

C) 重命名建议（仅列需要的）

  • `旧标题` → `建议标题`（原因：更标准/更短/更可检索/边界更准确）

D) 待确认问题（最多 3-7 条）

E) 精修后正文（仅当 full_refactor）

  • 输出完整正文（scope=sections 时只输出被重构章节，含必要父级标题上下文）
  • 标题不自动编号；保留原有强调标记（==高亮==、<u>、<mark>、代码块等）
  • 末尾追加"整理记录"区块（内嵌 F）

F) 越界路由清单（full_refactor 时输出）

| MIG-ID | 来源位置 | 内容块简述 | 目标路径 | 落点（章节/待整理） | |--------|---------|-----------|---------|-------------------|

同时追加写入到 E 末尾的"整理记录"区块，便于文档内留档。

G) 资源去向账本（asset_ledger=required 时输出）

| 类型 | 显示文本/alt | URL/路径 | 原位置 | 状态 | 新位置 | 说明 | |------|------------|---------|-------|------|-------|------|

状态：KEPT / MOVED / MERGED / TO_REVIEW / ⚠️ ALT_MISSING（图片缺失语义描述，建议用 /image-alt-title-filler 补全）

Scaffold 文件格式（scaffold=true 时生成）

写入路径： dirname(target_file)/<base>-待整理.md（已存在则追加 -v2/-v3）

结构：

  1. 顶部元信息（源文件、生成时间、说明）
  2. 新大纲与迁移工作区（每个新标题一个迁移块）
  3. 附录 A：旧→新映射表（全量）
  4. 附录 B：重命名建议
  5. 附录 C：待确认问题
  6. 附录 D：迁移顺序建议

迁移块模板：

### <新标题>
> 引导注释：<一句话>

**来源旧标题：**
- (MOVE) `旧标题1`
- (MERGE) `旧标题2`

**重命名建议（仅列需要的）：**
- `旧标题2` → `建议标题`（原因：...）

**迁移要点：**
- <注意事项>

⬇️ 在下面粘贴原文内容 ⬇️

（把原文复制到这里）

执行约束

必须满足

  • 标题不启用自动编号（原文已有编号保留）
  • 保留强调标记：==高亮==、<u>、<mark>、粗/斜/删、行内代码、代码块、引用块、Setext 标题
  • 不改变代码语义，不破坏代码块结构
  • 外链/图片零丢失：每条都有明确去向（正文/资料参考/账本）
  • 资料参考 只收纳"倾向删除"的资源，且每条附"待人工确认"与原因

不做（非目标）

  • 不做事实正确性校验
  • 不补充大量新内容
  • 不引入新的编号体系

调用模板

请按 learning-notes-organizer 执行。

target_file: <path/to/file.md>
scope: full                          # 或 sections: ["章节A", "章节B"]
deliverable_mode: full_refactor      # 或 plan_only
scaffold: false                      # plan_only 时建议 true

asset_policy: place_correctly_and_track
asset_ledger: required

典型场景对照：

| 场景 | 参数组合 | |------|---------| | 只要规划清单和框架文件 | deliverable_mode=plan_only, scaffold=true | | 直接整理全文 | deliverable_mode=full_refactor, scope=full | | 只整理指定几个章节 | deliverable_mode=full_refactor, scope=sections:[...] |

自我进化

本 skill 支持渐进式进化。当实战中发现行为偏差，参照 EVOLUTION.md 协议执行迭代升级。