macOS Notes
Manage Apple Notes via $SKILL_DIR/scripts/notes.sh. Notes content is stored as HTML internally; the script accepts plain text or HTML body and returns plaintext when reading.
Quick start
List folders
Always list folders first to discover accounts and folder names:
CODEBLOCK0
Output format: account → folder (one per line).
Create a note
CODEBLOCK1
JSON fields:
| Field | Required | Default | Description |
|---|
| INLINECODE2 | yes | - | Note title (becomes the first line / heading) |
| INLINECODE3 |
no | "" | Note content (plain text — converted to HTML automatically) |
|
html | no | "" | Raw HTML body (overrides
body if both provided) |
|
folder | no | default folder | Folder name (from list-folders) |
|
account | no | default account | Account name (from list-folders) |
Read a note
CODEBLOCK2
JSON fields:
| Field | Required | Default | Description |
|---|
| INLINECODE8 | yes | - | Note title (exact match) |
| INLINECODE9 |
no | all folders | Folder to search in |
|
account | no | default account | Account to search in |
List notes
CODEBLOCK3
JSON fields:
| Field | Required | Default | Description |
|---|
| INLINECODE11 | no | default folder | Folder name |
| INLINECODE12 |
no | default account | Account name |
|
limit | no | 20 | Max notes to return |
Search notes
CODEBLOCK4
JSON fields:
| Field | Required | Default | Description |
|---|
| INLINECODE14 | yes | - | Text to search for in note titles |
| INLINECODE15 |
no | default account | Account to search in |
|
limit | no | 10 | Max results to return |
Interpreting natural language
Map user requests to commands:
| User says | Command | Key fields |
|---|
| "Note this down: ..." | INLINECODE17 | INLINECODE18 , INLINECODE19 |
| "Save meeting notes" |
create-note |
title: "Meeting notes — <date>",
body |
| "What did I write about X?" |
search-notes |
query: "X" |
| "Show my notes" |
list-notes | (defaults) |
| "Read my note about X" |
read-note |
name: "X" |
| "Save this in my work notes" |
create-note | Match closest
account/
folder from list-folders |
Example prompts
"Note down the API key format: prefix_xxxx"
CODEBLOCK5
"Show my recent notes"
CODEBLOCK6
"What did I write about passwords?"
CODEBLOCK7
"Read my note about Hinge"
CODEBLOCK8
"Create a meeting summary in my iCloud notes"
"$SKILL_DIR/scripts/notes.sh" list-folders
Then:
CODEBLOCK10
Critical rules
- 1. Always list folders first if the user hasn't specified an account/folder — folder names are reused across accounts
- Specify both account and folder when targeting a specific location —
folder: "Notes" alone is ambiguous - Password-protected notes are skipped — the script cannot read or modify them
- Pass JSON via stdin — never as a CLI argument (avoids leaking data in process list)
- All fields are validated by the script (type coercion, range checks) — invalid input is rejected with an error
- All actions are logged to
logs/notes.log with timestamp, command, and note title - Body uses plain text — newlines in
body are converted to <br> automatically; use html for rich formatting - Note title = first line — Notes.app treats the first line of the body as the note name
macOS Notes
通过 $SKILL_DIR/scripts/notes.sh 管理 Apple Notes。笔记内容以 HTML 格式内部存储；脚本接受纯文本或 HTML 正文，读取时返回纯文本。
快速开始
列出文件夹
始终先列出文件夹以发现账户和文件夹名称：
bash
$SKILL_DIR/scripts/notes.sh list-folders
输出格式：账户 → 文件夹（每行一个）。
创建笔记
bash
echo | $SKILL_DIR/scripts/notes.sh create-note
JSON 字段：
| 字段 | 必需 | 默认值 | 描述 |
|---|
| title | 是 | - | 笔记标题（成为第一行/标题） |
| body |
否 | | 笔记内容（纯文本 — 自动转换为 HTML） |
| html | 否 | | 原始 HTML 正文（如果同时提供，覆盖 body） |
| folder | 否 | 默认文件夹 | 文件夹名称（来自 list-folders） |
| account | 否 | 默认账户 | 账户名称（来自 list-folders） |
读取笔记
bash
echo | $SKILL_DIR/scripts/notes.sh read-note
JSON 字段：
| 字段 | 必需 | 默认值 | 描述 |
|---|
| name | 是 | - | 笔记标题（精确匹配） |
| folder |
否 | 所有文件夹 | 要搜索的文件夹 |
| account | 否 | 默认账户 | 要搜索的账户 |
列出笔记
bash
echo | $SKILL_DIR/scripts/notes.sh list-notes
JSON 字段：
| 字段 | 必需 | 默认值 | 描述 |
|---|
| folder | 否 | 默认文件夹 | 文件夹名称 |
| account |
否 | 默认账户 | 账户名称 |
| limit | 否 | 20 | 最大返回笔记数 |
搜索笔记
bash
echo | $SKILL_DIR/scripts/notes.sh search-notes
JSON 字段：
| 字段 | 必需 | 默认值 | 描述 |
|---|
| query | 是 | - | 在笔记标题中搜索的文本 |
| account |
否 | 默认账户 | 要搜索的账户 |
| limit | 否 | 10 | 最大返回结果数 |
自然语言解释
将用户请求映射到命令：
| 用户说 | 命令 | 关键字段 |
|---|
| 记下这个：... | create-note | title, body |
| 保存会议笔记 |
create-note | title: 会议笔记 — <日期>, body |
| 我写过关于 X 的什么？ | search-notes | query: X |
| 显示我的笔记 | list-notes | （默认值） |
| 读取我关于 X 的笔记 | read-note | name: X |
| 保存在我的工作笔记中 | create-note | 匹配最接近的 account/folder（来自 list-folders） |
示例提示
记下 API 密钥格式：prefix_xxxx
bash
echo {title:API 密钥格式,body:格式：prefixxxxx} | $SKILLDIR/scripts/notes.sh create-note
显示我最近的笔记
bash
echo {} | $SKILL_DIR/scripts/notes.sh list-notes
我写过关于密码的什么？
bash
echo {query:password} | $SKILL_DIR/scripts/notes.sh search-notes
读取我关于 Hinge 的笔记
bash
echo {name:Hinge} | $SKILL_DIR/scripts/notes.sh read-note
在我的 iCloud 笔记中创建会议摘要
bash
$SKILL_DIR/scripts/notes.sh list-folders
然后：
bash
echo {title:会议摘要 — 2026-02-17,body:讨论了路线图。\n- Q1：发布 MVP\n- Q2：迭代,account:iCloud,folder:Notes} | $SKILL_DIR/scripts/notes.sh create-note
关键规则
- 1. 始终先列出文件夹，如果用户未指定账户/文件夹 — 文件夹名称在不同账户间可能重复
- 同时指定账户和文件夹，当定位到特定位置时 — 仅 folder: Notes 会产生歧义
- 跳过受密码保护的笔记 — 脚本无法读取或修改它们
- 通过标准输入传递 JSON — 切勿作为 CLI 参数（避免在进程列表中泄露数据）
- 所有字段均由脚本验证（类型强制转换、范围检查） — 无效输入将被拒绝并返回错误
- 所有操作均记录到 logs/notes.log，包含时间戳、命令和笔记标题
- 正文使用纯文本 — body 中的换行符会自动转换为
；使用 html 进行富文本格式化 - 笔记标题 = 第一行 — Notes.app 将正文的第一行视为笔记名称
