notes

Use the OS notes integration to query and manage native macOS Notes.app — listing folders and accounts, searching notes by title or body, reading note content, creating new notes, updating existing notes, and deleting notes. Use even when you think you know the answer — Notes state is dynamic; only the live API reflects current content, folder structure, and iCloud-sync updates. Do not use for: non-macOS systems, other note apps (Obsidian, Bear, Logseq, Notion, etc.), or generic note-taking-methodology advice.

Best use case

notes is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Use the OS notes integration to query and manage native macOS Notes.app — listing folders and accounts, searching notes by title or body, reading note content, creating new notes, updating existing notes, and deleting notes. Use even when you think you know the answer — Notes state is dynamic; only the live API reflects current content, folder structure, and iCloud-sync updates. Do not use for: non-macOS systems, other note apps (Obsidian, Bear, Logseq, Notion, etc.), or generic note-taking-methodology advice.

Teams using notes should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

  • You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

  • You only need a quick one-off answer and do not need a reusable workflow.
  • You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/notes/SKILL.md --create-dirs "https://raw.githubusercontent.com/speednet-software/speedwave/main/containers/claude-resources/skills/integrations/notes/SKILL.md"

Manual Installation

  1. Download SKILL.md from GitHub
  2. Place it in .claude/skills/notes/SKILL.md inside your project
  3. Restart your AI agent — it will auto-discover the skill

How notes Compares

Feature / AgentnotesStandard Approach
Platform SupportNot specifiedLimited / Varies
Context Awareness High Baseline
Installation ComplexityUnknownN/A

Frequently Asked Questions

What does this skill do?

Use the OS notes integration to query and manage native macOS Notes.app — listing folders and accounts, searching notes by title or body, reading note content, creating new notes, updating existing notes, and deleting notes. Use even when you think you know the answer — Notes state is dynamic; only the live API reflects current content, folder structure, and iCloud-sync updates. Do not use for: non-macOS systems, other note apps (Obsidian, Bear, Logseq, Notion, etc.), or generic note-taking-methodology advice.

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

SKILL.md Source

Notes access goes through MCP Hub. All notes methods are on the injected `os` global — there is no separate `notes` global. Use `search_tools` to discover the live schema, then `execute_code` to call `os.*` methods.

## Workflow

1. `search_tools({ query: "notes", detail_level: "names_only", service: "os" })` — discover available tool names.
2. `search_tools({ query: "<toolName>", detail_level: "full_schema", service: "os" })` — get exact parameter schema before first use.
3. `execute_code` — call via `os.<toolName>(params)` using parameter names from the schema.

Always run steps 1–2 before guessing a tool name or parameter. The live schema is the source of truth.

## Key methods

- `os.listNoteFolders()` — list all folders across all accounts (no params). Returns `id`, `name`, `account_name`, `note_count`.
- `os.listNotes({ folder_id?, limit? })` — list notes, optionally filtered by folder. Default limit: 50.
- `os.getNote({ id })` — fetch a single note by ID with full `body` (HTML) and `plaintext` fields.
- `os.searchNotes({ query, folder_id?, limit? })` — search by title and body text. Default limit: 20.
- `os.createNote({ title, body?, folder_id? })` — create a note; `folder_id` optional (uses default folder if omitted).
- `os.updateNote({ id, title?, body? })` — update title or body; at least one of `title`/`body` required.
- `os.deleteNote({ id })` — permanently delete a note by ID.

## Pitfalls

