Imported from glfruit/gorin-skills (release/packages/claude-code/gorin-pkm-core/SKILL.md). Install upstream with npx skills add glfruit/gorin-skills --skill gorin-pkm-core. Copyright stays with the author (MIT).

PKM Core — 笔记系统基础层

本 skill 提供所有笔记类 skills 共享的基础规范。不要单独触发，由其他笔记 skills 引用。

Vault 路径

所有 vault 配置（唯一权威来源）在 vault-config.yaml 的 vaults 字段。

# 获取指定 vault 路径
python3 -c "
import yaml
config_path = os.environ.get(
    'PKM_VAULT_CONFIG',
    os.path.expanduser('~/.config/gorin-skills/pkm/vault-config.yaml'),
)
with open(config_path) as f:
    cfg = yaml.safe_load(f)
print(os.path.expanduser(cfg['vaults']['atlas']['path']))
"

Vault 列表

Atlas 目录结构

atlas/
├── 1-Literature/           ← 文献笔记
│   ├── Papers/             ← 学术论文
│   ├── Books/              ← 书籍
│   ├── Articles/           ← 博客/网页
│   ├── Repos/              ← 代码仓库
│   ├── Podcasts/           ← 播客/视频
│   └── Tweets/             ← X/Twitter thread
├── 2-Concepts/             ← 概念节点（跨文献关联）
├── 3-Permanent/            ← 原子笔记
├── 4-Structure/            ← 结构笔记
│   ├── MOC/                ← Map of Content
│   ├── Index/              ← LLM 维护的索引
│   └── Queries/            ← 查询产物回填
├── 5-Areas/                ← 知识领域
├── 6-Outputs/              ← 多格式产物
│   ├── PDF/ Slides/ Charts/ Reports/
├── 7-Templates/            ← 笔记模板
├── 8-Assets/               ← 图片/附件
├── 9-Clippings/            ← Web Clipper 剪藏
└── .state/                 ← 处理状态

Octopus 目录结构

octopus/
├── Home/                    ← 仪表盘、索引页
├── Calendar/
│   ├── Journal/Daily/       ← 日记（YYYY/MM/DD.md）
│   ├── Journal/             ← 其他日记
│   ├── Reviews/             ← 周/月/年回顾
│   └── Logs/                ← 日志
├── Zettels/
│   ├── 1-Fleeting/          ← 闪念笔记（临时）
│   ├── 2-Literature/        ← 文献笔记（书籍/文章）
│   │   ├── Books/
│   │   ├── Papers/
│   │   └── Articles/
│   ├── 3-Permanent/         ← 永久笔记（原子化）
│   └── 4-Structure/         ← 结构笔记（MOC、周报）
├── Efforts/
│   ├── 1-Projects/
│   │   ├── Active/
│   │   └── Done/
│   ├── 2-Areas/
│   └── 3-Works/
├── Archives/                ← 归档
│   └── Temp-Files/0.Inbox/
└── .obsidian/               ← Obsidian 配置（不要手动改）

类型映射（唯一权威来源）

详见 vault-config.yaml 的 vaults.<name>.type_mapping 字段。各笔记 skill 不再各自维护 type → directory 映射，统一引用此文件。

注意：不同 vault 的类型映射不同。atlas 用 1-Literature，octopus 用 Zettels/2-Literature。

共享管道

详见 vault-config.yaml 的 pipeline 部分。所有创建类 skill（pkm-save-note、zk-literature、idea-creator）必须使用共享管道的 validate_frontmatter 和 prevent_orphan。

笔记命名规则

规则：

• ID 格式：YYYYMMDDHHMM（10 位数字）
• 标题分隔符：-
• 标题最大长度：50 字符
• 标题不包含特殊字符（/、\、:、*、?、"、<、>、|）

Frontmatter 规范（所有笔记必须遵守）

基本格式

---
title: "笔记标题"
type: zettel
date: 2026-03-20
tags: [tag1, tag2]
---

Obsidian 认可的属性类型

⚠️ 硬性规则

1. 列表项后不能加行内注释

   # ❌ 错误
   related:
     - "[[Note A]]" — 描述文字
   
   # ✅ 正确
   related:
     - "[[Note A]]"

2. Front matter wikilinks 必须加引号

   # ❌ 错误
   up: [[Note]]
   
   # ✅ 正确
   up: "[[Note]]"

3. Key 必须是 ASCII 字符

   # ❌ 可能出错
   心情: 😊
   
   # ✅ 正确
   mood: 😊

4. 日期格式必须标准

   # ❌ 错误
   date: 2024/01/15
   
   # ✅ 正确
   date: 2024-01-15

5. 不要在 front matter 中混用 tags 格式

   # ❌ 同时用 inline 和 multiline
   tags: [one]
     - two
   
   # ✅ 选一种
   tags: [one, two]

常用自定义属性

Obsidian 特有语法速查

详见 references/obsidian-syntax.md，关键项：

When NOT to Use

• 不直接由用户触发，由其他笔记类技能引用。
• 不用于执行笔记操作（保存/搜索/分类由上层技能处理）。

Error Handling

• vault 路径变量未设置时，使用默认路径并发出警告。
• frontmatter 解析失败时，报告具体行号和字段。
• 命名冲突时，在文件名后追加序号。

Internal Acceptance

• 所有引用此技能的上层技能能正确读取配置。
• vault 路径、命名规则、frontmatter 规范与实际文件一致。
• validate-skill.sh 通过。

Gotchas

• Obsidian vault 路径可能因环境不同而变化，始终使用环境变量。
• frontmatter 的 tags 必须是列表格式，不能用逗号分隔字符串。
• 笔记命名规则：YYYY-MM-DD-title-kebab，日期是必填前缀。

Delivery Contract

• 配置变更需同步更新所有引用此技能的 SKILL.md。
• vault 路径变更需在 TOOLS.md 中同步更新。 注意：本技能是大型流水线的一部分。Do not report completion to the user unless all dependent tools/scripts/skills have been verified as integrated.not report completion to the user unless all dependent tools/scripts/skills integration tests have passed.