automating-notes skill
scriptsAutomates Apple Notes on macOS using JXA, PyXA, or PyObjC to manage accounts, folders, and notes with HTML bodies.
- GitHub stars
- 49
- Files
- 11
- Last commit
- Aug 22, 2026
- License
- MIT
- Allowed tools
- 3
What does the automating-notes skill do?
automating-notes automates Apple Notes on macOS using JXA, PyXA, or PyObjC to manage accounts, folders, and notes with HTML bodies.
Summary generated from the skill's SKILL.md.
About the automating-notes skill
Managing Apple Notes on macOS through programmatic commands is what this skill enables for developers and users of macOS. It allows an agent to interact with the Notes application hierarchy, including accounts, folders, and individual notes, by utilizing JXA, PyXA, or PyObjC. When an agent is tasked with creating notes, organizing folders, or querying existing content, it can load this skill to perform these actions directly on the local system.
The skill produces structured notes with HTML bodies, supporting specific tags like headers, lists, and divisions. It handles complex workflows such as ensuring specific folder paths exist for meeting or people-based organization and can use Objective-C or clipboard fallbacks for checklists and attachments when standard dictionary support is insufficient. It relies on Bash, Read, and Write tools to execute these automation scripts. This is specifically designed for macOS environments and is not intended for cross-platform note-taking or collaborative editing.
What an agent can do with it
- 1Organize meeting notes automaticallyCreate a structured folder hierarchy for meetings based on company and date to store new notes.
- 2Generate notes with rich formattingCreate a new note that includes specific HTML headers and div structures for organized content.
- 3Automate folder path creationEnsure a specific nested folder structure exists within an iCloud account before attempting to save a note.
- 4Query and filter existing notesSearch through your notes using specific filters to find or update relevant entries.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the automating-notes skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the automating-notes skill in Plugin
/plugin marketplace add SpillwaveSolutions/automating-mac-apps-plugin /plugin install automating-mac-apps@automating-mac-apps-plugin
Install the automating-notes skill in Claude Code
~/.claude/skills/automating-notes/SKILL.md
$ npx degit SpillwaveSolutions/automating-mac-apps-plugin/plugins/automating-mac-apps-plugin/skills/automating-notes ~/.claude/skills/automating-notesInstall the automating-notes skill in Claude Code (project)
.claude/skills/automating-notes/SKILL.md
$ npx degit SpillwaveSolutions/automating-mac-apps-plugin/plugins/automating-mac-apps-plugin/skills/automating-notes .claude/skills/automating-notesInstall the automating-notes skill in Codex
~/.agents/skills/automating-notes/SKILL.md
$ npx degit SpillwaveSolutions/automating-mac-apps-plugin/plugins/automating-mac-apps-plugin/skills/automating-notes ~/.agents/skills/automating-notesInstall the automating-notes skill in Gemini CLI
~/.gemini/skills/automating-notes/SKILL.md
$ npx degit SpillwaveSolutions/automating-mac-apps-plugin/plugins/automating-mac-apps-plugin/skills/automating-notes ~/.gemini/skills/automating-notesInstall the automating-notes skill in Claude.ai
npx degit SpillwaveSolutions/automating-mac-apps-plugin/plugins/automating-mac-apps-plugin/skills/automating-notes automating-notes && zip -r automating-notes.zip automating-notes # claude.ai → Customize → Skills → + → Create skill → Upload a skill → automating-notes.zip
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablespillwavesolutions/automating-mac-apps-plugin/plugins/automating-mac-apps-plugin/skills/automating-notes is public and reachablegithub.com/spillwavesolutions/automating-mac-apps-plugin/tre ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-08-22github.com/spillwavesolutions/automating-mac-apps-plugin/com ↗Pass
- No download-and-run or credential theft in scripts5 scripts read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/spillwavesolutions/automating-mac-apps-plugin/blo ↗Pass
- Pre-approved tools are scopedBash lets the agent run any shell command without askinggithub.com/spillwavesolutions/automating-mac-apps-plugin/blo ↗Finding
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 191 linesgithub.com/spillwavesolutions/automating-mac-apps-plugin/blo ↗Pass
SKILL.md
View on GitHubAutomating Apple Notes (JXA-first, AppleScript discovery)
Relationship to the macOS automation skill
- Standalone for Notes; reuse
automating-mac-appsfor permissions, shell, and Objective-C/UI scripting patterns. - PyXA Installation: To use PyXA examples in this skill, see the installation instructions in
automating-mac-appsskill (PyXA Installation section).
Core framing
- Notes uses an AEOM hierarchy: Application → Accounts → Folders → Notes (with nested folders).
- Load:
automating-notes/references/notes-basics.mdfor complete specifier reference.
Workflow (default)
- Resolve account/folder explicitly (iCloud vs On My Mac); validate existence and permissions.
- Ensure target path exists (create folders if needed); handle creation failures gracefully.
- Create notes with explicit
nameand HTMLbody; verify creation success. - Query/update with
.whosefilters; batch delete/move as needed; check counts before/after operations. - For checklists/attachments, use clipboard/Objective-C scripting if dictionary support is insufficient; test fallbacks.
- For meeting/people workflows, file notes under
meetings/<company>/<date>-<meeting-title>andpeople/<first>-<last>/...; validate final structure.
Quickstart (ensure path + create)
JXA (Legacy):
const Notes = Application("Notes");
// Ensure folder path exists, creating intermediate folders as needed
function ensurePath(acc, path) {
const parts = path.split("/").filter(Boolean);
let container = acc;
parts.forEach(seg => {
let f; try {
f = container.folders.byName(seg);
f.name(); // Verify access
} catch (e) {
// Folder doesn't exist, create it
f = Notes.Folder({ name: seg });
container.folders.push(f);
}
container = f;
});
return container;
}
try {
// Get iCloud account and ensure meeting folder exists
const acc = Notes.accounts.byName("iCloud");
const folder = ensurePath(acc, "meetings/Acme/2024-07-01-Review");
// Create new note in the folder
folder.notes.push(Notes.Note({
name: "Client Review",
body: "<h1>Client Review</h1><div>Agenda...</div>"
}));
console.log("Note created successfully");
} catch (e) {
console.error("Failed to create note: " + e.message);
}
PyXA (Recommended Modern Approach):
import PyXA
notes = PyXA.Notes()
def ensure_path(account, path):
"""Ensure folder path exists, creating intermediate folders as needed"""
parts = [p for p in path.split("/") if p] # Filter empty parts
container = account
for part in parts:
try:
# Try to find existing folder
folder = container.folders().by_name(part)
folder.name() # Verify access
except:
# Folder doesn't exist, create it
folder = notes.make("folder", {"name": part})
container.folders().push(folder)
container = folder
return container
try:
# Get iCloud account
account = notes.accounts().by_name("iCloud")
# Ensure meeting folder exists
folder = ensure_path(account, "meetings/Acme/2024-07-01-Review")
# Create new note in the folder
note = folder.notes().push({
"name": "Client Review",
"body": "<h1>Client Review</h1><div>Agenda...</div>"
})
print("Note created successfully")
except Exception as e:
print(f"Failed to create note: {e}")
PyObjC with Scripting Bridge:
from ScriptingBridge import SBApplication
notes = SBApplication.applicationWithBundleIdentifier_("com.apple.Notes")
def ensure_path(account, path):
"""Ensure folder path exists, creating intermediate folders as needed"""
parts = [p for p in path.split("/") if p]
container = account
for part in parts:
try:
folder = container.folders().objectWithName_(part)
folder.name() # Verify access
except:
# Create new folder
folder = notes.classForScriptingClass_("folder").alloc().init()
folder.setName_(part)
container.folders().addObject_(folder)
container = folder
return container
try:
# Get iCloud account
accounts = notes.accounts()
account = None
for acc in accounts:
if acc.name() == "iCloud":
account = acc
break
if account:
# Ensure meeting folder exists
folder = ensure_path(account, "meetings/Acme/2024-07-01-Review")
# Create new note
note = notes.classForScriptingClass_("note").alloc().init()
note.setName_("Client Review")
note.setBody_("<h1>Client Review</h1><div>Agenda...</div>")
folder.notes().addObject_(note)
print("Note created successfully")
else:
print("iCloud account not found")
except Exception as e:
print(f"Failed to create note: {e}")
Validation Checklist
- Account access works (iCloud vs On My Mac)
- Folder creation and path resolution succeeds
- Note creation with valid HTML body completes
- Note appears in Notes UI
-
.whosequeries return expected results - Error handling covers missing accounts/folders
HTML & fallbacks
- Allowed tags:
<h1>-<h3>,<b>,<i>,<u>,<ul>/<ol>/<li>,<div>/<p>/<br>,<a>. - Security: Always sanitize HTML input; avoid
<script>,<style>, or event handlers to prevent XSS in rendered notes. - Checklists/attachments: Objective-C/clipboard fallback (Cmd+Shift+L for checklist, paste image via NSPasteboard + System Events).
- Append helper: replace
</body>with extra HTML, or append when missing; validate HTML structure post-modification.
When Not to Use
- Cross-platform note taking (use Notion API, Obsidian, or Markdown files)
- iCloud sync operations requiring status feedback (limited API support)
- Non-macOS platforms
- Rich formatting beyond supported HTML tags
- Collaborative editing workflows (no multi-user support)
What to load
- Basics & specifiers:
automating-notes/references/notes-basics.md - Recipes (create/move/query/ensure path/checklists):
automating-notes/references/notes-recipes.md - Advanced (HTML body rules, attachments/UI, JSON import/export, ObjC bridge):
automating-notes/references/notes-advanced.md - Dictionary/type map:
automating-notes/references/notes-dictionary.md - PyXA API Reference (complete class/method docs):
automating-notes/references/notes-pyxa-api-reference.md
Files in this skill
11automating-notes skill questions
How do I install the automating-notes skill in Claude Code?
Run npx degit SpillwaveSolutions/automating-mac-apps-plugin/plugins/automating-mac-apps-plugin/skills/automating-notes ~/.claude/skills/automating-notes. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the automating-notes skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I handle checklists and attachments?
For checklists and attachments, you may need to use Objective-C or clipboard scripting if the standard dictionary support is insufficient.