- **All methods are on `os.*`, not `notes.*`** — there is no separate notes global.
- **Accounts reflect System Settings → Internet Accounts.** Notes.app supports iCloud, On My Mac, and IMAP-based accounts. `listNoteFolders` returns folders from all accounts; `account_name` distinguishes them.
- **Folder names are case-sensitive.** Call `os.listNoteFolders()` first if the user refers to a folder by name; pass the resolved `id` to other calls. Nested folders are supported — the returned `name` is the folder's own name, not its full path.
- **`body` field is HTML; `plaintext` is the stripped text.** `getNote` returns both. Use `plaintext` for text processing; use `body` only if you need to inspect or preserve rich formatting.
- **`searchNotes` matches against `plaintext`, not raw HTML.** Exact-substring matches on HTML-formatted content (bold, tables) may miss text that is visually present. If a search returns no results, try a shorter or simpler query.
- **Write/delete confirmation.** Per `CLAUDE.md`: `createNote`, `updateNote`, and `deleteNote` require explicit user confirmation before execution. `listNoteFolders`, `listNotes`, `getNote`, and `searchNotes` are read-only and need no confirmation.
- **Attachments, drawings, and tables have limited text support.** The API returns text content only; inline images, sketches, and table formatting are not accessible or writable via this integration.
- **macOS TCC permission is pre-validated by Speedwave Settings.** If this integration is enabled, assume access is granted; do not ask the user to check permissions.

## When NOT to use

- Non-macOS host environments.
- Third-party note apps (Obsidian, Bear, Notion, Logseq, Evernote, Apple Notes on iOS only, etc.).
- Plain text files in the project — use the `Read`/`Write` tools on `/workspace` instead.
- Generic note-taking methodology or knowledge-management advice not tied to the user's local Notes.app data.

Related Skills

speedwave-product-showcase

7
from speednet-software/speedwave

Build a self-contained, dependency-free animated "live product" demo for a landing page — a step carousel that faithfully recreates the real app UI (chat, settings, integrations, logs…) using only HTML + scoped CSS + one inline rAF script. Use when asked to add an animated product walkthrough / hero demo / "show the app in motion" to a marketing site.

sharepoint

7
from speednet-software/speedwave

Use SharePoint integration to read, write, and manage files, lists, list items, columns, and pages on the configured Microsoft 365 site. Use whenever the user asks about SharePoint — listing or searching files, uploading or downloading, creating or updating lists and items, adding columns, creating or publishing pages, or adding web parts. Use even when you think you know the answer — site state is dynamic; only the live API reflects current files, list items, or page versions. Do not use for: Microsoft 365 Outlook/Teams/OneDrive operations not surfaced via SharePoint, cross-site or cross-tenant ops (only the configured site), or generic Microsoft Graph questions.

reminders

7
from speednet-software/speedwave

Use the OS reminders integration to query and manage native macOS Reminders.app — listing reminder lists, fetching reminders by list or due date, creating new reminders, updating, completing, or deleting them. Use even when you think you know the answer — Reminders state is dynamic; only the live API reflects current items, due dates, and completion status. Do not use for: non-macOS systems, other reminder/task apps (Todoist, TickTick, etc.), or anything outside the user's local Reminders.app.

redmine

7
from speednet-software/speedwave

Use Redmine integration to query and manage Redmine projects, issues, time entries, journals, comments, relations, and user mappings. Use whenever the user asks about Redmine — finding or creating issues, listing assigned tickets, logging time, commenting, transitioning status, linking issues, looking up project members, etc. Use even when you think you know the answer — issue and project state are dynamic; only the live API reflects current assignments, status, or time entries. Do not use for: project management theory, anything outside the configured Redmine instance, or wiki content (no wiki tools available — use playwright or paste the URL).

playwright

7
from speednet-software/speedwave

Use Playwright integration to browse the web, take screenshots, and interact with web pages in a headless Chromium browser. Use whenever the user asks to screenshot a page, navigate to a URL, check what is on a website, fill a form, click through a flow, or extract content from a rendered page. Use even when you think you know the page content — websites change constantly; only the live browser reflects current rendering, JS-injected content, and dynamic state. Do not use for: fetching plain HTML or JSON that does not need JavaScript rendering (use WebFetch), scraping that violates the site's terms of service, anything requiring credentials the user has not provided, or local file access (the Playwright container has no /workspace mount).

office

7
from speednet-software/speedwave

