omnifocus-mcp: Skill for Claude Code

AppleScript + OmniFocus Patterns

This skill covers the hard-won knowledge about scripting OmniFocus via AppleScript. These are not obvious from documentation and have caused real bugs in this project.

Critical: Variable Naming Conflicts

OmniFocus AppleScript has a dangerous quirk: if you use a variable name that matches an OmniFocus property, AppleScript silently reads the property instead of your variable.

Bug-causing names (NEVER use as variables): name, note, status, flagged, completed, sequential, due date, defer date, estimated minutes, repetition rule, repetition method

Safe naming pattern: Always prefix with the entity type:

-- BAD: "name" collides with OmniFocus property
set name to "My Task"
set name of theTask to name  -- reads property of theTask, not your variable!

-- GOOD: prefixed variable name
set taskName to "My Task"
set name of theTask to taskName  -- works correctly

Real bug from this project: A variable called status inside a tell task block caused OmniFocus to read the task's status property instead of the variable value, producing silent data corruption. The elifintervalDays typo story: unit tests passed because they mocked AppleScript, but integration tests against real OmniFocus caught the variable collision. This is why integration tests exist.

Rich Text Notes Limitation

OmniFocus stores notes as rich text internally. The AppleScript API exposes this inconsistently:

• Reading: note of task returns plain text (stripped of formatting)
• Writing: set note of task to "text" replaces the entire note with plain text, destroying any rich text formatting

There is no workaround. You cannot preserve rich text through the AppleScript API. Document this to users and warn when overwriting notes.

Recurring Task Completion

Two ways to complete a task — only one handles recurrence correctly:

-- CORRECT: Creates next occurrence for recurring tasks
mark complete theTask

-- WRONG: Just marks this instance done, no next occurrence spawned
set completed of theTask to true