automating-contacts

Automate searching, creating, updating, and grouping contacts in macOS Contacts.app using JXA.

63|12|Updated Mar 9, 2026
One-click install
npx skills add https://github.com/iBz-04/gloamy --skill automating-contacts
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: automating-contacts
Source: https://github.com/iBz-04/gloamy/tree/main/skills/automating-contacts
Command: npx skills add https://github.com/iBz-04/gloamy --skill automating-contacts

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires PyXA, and includes references (resource) and scripts (resource) components.

What problem does it solve?

This Skill helps you automate macOS Contacts operations—finding people, creating or updating records, and managing group membership—without manually clicking through the Contacts app.

Core Features & Use Cases

  • Query and filter contacts using Contacts.app’s AppleScript dictionary as the source of truth, then implementing the same concepts in JXA with specifier reads.
  • Create and upsert contact records with robust make + property assignment patterns, including multi-value fields like emails, phones, and addresses.
  • Manage groups defensively by checking for existence to avoid duplicate membership errors and persisting changes reliably via Contacts.save().
  • Handle tough cases such as TCC permission requirements and image/photo bridge failures with ObjC/clipboard fallback guidance.

Quick Start

Grant Contacts permission if prompted, then ask the skill to upsert a contact by email and add it to a group on your Mac.

Frequently Asked Questions about automating-contacts

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I automate upserting contacts in macOS Contacts by email using JXA?

To automate upserting macOS Contacts by email, use JXA to search existing records via specifier reads, then create or update properties and persist changes with Contacts.save. This pattern safely handles multi-value fields like emails and phones.

How do I manage group membership for Apple Contacts without causing duplicate errors?

Managing Apple Contacts group membership safely requires checking for existing entries before adding contacts to prevent duplicate errors. This defensive approach verifies group existence, updates memberships, and persists changes using Contacts.save.

What is the best way to update multi-value fields like addresses in Apple Contacts via JXA?

The best way to update multi-value fields like addresses in Apple Contacts via JXA is constructing elements via the push method and assigning properties directly. This aligns with the AppleScript dictionary to ensure specifier reads and writes function correctly.

How do I handle TCC permissions when automating macOS Contacts with JXA?

Handling TCC permissions for macOS Contacts automation requires granting Contacts access when prompted by the system. If image or ObjC bridge failures occur, use fallback guidance to manage photo updates via the clipboard.

Can I use PyXA to perform batch-style lookups in macOS Contacts?

Yes, you can use PyXA alongside JXA to perform batch-style lookups in macOS Contacts. This dependency allows you to query and filter contacts using the Contacts.app AppleScript dictionary as the source of truth for automation workflows.

Why does my JXA script fail to persist changes to Apple Contacts groups?

JXA scripts fail to persist Apple Contacts group changes if Contacts.save is not explicitly called after modifying membership. You must construct multi-value elements via push and execute the save command to ensure defensive duplicate-guard logic succeeds.