macOS Contacts

Read, search, and safely create contacts in macOS Contacts (Address Book). Use when the user asks to inspect the native macOS contacts database, search conta...

Security Scan

The skill's files, instructions, and required access are consistent with a macOS Contacts helper: it reads the local AddressBook DB (read-only), uses native APIs or AppleScript for writes, and keeps backups — nothing indicates hidden network exfiltration or unrelated credential access.

Purpose & Capability

Name/description match the included artifacts: SQLite-based read script, Swift/AppleScript write paths, backup/restore and transaction wrappers, and dedupe/merge helpers. The requested capabilities (none: no env vars or external credentials) align with a local-contacts skill.

Instruction Scope

Runtime instructions explicitly target the local macOS Contacts DB and Contacts APIs. Scripts read ~/Library/Application Support/AddressBook/AddressBook-v22.abcddb (sqlite read uses mode=ro) and use osascript/Contacts.framework for writes. This is expected, but note backups and transaction wrappers write files under $HOME/.openclaw/state/macos-contacts (sensitive contact data will be present there). The txn wrapper executes the supplied mutating command and will restore backups on failure — normal for transactional safety but gives the skill the ability to run local mutating commands that you should review before invoking.

Install Mechanism

Instruction-only skill with no installer. Bundled scripts are plain Python, Bash, Swift and AppleScript wrappers that run locally — no external downloads or install steps were included.

Credentials

No environment variables, credentials, or network endpoints are requested. The skill stores runtime backups under ~/.openclaw/state/macos-contacts which is proportional for a backup/txn workflow but could be a privacy consideration since contact data is persisted there.

Persistence & Privilege

always:false and user-invocable:true (default) — normal. The skill does not modify other skills or system-wide agent settings. It creates local backup state under the user's home (expected for rollback functionality).

Scan Findings in Context

[pre-scan-injection-signals-none] expected: Static pre-scan reported no injection or network-exfil patterns. That matches the code: no outbound network calls, no use of remote URLs, and no required credentials.

Assessment

This skill appears coherent and implements local read/write workflows for macOS Contacts. Before installing or running it: (1) review and be comfortable with backups written to ~/.openclaw/state/macos-contacts (these contain contact data and should be protected or cleaned if needed); (2) expect to grant macOS Contacts automation/Contacts.framework permission when running Swift/AppleScript writes; (3) inspect any commands you run under contacts_txn.sh since it executes arbitrary local commands and will restore backups on failure; (4) confirm you have swift/python installed on the target mac; and (5) note there are some minor code quality issues (e.g., a bug in a Merge script's 'originals' construction and a truncated Swift file in the distribution preview) — consider testing in a safe environment or reviewing those files before using in production.

Use this skill for production-safe access to the local macOS Contacts data.

Principles

• Prefer SQLite for reads/search/list because it is fast and flexible.
• Prefer Swift + Contacts.framework for production writes/checks because it uses the native contacts API directly and avoids AppleScript performance/pathology issues. Keep AppleScript as a compatibility fallback only.
• Do not write directly to the AddressBook SQLite database.
• Before any destructive or risky experiment, create a backup of the AddressBook database.
• For normal add-contact operations, writes are non-destructive and do not require touching the DB directly.

Data locations

Primary Contacts database on macOS:

• ~/Library/Application Support/AddressBook/AddressBook-v22.abcddb
• Sidecars may exist:
  • AddressBook-v22.abcddb-wal
  • AddressBook-v22.abcddb-shm

Bundled scripts

scripts/contacts_sqlite.py

Use for read/search/list against the native Contacts SQLite database.

Examples:

python3 scripts/contacts_sqlite.py list --limit 20
python3 scripts/contacts_sqlite.py search "黄"
python3 scripts/contacts_sqlite.py search "1555555"
python3 scripts/contacts_sqlite.py get --name "Huang Liao"
python3 scripts/contacts_sqlite.py exists --phone [phone]

Output defaults to JSON for easy downstream use.

scripts/contacts_swift.swift

Use for production-grade native contact API access via Contacts.framework.

Examples:

swift scripts/contacts_swift.swift count
swift scripts/contacts_swift.swift find --query "Huang"
swift scripts/contacts_swift.swift create   --first-name OpenClaw   --last-name Native   --phone [phone]   --email [e-mail]

Use this path for create and duplicate checks before write.

scripts/contacts_applescript.py

Use for supported writes and API-level reads via Contacts.app.

Examples:

python3 scripts/contacts_applescript.py count
python3 scripts/contacts_applescript.py create \
  --first-name OpenClaw \
  --last-name Demo \
  --phone [phone] \
  --email [e-mail]

Recommended workflow

Read/search flow

1. Use contacts_sqlite.py for fast read/search.
2. If results are ambiguous, refine by phone/email/company.
3. Return structured results first; summarize after.

Create-contact flow

1. Confirm target fields from the user when creating a real contact:
   • first name / last name or display name
   • phone and/or email
   • organization/job title if relevant
2. Use contacts_swift.swift create or contacts_swift.swift update.
3. Duplicate-check before create uses strict matching: phone exact match, email exact match, or full-name exact match when no phone/email is supplied; if a match exists, return it instead of creating a duplicate.
4. For updates, prefer identifier-based precise modification instead of fuzzy matching.
5. Read back the contact to verify success.
6. For delete, require identifier-based targeting and recommend wrapping the command with contacts_txn.sh.
7. Report exactly what changed.

Safety rules

• Do not directly mutate the SQLite DB.
• Do not delete or merge contacts unless the user explicitly asks.
• Before delete/merge/batch update, create a backup or use contacts_txn.sh.
• Treat bulk writes as sensitive; prefer one verified create at a time unless the user explicitly wants batch import.
• If AppleScript permissions fail, report that Contacts automation permission is required.

References

• Read references/schema-notes.md when you need table/field hints for SQLite queries.
• Read references/production-notes.md when designing higher-level automation on top of this skill.

Backup and rollback

Use the bundled transaction helpers before destructive or multi-record write operations.

scripts/contacts_backup.sh

Create a filesystem-level backup of the AddressBook DB and sidecars.

scripts/contacts_restore.sh

Restore a backup directory back into the local AddressBook store.

scripts/contacts_txn.sh

Wrap a mutating command with automatic pre-backup and rollback-on-failure.

Examples:

bash scripts/contacts_backup.sh
bash scripts/contacts_txn.sh swift scripts/contacts_swift.swift update --identifier "CONTACT_ID" --job-title "Manager"
bash scripts/contacts_restore.sh ~/.openclaw/state/macos-contacts/backups/AddressBook-YYYYmmdd-HHMMSS

Dedupe cleanup

Use scripts/contacts_dedupe.sh only after listing duplicates and explicitly deciding which identifier to keep.

Example:

swift scripts/contacts_swift.swift duplicates
bash scripts/contacts_dedupe.sh KEEP_IDENTIFIER DROP_IDENTIFIER_1 DROP_IDENTIFIER_2

This workflow uses transactional delete wrappers so each delete is backed up and can roll back on failure.

Dedupe merge

Use scripts/contacts_merge.swift to plan or apply a merge of duplicate contacts.

Examples:

swift scripts/contacts_merge.swift plan-duplicates
swift scripts/contacts_merge.swift apply-plan --keep KEEP_ID --drop DROP_ID_1 --drop DROP_ID_2

Recommended workflow:

1. Run plan-duplicates
2. Inspect the proposed keep/drop split
3. Wrap apply-plan with contacts_txn.sh before applying