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 <noreply@anthropic.com>
This commit is contained in:
ingjieyeandClaude Opus 5 committed
1 parent
07bf3854b7
commit
ad668fbcd3
2 files changed
+160
No files matched your search
@@ -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 "找一下我记过的会议决定".
|
||||
|
||||
<details>
|
||||
<summary>Setup steps, if you are an agent reading this</summary>
|
||||
|
||||
```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.
|
||||
|
||||
</details>
|
||||
|
||||
## Commands
|
||||
|
||||
```
|
||||
|
||||
@@ -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 "<query>" [-n N] [--regex] [--case-sensitive] [--folder F] [--since 2d] [--json]
|
||||
apple-notes recent [-n N] [--since 6h] [--folder F] [--json]
|
||||
apple-notes show <id> [--plain] [--json]
|
||||
apple-notes folders [--json]
|
||||
apple-notes export <dir> [--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=<uuid>`,
|
||||
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.
|
||||
Reference in new issue
Block a user