From ad668fbcd34e8b8f7451cda6bcb58e4eece4789e Mon Sep 17 00:00:00 2001 From: ingjieye Date: Wed, 9 Sep 2026 16:48:48 +0800 Subject: [PATCH] Ship the agent skill in-repo and document installing it The skill only existed on my machine, so nobody else could get it. It now lives at skills/apple-notes/SKILL.md and the README covers installing it alongside the CLI. Adds an agent-driven install path: pointing an agent at the README is enough, since it now carries a collapsed block of literal setup steps -- platform check, CLI install with a pipx fallback, skill fetch, and a verification run -- plus what the two likely failures (no database, no permission) mean. Drops the local-checkout path from the skill's install hint, which was only valid on my machine. Co-Authored-By: Claude Opus 5 --- README.md | 57 ++++++++++++++++++++ skills/apple-notes/SKILL.md | 103 ++++++++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+) create mode 100644 skills/apple-notes/SKILL.md diff --git a/README.md b/README.md index 348d9ab..ccb2c51 100644 --- a/README.md +++ b/README.md @@ -80,6 +80,16 @@ create and edit notes. The two compose well — see Requires macOS and Python 3.10+. +### Just ask your agent + +If you use Claude Code, Claude Desktop, or any coding agent, point it at this +file and it has everything it needs: + +> Read https://github.com/ingjieye/apple-notes-cli/blob/main/README.md and set +> it up, including the skill. + +### The CLI + ```bash uv tool install git+https://github.com/ingjieye/apple-notes-cli # or @@ -96,6 +106,53 @@ uv run python -m apple_notes_cli recent macOS may ask you to grant your terminal access to the Notes container the first time. Nothing here needs Full Disk Access on its own. +### The agent skill + +[`skills/apple-notes/SKILL.md`](skills/apple-notes/SKILL.md) teaches an agent +to use this CLI — when to reach for it, how to page from search results to full +note bodies, and what its limits are. Drop it in place: + +```bash +mkdir -p ~/.claude/skills/apple-notes +curl -fsSL https://raw.githubusercontent.com/ingjieye/apple-notes-cli/main/skills/apple-notes/SKILL.md \ + -o ~/.claude/skills/apple-notes/SKILL.md +``` + +Use `.claude/skills/` inside a project instead of `~/.claude/skills/` to scope +it to that project. Then ask your agent things like "what did I note about the +cluster migration?" or "找一下我记过的会议决定". + +
+Setup steps, if you are an agent reading this + +```bash +# 1. macOS only; bail out early elsewhere. +[ "$(uname)" = "Darwin" ] || { echo "macOS required"; exit 1; } + +# 2. Install the CLI (uv preferred, pipx as fallback). +if command -v uv >/dev/null; then + uv tool install git+https://github.com/ingjieye/apple-notes-cli +else + pipx install git+https://github.com/ingjieye/apple-notes-cli +fi + +# 3. Install the skill. +mkdir -p ~/.claude/skills/apple-notes +curl -fsSL https://raw.githubusercontent.com/ingjieye/apple-notes-cli/main/skills/apple-notes/SKILL.md \ + -o ~/.claude/skills/apple-notes/SKILL.md + +# 4. Verify against the real store. Exit 1 from `search` just means no match. +apple-notes folders | head -5 +apple-notes recent -n 3 +``` + +If step 4 reports the database is missing, Notes.app has never been launched on +this machine. If it raises a permission error, the terminal needs access to the +Notes container — that is a macOS prompt the user has to accept, not something +you can grant. + +
+ ## Commands ``` diff --git a/skills/apple-notes/SKILL.md b/skills/apple-notes/SKILL.md new file mode 100644 index 0000000..4785bcc --- /dev/null +++ b/skills/apple-notes/SKILL.md @@ -0,0 +1,103 @@ +--- +name: apple-notes +description: Search, read, and export the user's local Apple Notes via the apple-notes CLI, which reads the Notes SQLite store directly. Use whenever the user asks about their own notes — 查笔记、搜索笔记、我的笔记里、备忘录、Apple Notes、我记过什么、找一下我写的、导出笔记 — or asks to find, recall, summarize, or cross-reference something they wrote down. Also use when the user asks what they noted about a topic, person, meeting, or project, or wants notes exported to Markdown. +--- + +# Apple Notes + +Query the user's Apple Notes through the `apple-notes` CLI. It reads +`~/Library/Group Containers/group.com.apple.notes/NoteStore.sqlite` read-only +and always reflects the live store — there is no cache and no staleness. + +## Check availability first + +```bash +command -v apple-notes || echo "not installed" +``` + +If missing, install it: + +```bash +uv tool install git+https://github.com/ingjieye/apple-notes-cli +``` + +## Commands + +```bash +apple-notes search "" [-n N] [--regex] [--case-sensitive] [--folder F] [--since 2d] [--json] +apple-notes recent [-n N] [--since 6h] [--folder F] [--json] +apple-notes show [--plain] [--json] +apple-notes folders [--json] +apple-notes export [--incremental] +``` + +## How to use it + +**Always use `--json` when you need to reason over results.** The text output +is for humans; JSON gives you `pk`, `title`, `folder`, `created`, `modified`, +`match_count`, and `snippets`. + +```bash +apple-notes search "kubernetes" --json +``` + +**Two-step reads.** `search` and `recent` return metadata and snippets, not +full bodies. To read a note, take its `pk` and call `show`: + +```bash +apple-notes search "release process" --json # -> pk 4821 +apple-notes show 4821 # full Markdown body +``` + +**Searching is cheap — under a second even for a full store.** Don't hesitate +to run several queries with different wording. The user's notes may be in +Chinese, English, or both, so try both when the first attempt comes up empty: + +```bash +apple-notes search "会议" --json +apple-notes search "meeting" --json +``` + +**Narrow with filters rather than post-processing.** `--folder` matches any +folder path containing the text; `--since` takes `30m`, `6h`, `2d`, `1w`, or an +ISO date. + +```bash +apple-notes recent --since 1w --folder Work --json +apple-notes search "invoice" --since 2026-01-01 --json +``` + +**`--regex` for alternatives.** The query is a literal string by default. + +```bash +apple-notes search "TODO|FIXME|待办" --regex --json +``` + +## Exit codes + +`search` follows `grep`: `0` matched, `1` nothing matched, `2` bad argument or +unreadable database. Exit `1` is a normal empty result, not an error — report +that nothing was found and consider retrying with different wording. + +## Reporting back + +Cite notes by title and folder, not by `pk` — the id is an internal key that +means nothing to the user. Include the modified date when recency matters. +Note bodies can be opened in Notes.app via `notes://showNote?identifier=`, +which `export` writes into frontmatter. + +## Scope and limits + +- **Read-only.** This never writes to the Notes store; doing so would corrupt + CloudKit sync. If the user wants to create or edit a note, say so and offer + AppleScript (`osascript -e 'tell application "Notes" ...'`) instead. +- **Recently Deleted is excluded** by default. Add `--include-trashed` if the + user is looking for something they deleted. +- **Password-protected notes** stay encrypted and unreadable; they are skipped. +- Attachment files are not searched — only note text. `export` copies them. + +## Privacy + +These are the user's personal notes. Read only what the current request needs, +quote no more than answers the question, and never send note content to an +external service unless the user explicitly asks for that.