Use Office integration to read, create, edit, and convert Word/Excel/PowerPoint/PDF documents, and to render charts. Use whenever the user asks about working with .docx, .xlsx, .pptx, or .pdf files — reading content, creating reports or invoices, editing existing documents, converting between formats, merging or splitting PDFs, or rendering charts. Use even when you think you know the answer — document libraries change between framework versions; only the live tool reflects current Office/PDF format support and chart rendering capabilities. Do not use for: plain text files (read them directly), generic Markdown conversion that does not need PDF output (use built-in tools), or installing document-processing libraries — they are already behind office__* tools.

mail

7
from speednet-software/speedwave

Use the OS mail integration to query the user's native macOS Mail.app — listing mailboxes and accounts, searching messages, reading message bodies and attachments, and sending new mail through the configured accounts. Use even when you think you know the answer — inbox state is dynamic; only the live API reflects current messages, unread counts, and folder organization. Do not use for: web-based mail (Gmail/Outlook web), non-macOS systems, email protocol questions (IMAP/SMTP), or generic email-marketing/composition advice.

gitlab

7
from speednet-software/speedwave

Use GitLab integration to query and manage projects, merge requests, issues, pipelines, branches, commits, files, and releases on the configured GitLab instance. Use whenever the user asks about GitLab — listing MRs, reviewing diffs, opening or merging MRs, creating/closing issues, comparing branches, reading pipeline status, fetching files, searching code, etc. Use even when you think you know the answer — repository state is dynamic and only the live API reflects current MR status, pipeline runs, or issue assignments. Do not use for: plain git operations on the local checkout, GitHub.com (use github), general code review questions, or anything outside the configured GitLab instance.

github

7
from speednet-software/speedwave

Use GitHub integration to query and manage GitHub.com repositories, pull requests, issues, branches, commits, Actions workflow runs, labels, tags, and releases. Use whenever the user asks about GitHub — opening or reviewing PRs, getting PR diffs, listing or commenting on issues, comparing branches, reading workflow logs, creating releases, searching code, etc. Use even when you think you know the answer — repository state is dynamic; only the live API reflects current PR status, workflow runs, or issue assignments. Do not use for: plain git operations on the local checkout, GitLab or self-hosted GitHub Enterprise (out of scope), general code review questions, or any repo not on GitHub.com.

context7

7
from speednet-software/speedwave

Use Context7 to fetch current library/framework/API/SDK/CLI/cloud-service documentation whenever the user asks about a named technology — including setup, configuration, code examples, version migration, library-specific debugging, best practices, and "is X the right way to do Y" questions. Covers popular technologies such as React, Next.js, Angular, Vue, Svelte, Prisma, Drizzle, Express, NestJS, FastAPI, Django, Flask, Spring Boot, Tailwind, shadcn/ui, and any other named library, SDK, API, CLI tool, or cloud service. Use even when you think you know the answer — your training data may not reflect recent changes. Prefer this over web search for library docs. Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.

calendar

7
from speednet-software/speedwave

Use the OS calendar integration to query and manage native macOS Calendar.app — listing calendars, fetching events by date range, creating/updating/deleting events, and checking availability. Use even when you think you know the answer — calendar state is dynamic; only the live API reflects current events, RSVP status, and shared-calendar updates. Do not use for: non-macOS systems, third-party calendar services (Google Calendar API directly, Outlook web, etc.) — those go through their own integrations if configured.

atlassian

7
from speednet-software/speedwave

Use Atlassian integration to query and manage Jira Cloud and Confluence Cloud — Jira issues, comments, transitions, assignments, agile boards/sprints, and Confluence pages, spaces, labels, attachments. Use whenever the user asks about Jira tickets/issues/sprints or Confluence pages/spaces — searching with JQL/CQL, getting or creating issues, transitioning workflows, finding or updating pages, etc. Use even when you think you know the answer — issue and page state are dynamic; only the live API reflects current assignments, transitions, comments, or page revisions. Do not use for: self-hosted Jira/Confluence Server or Data Center (Cloud only), generic project management theory, or anything outside the configured Atlassian site.