note-taker

记事工具（Git 管理）

此技能可在专用的 Git 版本库中维护私有笔记系统。

设置： 必须配置笔记版本库路径。在项目的 CLAUDE.md 或 AGENTS.md 中查找 NOTES_REPO 变量；如果是首次使用，也可以询问用户路径。

规则： 此技能会产生副作用（写入、提交和推送），因此必须由用户主动调用。

编辑前同步版本库（必须）

在现有版本库中创建、更新或删除文件之前，先将当前分支与远程同步：

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

如果工作树不干净，先暂存更改，再同步，然后恢复更改：

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

如果缺少 origin、无法拉取，或发生变基／暂存冲突，请停止并先询问用户。

工作流

1) 接收内容

接受以下形式的输入：

• 文本：消息内容
• 语音：进行摘要（除非用户要求，否则不要保存完整转录）
• 图像／视频／文件：复制附件文件，并在笔记中引用

如果用户提供了多个项目，除非用户明确要求合并成一篇笔记，否则将每个项目作为单独的笔记处理。

2) 确定文件名和文件夹

将整理后的笔记创建在：

• notes/YYYY/MM/YYYY-MM-DD--<slug>.md

使用简短、稳定的 slug（kebab-case）。如果不确定，请询问标题。

3) 撰写笔记

使用 assets/note-template.md 中的模板。 至少包含以下部分：

• 摘要（简短）
• 详情（仅包含重要内容）
• 任务（复选框）
• 附件（路径和链接）

4) 存储附件（必须）

始终将附件文件存储在与笔记文件相同的文件夹中。

示例：

• 笔记：notes/2026/02/2026-02-11--example.md
• 附件：
  • notes/2026/02/2026-02-11--example--1.jpg
  • notes/2026/02/2026-02-11--example--2.mp4

规则：

• 不要将此工作流中的笔记附件存储在 assets/images 或 assets/audio 下。
• 使用确定性的后缀：--1、--2、……
• 在笔记 Markdown 中使用相对路径。

5) 在笔记 Markdown 中嵌入图像（必须）

每个图像附件都必须包含内联 Markdown 图像，以便在笔记中显示：

• ![<short-alt-text>](./<attachment-filename>)

对于非图像文件（视频／音频／文档），请在“附件”下使用普通 Markdown 链接。

6) 删除敏感信息（必须）

提交前，扫描笔记（以及任何粘贴的片段），查找：

• API 密钥／令牌／密码／私钥

如果发现：

• 替换为 [REDACTED_SECRET]
• 如果仍有歧义，请在提交前询问

7) 提取任务 → Kanban

更新 KANBAN.md：

• 将新任务添加到待办事项
• 每项任务都应包含指向笔记路径的链接

8) 维护 README 索引（必须）

更新笔记和 KANBAN.md 后，手动更新笔记版本库的 README.md：

• 更新概览计数（笔记总数、任务总数）
• 更新笔记索引表，添加指向最新笔记的链接

9) 提交并推送（提供链接时必须）

提交信息格式约定：

• note: add <short-title>
• kanban: add tasks from <slug>
• note: update <slug>
• docs: update notes README（如果 README 有更改）

远程版本库存在时，始终推送，以确保提供给用户的 GitHub 链接有效。 用户调用此技能后，不要再额外询问是否确认推送。

10) 返回 GitHub 链接（必须）

报告任何笔记操作完成时，必须包含：

• 每个新建／更新笔记 Markdown 文件的 GitHub 链接
• 每个新增附件媒体文件的 GitHub 链接
• 提交哈希

链接格式：

• https://github.com/<owner>/<repo>/blob/main/<relative-path>

通过笔记版本库的 git remote get-url origin 检测远程 URL，以构建正确的链接。

预期输出

笔记保存并推送后，完成报告格式如下：

Note saved: notes/2026/04/2026-04-19--project-meeting.md

## Summary
Quick sync on Q2 roadmap priorities.

## Tasks added to KANBAN.md
- [ ] Draft PRD for feature X  → notes/2026/04/2026-04-19--project-meeting.md
- [ ] Schedule follow-up with design team

Committed: 3e4f1a2
GitHub: https://github.com/user/notes/blob/main/notes/2026/04/2026-04-19--project-meeting.md

边缘情况

• 重复笔记：如果同一天已存在相同 slug 的笔记文件，请在 slug 后追加 -2 后缀（例如，2026-04-19--standup-2.md），而不是覆盖文件。提交前提醒用户。
• 附件过大：如果二进制附件超过 50 MB，请勿直接提交。将其存储在仓库之外，在笔记中添加占位注释（``），并通知用户。
• 未配置 git 仓库：如果未设置 NOTES_REPO，且不存在标记文件，请在写入任何文件前向用户询问仓库路径。不要悄悄将文件写入当前工作目录。

验收标准

• 笔记已创建在正确路径（notes/YYYY/MM/YYYY-MM-DD--<slug>.md）
• 所有附件都存储在与笔记相同的文件夹中，并使用确定性后缀
• 图片已使用 ![alt](./filename) 语法内嵌在笔记中
• 提交前已检测并脱敏笔记内容中的机密信息
• 从笔记中提取的任务已添加到 KANBAN.md 的 Backlog 下，并附有指向笔记的链接
• README.md 索引已更新笔记数量，并添加了新笔记的链接
• 更改已提交并推送；完成消息中已提供 GitHub 链接

步骤完成报告

完成每个主要步骤后，请按以下格式输出状态报告：

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

根据步骤实际验证的内容调整检查项名称。通过使用 √，失败使用 ×，补充简短背景信息使用 —。“Criteria”行概述已满足的验收标准数量。“Result”行给出总体结论。

接收（第 1 步，共 4 步）

◆ Intake (step 1 of 4 — input processing)
··································································
  Input received:         √ pass
  Type detected:          √ pass (text/voice/image/file)
  Content parsed:         √ pass
  [Criteria]:             √ 3/3 met
  ____________________________
  Result:                 PASS

处理（第 2 步，共 4 步）

◆ Processing (step 2 of 4 — note creation)
··································································
  Note written:           √ pass
  Attachments stored:     √ pass (same folder as note)
  Secrets redacted:       √ pass — no secrets found
  [Criteria]:             √ 3/3 met
  ____________________________
  Result:                 PASS

整理（第 3 步，共 4 步）

◆ Organization (step 3 of 4 — kanban and index)
··································································
  Tasks extracted:        √ pass — 2 tasks added
  Kanban updated:         √ pass — tasks in Backlog
  Index maintained:       × fail — README count not updated
  [Criteria]:             √ 2/3 met
  ____________________________
  Result:                 PARTIAL

发布（第 4 步，共 4 步）

◆ Publish (step 4 of 4 — git push and reporting)
··································································
  Committed:              √ pass
  Pushed:                 √ pass
  Links reported:         √ pass — GitHub links included
  [Criteria]:             √ 3/3 met
  ____________________________
  Result:                 PASS

每日例行事项

• 日终：列出今天的笔记 + 提出重新整理建议（标签 / 合并 / 拆分）
• 每天 10–15 分钟：审查 Backlog → 选取任务 → 移至 In Progress → Done

参考资料

• 仓库流程规则：笔记仓库根目录中的 AGENTS.md
• 脱敏 + 工作流政策：笔记仓库根目录中的 POLICY.md