前言¶

Obsidian 里混着业务附件、项目 README、手写 Markdown 和各类生成物时，单靠人工维护「每个源文件旁有没有 .core.md、文件夹有没有 资料索引.md、图谱链接是否跟得上改名/移动」很容易漏项。常见做法是偶尔全库整理，或在插件里做局部自动化，但和「在 Cursor 里一边改文件一边让模型补索引」往往脱节。

下面介绍 SkillHub 社区 Skill Obsidian资料整理（坐标 @user_55161a2d/obsidian-core-notes，当前版本 1.0.2）。它把 vault 内的核心侧记、专题综合笔记、文件夹索引和 Obsidian 关系链接写成一套可复用的 Agent 工作流，并附带 Python 脚本做扫描、刷新与校验。

这是什么¶

Obsidian资料整理 面向 Obsidian vault，也可用于与文档/代码混放的 workspace。发布者为 SkillHub 用户 user_55161a2d，来源为 community，分类为 knowledge-management，不需要 API Key（requires_api_key=false）。

Skill 的定位是：让源文件、生成的 .core.md、专题级 专题综合.core.md 以及关系索引保持同步；在创建、编辑、移动、删除、扫描、汇总或整理可能涉及 .core.md、专题综合.core.md、资料索引.md、核心文件索引.md 的文件时启用。

核心功能¶

笔记类型与命名¶

Skill 区分四类产出，并在规则里固定用途：

1. 文件侧记：对非 Markdown 的业务源附件，生成与源文件同名的 <源文件名>.core.md。
2. 文件夹索引：目录内用 资料索引.md 做导航与直接源文件列表。
3. 工作区入口：在 vault 根或约定位置维护 核心文件索引.md。
4. 专题综合：仅对经筛选的高价值目录写 专题综合.core.md；多数目录应保持轻量源图，而非处处「深度综述」。

已有意义的 Markdown 核心文档应直接引用，不重复生成侧记。代码、配置、脚本、测试、模型输出、解析结果目录等不生成 .core.md（详见 Skill 内 references/core-file-rules.md）。

文档治理字段¶

生成物需带 YAML 治理字段，例如：

• 生成的 .core.md 侧记：doc_role: source、doc_authority: supporting、doc_rule: wiki-doc-governance-v1。
• 资料索引.md 与 核心文件索引.md：doc_role: common、doc_authority: preferred、doc_rule: wiki-doc-governance-v1。
• 承载长期判断的深度 专题综合.core.md 可用 doc_role: result。

修订源 Markdown、索引或专题笔记前，Skill 要求对照 vault 内文档分类分级准则（路径在 SKILL 中为 个人/公司相关个人资料/个人知识库实现路径/文档分类分级与技能取信准则.md）；若你的库没有该文件，需自行对齐同类治理约定。

附带脚本命令¶

安装后 Skill 目录下的 scripts/obsidian_core_notes.py 提供：

refresh 是图谱维护 pass，不能替代人工或 LLM 对 专题综合.core.md 的策展式撰写。用户要求「像 V3 一样的专题综合」时，需在 refresh 之后对选定目录做专题综合 pass（见 references/topic-synthesis-core-notes.md）。

安全删除与标记¶

仅当文件含有生成标记时才允许批量覆盖或删除，例如 <!-- CORE_FILE_NOTE_V1 -->、<!-- CORE_FOLDER_INDEX_V1 -->、<!-- CORE_WORKSPACE_INDEX_V1 -->。手写 Markdown 除非用户明确要求，不得删除。激进清理前，Skill 要求先把将被覆盖/删除的生成笔记备份到 vault 外。

安装与启用¶

通过 SkillHub CLI¶

若尚未安装 CLI，可先按 SkillHub 安装说明 执行检测与安装。安装 Skill 时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能无法被识别。

command -v skillhub && skillhub --version

skillhub install @user_55161a2d/obsidian-core-notes --dir ~/.cursor/skills/

Cursor 的 skills 目录一般为 ~/.cursor/skills/；Claude Code 为 ~/.claude/skills/；Codex 为 ~/.codex/skills/ 或项目下的 .agents/skills/。其他客户端路径以 SkillHub 安装文档第四节为准。

通过对话让 Agent 安装¶

SkillHub 页面提供的提示词为：请根据 https://skillhub.cn/install/skillhub.md，安装 @user_55161a2d/obsidian-core-notes。

安装完成后重启或刷新 Agent，使 Skill 被加载。本 Skill 版本 1.0.2，SkillHub 页面统计（以抓取资料为准）：评分 100000，下载 2237 次。

典型用法¶

下面步骤对应 SKILL.md 中的 Workflow，<skill-dir> 替换为安装后的 Skill 目录，<vault-root> 替换为你的 Obsidian 库根路径。

1. 确认根目录：默认以当前工作目录为 vault/workspace root，用户指定时用其路径。

2. 大范围改动前先扫描：

python <skill-dir>/scripts/obsidian_core_notes.py scan --root <vault-root> --json

3. 选定笔记类型（侧记 / 资料索引.md / 专题综合.core.md），在同一轮对话里完成源文件的增删改移时，同步更新对应 .core.md 与最近的 资料索引.md。

4. 批量刷新轻量索引与侧记：

python <skill-dir>/scripts/obsidian_core_notes.py refresh --root <vault-root>

5. 要做专题综合前先筛目录：

python <skill-dir>/scripts/obsidian_core_notes.py topic-candidates --root <vault-root> --json

6. 批量操作后校验：

python <skill-dir>/scripts/obsidian_core_notes.py validate --root <vault-root>

7. 仅在用户明确要求时清理生成物：

python <skill-dir>/scripts/obsidian_core_notes.py clean-generated --root <vault-root>

发现默认业务根/项目根不准时，可在 scan 与 refresh 上使用 --business-root 或 --project-root 覆盖发现逻辑（见 references/core-file-rules.md 的 Discovery defaults）。

适用场景与注意¶

适合谁：已经在 Obsidian（或与代码仓共存的文档库）里用 .core.md + 中文索引文件组织知识、并希望 Agent 在改文件时自动维护图谱与索引的维护者；也适合需要脚本批量 refresh / validate 的定期整理。

限制与坑：

• 不要把 refresh 当成专题综述生成器；V3 式 专题综合.core.md 需要单独的策展步骤与 topic-candidates 筛选。
• 修改原始 Markdown 时，不要用过程/证据内容覆盖结果类文件；优先用 related_process、related_result、validation 等溯源链接。
• 依赖 vault 内可选的「文档分类分级」准则文件时，若路径不存在，需自行约定等效的 doc_role / doc_authority 规则。
• 脚本会排除 node_modules、.git、构建产物、模型目录等；业务边界错判时用 CLI 参数纠正。

结尾¶

Obsidian资料整理 把核心侧记、专题综合、文件夹索引与 Obsidian 链接维护收敛成一套 Agent 规则加可执行脚本，适合在编辑 vault 时减少索引漂移，并用 validate 兜底批量操作。

• SkillHub 页面：https://www.skillhub.cn/skills/user_55161a2d/obsidian-core-notes
• 安装坐标：@user_55161a2d/obsidian-core-notes
• API 资源地址：https://api.skillhub.cn/user_55161a2d/obsidian-core-notes