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.