Skip to content
Skills Library
Personal productivity · Tool integration

apple-notes

/apple-notes

Read, search, write Apple Notes on macOS and extract their images. Enforces an inbox/ready/done/docs layout per project. Use when the user references Apple Notes, "check my notes", "pull bug reports from Notes", or extract screenshots.

Repository
skills ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/_helper.py

What it does and when to use it

Read, search, write Apple Notes on macOS and extract their images. Enforces an inbox/ready/done/docs layout per project. Use when the user references Apple Notes, "check my notes", "pull bug reports from Notes", or extract screenshots.

Triggers from the description

check my notespull bug reports from Notes
Original author description

Read, search, write Apple Notes on macOS and extract their images. Enforces an inbox/ready/done/docs layout per project. Use when the user references Apple Notes, "check my notes", "pull bug reports from Notes", or extract screenshots.

How it works

  1. Project layout (enforced by init, scanned by all reads)
  2. What each folder means → which one to read
  3. Quick start
  4. Subcommands
  5. Token-efficiency rules
  6. Workflows
  7. Setup
  8. macOS permissions
  9. Long titles & truncation
  10. Limitations
Original SKILL.md headings · 137 lines, 1,498 words
SKILL.md preview
---
name: apple-notes
description: Read, search, write Apple Notes on macOS and extract their images. Enforces an inbox/ready/done/docs layout per project. Use when the user references Apple Notes, "check my notes", "pull bug reports from Notes", or extract screenshots.
---

# Apple Notes

One dispatcher: `scripts/apple-notes <subcommand>`. AppleScript under the hood. Output is plain text by default, `--json` available where useful.

## Project layout (enforced by `init`, scanned by all reads)

```
Firma/                       ← company folder (configurable; default "Firma" in iCloud)
  ProjektA/                  ← one subfolder per app/repo
    inbox/                   ← new, untriaged
    ready/                   ← triaged, ready for work
    done/                    ← merged / shipped
    docs/                    ← templates, briefing, specs — NOT issues
  Projekt-B/
    inbox/  ready/  done/  docs/
```

**Title-prefix convention** (the only requirement, surfaced by `triage`):
`BUG:` `FEAT:` `IDEA:` `FB:` (user feedback) `TECH:` (tech debt / refactor).

