note-taker（记事员）

Note Taker (Git-managed)

This skill maintains a private notes system in a dedicated git-backed notes repository.

Setup: The notes repo path must be configured. Look for a NOTES_REPO variable in the project's CLAUDE.md or AGENTS.md, or ask the user for the path on first use.

Rule: This skill has side effects (writes + commits + pushes) so it must be user-invoked.

Repo Sync Before Edits (mandatory)

Before creating/updating/deleting files in an existing repository, sync the current branch with remote:

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

If the working tree is not clean, stash first, sync, then restore:

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

If origin is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

Workflow

1) Intake

Accept input as:

• Text: the message content
• Voice: summarize (do not store full transcript unless user asks)
• Image / video / file: copy attachment file and reference it from the note

If the user provides multiple items, treat each as a separate note unless they explicitly want a single combined note.

2) Decide filename + folder

Create processed notes at:

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

Use a short, stable slug (kebab-case). If unsure, ask for a title.

3) Write the note

Use the template in assets/note-template.md. Minimum sections:

• Summary (short)
• Details (only what matters)
• Tasks (checkboxes)
• Attachments (paths + links)

4) Store attachments (mandatory)

Always store attachment files in the same folder as the note file.

Example:

• Note: notes/2026/02/2026-02-11--example.md
• Attachments:

- notes/2026/02/2026-02-11--example--1.jpg - notes/2026/02/2026-02-11--example--2.mp4

Rules:

• Never store note attachments for this workflow under assets/images or assets/audio.
• Keep deterministic suffixes: --1, --2,...
• Use relative paths in note markdown.

5) Embed images in note markdown (mandatory)

For every image attachment, include an inline markdown image so it renders in the note:

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

For non-image files (video/audio/docs), keep normal markdown links under Attachments.

6) Redact secrets (mandatory)

Before committing, scan the note (and any pasted snippets) for:

• API keys / tokens / passwords / private keys

If found:

• replace with [REDACTED_SECRET]
• if ambiguity remains, ask before commit

7) Extract tasks → Kanban

Update KANBAN.md:

• Add new tasks to Backlog
• Each task should include a link to the note path

8) Maintain README index (mandatory)

After updating notes and KANBAN.md, update the notes repo README.md manually:

• Update overview counts (total notes, total tasks)
• Update notes index table with links to latest notes

9) Commit and push (mandatory for reporting links)

Commit message conventions:

• note: add <short-title>
• kanban: add tasks from <slug>
• note: update <slug>
• docs: update notes README (if README changed)

Always push when remote exists, so reported GitHub links are valid for user. Do not ask for extra push confirmation once this skill is invoked by the user.

10) Report back with GitHub links (mandatory)

When reporting completion of any note action, include:

• GitHub link to each new/updated note markdown file
• GitHub link to each attached media file (if added)
• Commit hash

Link format:

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

Detect the remote URL from the notes repo's git remote get-url origin to build correct links.

Expected Output

After a note is saved and pushed, the completion report looks like:

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

Edge Cases

• Duplicate note: If a note file for the same slug already exists on the same date, append a -2 suffix to the slug (e.g., 2026-04-19--standup-2.md) rather than overwriting. Warn the user before committing.
• Attachment too large: If a binary attachment exceeds 50 MB, do not commit it directly. Store it outside the repo, add a placeholder comment in the note (<!-- attachment too large to commit: original-filename.mp4 -->), and notify the user.
• No git repo configured: If NOTES_REPO is not set and no marker file exists, ask the user for the repo path before doing any file writes. Do not silently write to the current working directory.

Acceptance Criteria

• Note is created at the correct path (notes/YYYY/MM/YYYY-MM-DD--<slug>.md)
• All attachments are stored in the same folder as the note with deterministic suffixes
• Images are embedded inline in the note with ![alt](./filename) syntax
• Secrets in note content are detected and redacted before committing
• Tasks extracted from the note are added to KANBAN.md under Backlog with a link back to the note
• README.md index is updated with the note count and a link to the new note
• Changes are committed and pushed; GitHub links are reported in the completion message

Step Completion Reports

After completing each major step, output a status report in this format:

◆ [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

Adapt the check names to match what the step actually validates. Use √ for pass, × for fail, and — to add brief context. The "Criteria" line summarizes how many acceptance criteria were met. The "Result" line gives the overall verdict.

Intake (step 1 of 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

Processing (step 2 of 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

Organization (step 3 of 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

Publish (step 4 of 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

Daily routines

• End-of-day: list today’s notes + propose re-organization (tags / merges / splits)
• Daily 10–15min: review Backlog → pick → move to In Progress → Done

References

• Repo process rules: AGENTS.md in the notes repo root
• Redaction + workflow policy: POLICY.md in the notes repo root