contacts

Search macOS Contacts app for contact details via AppleScript.

1|Updated Feb 15, 2026
One-click install
npx skills add https://github.com/n0rvyn/indie-toolkit --skill contacts-n0rvyn
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: contacts
Source: https://github.com/n0rvyn/indie-toolkit/tree/main/mactools/skills/contacts
Command: npx skills add https://github.com/n0rvyn/indie-toolkit --skill contacts-n0rvyn

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Locate and surface contact details stored in the macOS Contacts app so users no longer need to manually search multiple accounts or apps for phone numbers, emails, addresses, and company metadata.

Core Features & Use Cases

  • Fuzzy and exact name search: Perform partial-name searches to find likely matches and exact-name lookups for full contact details.
  • Detailed contact view: Retrieve phone numbers, labeled emails, formatted postal addresses, company, job title, birthday, and notes.
  • Group handling and listing: List all address book groups and enumerate members of a chosen group with result limits.
  • Use Case: Quickly pull a teammate's phone and email before a call, audit group membership, or export a name list for a meeting.

Quick Start

Search for a contact by name and return their phone numbers and email addresses.

Frequently Asked Questions about contacts

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

FAQPage Schema
How do I search for contact details in the macOS Contacts app using automation?

You can search the macOS Contacts app using Bash and AppleScript to perform fuzzy or exact name searches. This retrieves formatted phone numbers, emails, addresses, company info, and notes without manual lookup.

Can I list all groups and their members from the macOS Contacts app?

Yes, you can list all address book groups and enumerate members of a chosen group. The script supports a configurable max-results parameter to limit the number of contacts returned during group listing.

Does this contact search method require any external dependencies?

No external dependencies are required. It relies on the built-in macOS Contacts app and uses osascript to invoke AppleScript from a Bash wrapper, requiring only a macOS environment to function.

How do I retrieve specific details like phone numbers and emails for a contact?

By performing an exact name lookup, you can retrieve a detailed contact view. This returns labeled emails, formatted postal addresses, phone numbers, company, job title, birthday, and notes fields.

What is the best way to find a teammate's phone and email before a call on macOS?

Use a partial-name fuzzy search to find likely matches quickly. This allows you to pull a teammate's phone and email directly from the macOS Contacts app for immediate use before a meeting.

Are there limitations when using AppleScript to search macOS contacts?

The primary limitation is platform exclusivity; this approach only works within macOS. Additionally, very broad fuzzy searches might return too many results unless properly constrained by the max-results parameter.