**Body**: free-form text. Non-technical partners write plain prose using the BUG / FEAT / IDEA / FB templates seeded under `docs/`. Only the TECH template (the maintainer's own notes) carries a compact `·`-separated metadata first line — agents and `triage` do not require it for any other prefix.

## What each folder means → which one to read

Pick the folder by **intent**. Crucial: a bare `notes <project>` lists *every* status, and `search` spans *every* project + status — so neither answers "what's new". Both will surface long-done and ready items as if they were fresh. This is the #1 mistake: do not answer an "incoming" question from `search` or an unscoped `notes`.

| Folder | Meaning | Read it when the user asks… |
|--------|---------|------------------------------|
| `inbox` | New, untriaged — the **only** "new" surface | "newest bugs", "what's new", "what did my partner report", "any new feedback", "triage the inbox" → `notes <project> --status inbox` (or `triage <project>`) |
| `ready` | Triaged, accepted, waiting for work | "what's ready", "next task", "the backlog" → `notes <project> --status ready` |
| `done` | Merged / shipped — history only | "what shipped", "already fixed", "what's done" → `notes <project> --status done` |
| `docs` | Templates, briefing, specs — **never issues** | only when explicitly asked for a template/spec; never list these as bugs/issues |

**Default rule:** any request about *incoming / new / latest / unhandled / untriaged* items ⇒ scope to **`--status inbox`**. Only widen to `ready`/`done`, or fall back to `search`, when the user *explicitly* asks for those statuses or for an across-everything lookup. When unsure which folder the user means, ask — don't silently pull from all of them.

## Quick start

```bash
S=/path/to/apple-notes/scripts/apple-notes

"$S" init ProjektA            # creates inbox/ready/done/docs + seeds templates+cheatsheet
"$S" resolve                  # auto-map current repo to project (cached)
"$S" notes "$($S resolve)"    # list, grouped by status
"$S" triage ProjektA          # inbox health check (prefix + metadata)
"$S" get ProjektA "BUG: Login flaky"   # plain-text body
"$S" images ProjektA "BUG: Login flaky"  # extract base64 images → JSON paths
```

## Subcommands

| | |
|---|---|
| `init <project>` | Creates the four status folders and seeds `docs/` with five issue templates (`VORLAGE BUG/FEAT/IDEA/FB/TECH`) + an `Anleitung`-cheatsheet for non-technical collaborators. Idempotent; existing notes are never overwritten. `--no-docs` skips the templates. `init --explain` prints the convention. |
| `projects [--json]` | Lists app subfolders of the company folder with note counts. |
| `resolve [REPO]` | Maps a repo name (default: current git toplevel) to a project. Cached at `~/.config/claude/apple-notes/mapping.json`. |
| `notes <project> [--status S] [--limit N] [--preview N] [--json]` | Lists notes; default groups by status. |
| `get <project> <title> [--format text\|html\|raw]` | Reads a note; auto-locates across all status folders. `<title>` may be the exact name, a truncated/ellipsis title as listed, a prefix, or a raw note `id`. Default `text` strips base64 → `[image:N]`. |
| `images <project> <title> [--out DIR]` | Extracts inline base64 images to `~/.cache/claude/apple-notes/images/<slug>/` (dirs `0700`, files `0600`) and prints JSON `[{path,bytes,mime}]`. `--out` overrides the directory. |
| `search <query> [--project NAME] [--json]` | Full-text across all projects + statuses. |
| `create <project> <title> [--status S] [--body-file F]` | Body on stdin or `--body-file`. Default status: `inbox`. |
| `update <project> <title>` / `append <project> <title>` | Replace / append. Auto-locates the note; status stays. |
| `delete <project> <title> --force` | Moves to "Recently Deleted" (recoverable for 30 days). |
| `move <project> <title> <new-status>` | Status transition: `apple-notes move ProjektA "BUG: …" ready`. |
| `triage <project> [--json]` | Inbox health: per-note score (✓ / ⚠) based on whether the title carries one of the configured prefixes (`BUG:` / `FEAT:` / `IDEA:` / `FB:` / `TECH:`). Body content is no longer scored. |
| `config show \| set <k> <v> \| set-mapping <repo> <project>` | Read/write config + manual repo→project overrides. |

## Token-efficiency rules

1. Default `get` format is `text` — base64 images are placeholders, not the LLM payload.
2. `notes` lists `title + date + 80-char preview`, grouped by status.
3. For screenshots: `images <project> <title>` → temp paths → `Read` each path (multimodal). Never paste raw base64.
4. `search` returns the most recent match first; use `--project NAME` to scope.

## Workflows

**Verify every write.** `move`, `create`, `update`, and `init` print `OK` or `ERR:…`. After any write, check that line — on `ERR:` surface it and do **not** report success. For `move`, confirm by re-listing: `apple-notes notes <project> --status <new-status>` must now include the note. Never claim a note was moved/created/updated without seeing it land.

**Pull issues from a partner-maintained inbox**
1. `apple-notes triage <project>` — see which inbox notes are well-formed.
2. `apple-notes notes <project> --status inbox` — full list.
3. `apple-notes get <project> <title>` for content; `apple-notes images …` for screenshots.
4. Present your assessment and propose `apple-notes move <project> <title> ready` (acknowledge, will fix) or `delete --force` (won't fix). Wait for explicit user confirmation before running `delete --force` — deletion is destructive and the agent must not decide it autonomously.
5. After implementation: `apple-notes move <project> <title> done`.

**Always close the loop on processed inbox notes (standing reminder rule)**

Whenever you have *acted on* one or more `inbox` notes in a turn — triaged them, diagnosed them, turned them into a plan/PRD, or fixed them — you MUST end that turn by **offering to move those specific notes to `ready`** (acknowledged / will-fix). List the affected note titles and ask explicitly, e.g. "Soll ich diese N Notizen nach `ready` verschieben?".

- This is a standing reminder that fires on **every** such turn, not a one-off.
- **Never move them autonomously.** Always wait for explicit confirmation — the user may have only partly processed a note, or may want to revisit it later.
- `ready` = "acknowledged, will fix". Reserve `done` for after the work ships, and `delete --force` (still confirmation-gated) for "won't fix".
- If the user declines or stays silent, leave the notes in `inbox` and simply re-offer the next time they are processed.

**Onboarding a new project**
1. Create the project subfolder manually in Apple Notes UI (e.g. `Projekt-B`).
2. `apple-notes init Projekt-B` — folders + templates land.
3. Share the `Anleitung: Bugs und Feedback einbringen` note (in `docs/`) with the human collaborator.

## Setup

First run creates `~/.config/claude/apple-notes/config.json` with defaults:
```json
{
  "account": "iCloud",
  "company_folder": "Firma",
  "statuses": ["inbox", "ready", "done", "docs"],
  "default_status": "inbox",
  "default_image_dir": "~/.cache/claude/apple-notes/images"
}
```
Change with `apple-notes config set <key> <value>`. Pre-existing configs are gently migrated on every run.

Extracted images are private but are not cleaned up automatically. Remove them when no longer needed:
`rm -rf ~/.cache/claude/apple-notes/images`. Configs written by older versions may still point to `/tmp/apple-notes-images`;
change that with `apple-notes config set default_image_dir ~/.cache/claude/apple-notes/images`.

## macOS permissions

Claude Code's host terminal must have **Automation → Notes** enabled in `System Settings → Privacy & Security`. First invocation triggers the prompt; if denied earlier, toggle it back.

## Long titles & truncation

Apple Notes has no separate title field — a note's title **is** its first body line, truncated to ~64 chars + `…` once it gets long. So when a collaborator dumps the whole report into the first line (no line break), the listed title is a truncated ellipsis form while the full text lives in the body.

This is handled transparently: `get`/`update`/`append`/`move`/`delete` resolve a `<title>` that is exact, **truncated**, a prefix, ASCII-`...`, or a raw **note `id`**. For bulletproof addressing across several operations, take the `id` from `notes --json` / `search --json` and pass it as `<title>`. If two notes collide on a prefix, the command aborts as `ambiguous` and asks for the id.

To *prevent* the problem at the source, the seeded `Anleitung`/templates ask collaborators to keep the first line a short title and put detail in the lines below.

## Limitations

- **Inline base64 only**: only images that Apple Notes stored inline are extractable. Video, audio, PDFs, and richly-linked attachments are flagged in the note body (often as ``) but not retrievable via AppleScript.
- **Duplicate / prefix-colliding titles**: when a title query ties across notes, the command aborts as ambiguous — disambiguate with the note `id` (from `--json`) or rename in Apple Notes.
- **Status set is configurable** but enforced by `init` + `move`. Adding a new status: edit `config.json` `statuses` array and re-run `init`.

See [REFERENCE.md](REFERENCE.md) for AppleScript caveats, exit codes, and full subcommand contracts.
Files in this package (5)
  • REFERENCE.md 10 KB
  • SKILL.md 10 KB
  • applescripts/create_note.applescript 1 KB
  • scripts/_helper.py 7 KB
  • scripts/apple-notes 38 KB

Versions

RepositoryScoreLicence
This page · silvio-l/skills100MIT
sweetrb/apple-notes-mcp100MIT
sweetrb/apple-notes-mcp100MIT
AceDataCloud/Skills100Apache-2.0
cowork-os/cowork-os100MIT
microclaw/microclaw100MIT
foxrun-ai/foxrun100MIT
grtninja/skill-arbiter90MIT
craftos-dev/craftbot86MIT

Database snapshot: 13.11.2026 · package version 6a852a4e4f5b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100apple-notes-search
    Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server. Use when the user wants to find, recall, or synthesize something from their notes, or surface non-obvious bridges/related notes. macOS, on-device.
  • 100apple-notes-search
    Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server. Use when the user wants to find, recall, or synthesize something from their notes, or surface non-obvious bridges/related notes. macOS, on-device.
  • 100apple-notes-search
    Semantic + keyword search and connection-discovery across the user's own Apple Notes via the apple-notes MCP server. Use when the user wants to find, recall, or synthesize something from their notes, or surface non-obvious bridges/related notes. macOS, on-device.
  • 100apple-notes-to-obsidian
    Put the user's Apple Notes into an Obsidian vault as Markdown and keep them in sync, using the Exporter Mac app and its exporter command line. Use when asked to move, import, migrate or sync Apple Notes to Obsidian, open Apple Notes in Obsidian, or keep an Obsidian copy of Apple…
  • 90export-apple-notes
    Export the user's Apple Notes to Markdown (or HTML) files on a Mac with the Exporter Mac app and its exporter command line. Use when asked to export Apple Notes, convert notes to markdown or .md files, get notes out of Apple Notes, or save notes as HTML. macOS only.
  • 100notes-management
    Guide for effective use of che-apple-notes-mcp for macOS Apple Notes management. Use when user asks about Apple Notes, 備忘錄, note taking on Mac, creating/searching/organizing notes.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.