contacts-framework
Read, create, update, and pick contacts using the Contacts and ContactsUI frameworks
Install / Use
npx skills add dpearson2699/swift-ios-skills --skill contacts-frameworkInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of contacts-framework
contacts-framework scores 86/100 on our quality scale, 2428th of 4,698 Development & Engineering skills we index.
Its SKILL.md is 16 KB long, well organised into 32 sections with 18 code examples: a thorough specification that gives an agent plenty to work with.
With 1,143 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
- Our last check on 2026-11-03 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 86/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
contacts-framework compared with similar skills
All 4 of these similar skills score higher than contacts-framework; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| contacts-framework (this skill)by dpearson2699 | 86 | 1.1k | 4mo ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.md |
| lobehubby lobehub | 100 | 85.6k | today | MCP Server |
Frequently asked questions
- How do I install contacts-framework?
- Run
npx skills add dpearson2699/swift-ios-skills --skill contacts-framework. The install tabs above show the steps for each supported agent. - Which AI agents does contacts-framework work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is contacts-framework safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 86/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is contacts-framework still maintained?
- The repository was last updated about 4 months ago. That is recent enough to be usable, but agent tooling moves fast, so check the instructions against your agent's current version.
Skill content
View source on GitHubname: contacts-framework description: "Read, create, update, and pick contacts using the Contacts and ContactsUI frameworks. Use when fetching contact data, saving new contacts, wrapping CNContactPickerViewController in SwiftUI, handling contact permissions, or working with CNContactStore fetch and save requests."
Contacts Framework
Use CNContactStore, CNSaveRequest, and CNContactPickerViewController to
fetch, create, update, or pick contacts in Swift 6.3 / iOS 26+ apps.
Contents
- Setup
- Authorization
- Fetching Contacts
- Key Descriptors
- Creating and Updating Contacts
- Contact Picker
- Observing Changes
- Common Mistakes
- Review Checklist
- References
Setup
Project Configuration
- Add
NSContactsUsageDescriptionto Info.plist explaining why the app accesses contacts. The app crashes if it uses contact data APIs without this key. - No additional capability or entitlement is required for ordinary Contacts access.
- Add
com.apple.developer.contacts.notesonly when reading or writingCNContactNoteKey/CNContact.note; this entitlement requires Apple approval before public distribution.
Imports
@preconcurrency import Contacts // CNContactStore, CNSaveRequest, CNContact
import ContactsUI // CNContactPickerViewController
Authorization
Request access before fetching or saving contacts. The picker (CNContactPickerViewController)
does not require authorization -- the system grants access only to the contacts
the user selects.
let store = CNContactStore()
func requestAccess() async throws -> Bool {
return try await store.requestAccess(for: .contacts)
}
// Check current status without prompting
func checkStatus() -> CNAuthorizationStatus {
CNContactStore.authorizationStatus(for: .contacts)
}
Authorization States
| Status | Meaning |
|---|---|
| .notDetermined | User has not been prompted yet |
| .authorized | Full read/write access granted |
| .denied | User denied access; direct to Settings |
| .restricted | Parental controls or MDM restrict access |
| .limited | iOS 18+: user granted access to selected contacts only |
Treat both .authorized and .limited as usable Contacts API states. With
.limited, fetch, edit, and delete operations only apply to contacts the user
granted or the app created. Use ContactAccessButton or
contactAccessPicker(isPresented:completionHandler:) to let users add contacts
to the app's limited-access set.
Fetching Contacts
Use unifiedContacts(matching:keysToFetch:) for predicate-based queries.
Use enumerateContacts(with:usingBlock:) for batch enumeration of all contacts.
For large cached address books, first fetch identifiers, then fetch detailed
contacts in batches by identifier.
Fetch by Name
func fetchContacts(named name: String) throws -> [CNContact] {
let predicate = CNContact.predicateForContacts(matchingName: name)
let keys: [CNKeyDescriptor] = [
CNContactGivenNameKey as CNKeyDescriptor,
CNContactFamilyNameKey as CNKeyDescriptor,
CNContactPhoneNumbersKey as CNKeyDescriptor
]
return try store.unifiedContacts(matching: predicate, keysToFetch: keys)
}
Fetch by Identifier
func fetchContact(identifier: String) throws -> CNContact {
let keys: [CNKeyDescriptor] = [
CNContactGivenNameKey as CNKeyDescriptor,
CNContactFamilyNameKey as CNKeyDescriptor,
CNContactEmailAddressesKey as CNKeyDescriptor
]
return try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)
}
Enumerate All Contacts
Perform I/O-heavy enumeration off the main thread.
func fetchAllContacts() throws -> [CNContact] {
let keys: [CNKeyDescriptor] = [
CNContactGivenNameKey as CNKeyDescriptor,
CNContactFamilyNameKey as CNKeyDescriptor
]
let request = CNContactFetchRequest(keysToFetch: keys)
request.sortOrder = .givenName
var contacts: [CNContact] = []
try store.enumerateContacts(with: request) { contact, _ in
contacts.append(contact)
}
return contacts
}
Key Descriptors
Only fetch the properties you need. Accessing an unfetched property throws
CNContactPropertyNotFetchedException.
Common Keys
| Key | Property |
|---|---|
| CNContactGivenNameKey | First name |
| CNContactFamilyNameKey | Last name |
| CNContactPhoneNumbersKey | Phone numbers array |
| CNContactEmailAddressesKey | Email addresses array |
| CNContactPostalAddressesKey | Mailing addresses array |
| CNContactImageDataKey | Full-resolution contact photo |
| CNContactThumbnailImageDataKey | Thumbnail contact photo |
| CNContactBirthdayKey | Birthday date components |
| CNContactOrganizationNameKey | Company name |
Composite Key Descriptors
Use CNContactFormatter.descriptorForRequiredKeys(for:) to fetch all keys needed
for formatting a contact's name.
let nameKeys = CNContactFormatter.descriptorForRequiredKeys(for: .fullName)
let keys: [CNKeyDescriptor] = [nameKeys, CNContactPhoneNumbersKey as CNKeyDescriptor]
Creating and Updating Contacts
Use CNMutableContact to build new contacts and CNSaveRequest to persist changes.
Creating a New Contact
func createContact(givenName: String, familyName: String, phone: String) throws {
let contact = CNMutableContact()
contact.givenName = givenName
contact.familyName = familyName
contact.phoneNumbers = [
CNLabeledValue(
label: CNLabelPhoneNumberMobile,
value: CNPhoneNumber(stringValue: phone)
)
]
let saveRequest = CNSaveRequest()
saveRequest.add(contact, toContainerWithIdentifier: nil) // nil = default container
try store.execute(saveRequest)
}
Updating an Existing Contact
You must fetch the contact with the properties you intend to modify, create a mutable copy, change the properties, then save.
func updateContactEmail(identifier: String, email: String) throws {
let keys: [CNKeyDescriptor] = [
CNContactEmailAddressesKey as CNKeyDescriptor
]
let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)
guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
mutable.emailAddresses.append(
CNLabeledValue(label: CNLabelWork, value: email as NSString)
)
let saveRequest = CNSaveRequest()
saveRequest.update(mutable)
try store.execute(saveRequest)
}
Deleting a Contact
func deleteContact(identifier: String) throws {
let keys: [CNKeyDescriptor] = [CNContactIdentifierKey as CNKeyDescriptor]
let contact = try store.unifiedContact(withIdentifier: identifier, keysToFetch: keys)
guard let mutable = contact.mutableCopy() as? CNMutableContact else { return }
let saveRequest = CNSaveRequest()
saveRequest.delete(mutable)
try store.execute(saveRequest)
}
Save Result and Recovery
try store.execute(saveRequest) returning without throwing is the save success
checkpoint. Update an app-side cache or success UI only after that return. If it
throws, surface or propagate the error, keep the unsaved intent available to the
user, and correct the known cause—such as authorization, a read-only container,
or invalid input—before building a fresh request. Serialize overlapping saves,
do not access a request while execute(_:) is using it, and refetch a possibly
stale contact before a corrected retry when access permits. Do not blindly
repeat the same destructive request or require a universal read-back that the
current access level may not permit. Load
Extended Contacts Patterns for multi-select,
vCard, and optimized-search workflows.
Contact Picker
CNContactPickerViewController lets users pick contacts without granting full
Contacts access. The app receives only the selected contact data.
SwiftUI Wrapper
import SwiftUI
import ContactsUI
struct ContactPicker: UIViewControllerRepresentable {
@Binding var selectedContact: CNContact?
func makeUIViewController(context: Context) -> CNContactPickerViewController {
let picker = CNContactPickerViewController()
picker.delegate = context.coordinator
return picker
}
func updateUIViewController(_ uiViewController: CNContactPickerViewController, context: Context) {}
func makeCoordinator() -> Coordinator {
Coordinator(self)
}
final class Coordinator: NSObject, CNContactPickerDelegate {
let parent: ContactPicker
init(_ parent: ContactPicker) {
self.parent = parent
}
func contactPicker(_ picker: CNContactPickerViewController, didSelect contact: CNContact) {
parent.selectedContact = contact
}
func contactPickerDidCancel(_ picker: CNContactPickerViewController) {
parent.selectedContact = nil
}
}
}
Using the Picker
struct ContactSelectionView: View {
@State private var selectedContact: CNContact?
@State private var showPicker = false
var body: some View {
VStack {
if let contact = selectedContact {
Text("\(contact.givenName) \(contact.familyName)")
}
Button("Select Contact") {
showPicker = true
}
}
.sheet(isPresented: $showPicker) {
ContactPicker(selectedContact: $selectedContact)
}
}
}
Filtering the Picker
Use predicates to control which contacts appear and what the user can select.
let picker = CNContactPickerViewController()
// Only show contacts that have an email address
picker.predicateForEnablingContact = NSPredicate(format: "emailAddresses.@count > 0")
// Selecting a contact returns it directly (no detail card)
picker.predicateForSelectionOfContact = NSPredicate(value: true)
Observing Changes
Listen for external contact database changes to refresh cached data.
func observeContactChanges() {
NotificationCenter.default.addObserver(
forName: .CNContactStoreDidChange,
object: nil,
queue: .main
) { _ in
// Refetch contacts -- cached CNContact objects are stale
refreshContacts()
}
}
Common Mistakes
DON'T: Fetch all keys when you only need a name
Over-fetching wastes memory and slows queries, especially for contacts with large photos.
// WRONG: Fetches far more than the UI displays, including full-resolution photos
let keys: [CNKeyDescriptor] = [
CNContactFormatter.descriptorForRequiredKeys(for: .fullName),
CNContactImageDataKey as CNKeyDescriptor,
CNContactPhoneNumbersKey as CNKeyDescriptor,
CNContactEmailAddressesKey as CNKeyDescriptor,
CNContactPostalAddressesKey as CNKeyDescriptor,
CNContactBirthdayKey as CNKeyDescriptor
]
// CORRECT: Fetch only what you display
let keys: [CNKeyDescriptor] = [
CNContactGivenNameKey as CNKeyDescriptor,
CNContactFamilyNameKey as CNKeyDescriptor
]
DON'T: Access unfetched properties
Accessing a property that was not in keysToFetch throws
CNContactPropertyNotFetchedException at runtime.
// WRONG: Only fetched name keys, now accessing phone
let keys: [CNKeyDescriptor] = [CNContactGivenNameKey as CNKeyDescriptor]
let contact = try store.unifiedContact(withIdentifier: id, keysToFetch: keys)
let phone = contact.phoneNumbers.first // CRASH
// CORRECT: Include the key you need
let keys: [CNKeyDescriptor] = [
CNContactGivenNameKey as CNKeyDescriptor,
CNContactPhoneNumbersKey as CNKeyDescriptor
]
DON'T: Mutate a CNContact directly
CNContact is immu
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
lobehub
85.6k🤯 LobeHub - Super-Agents on Your Team. Add super-agents to the chats your team already uses.They take on work by themselves and get better every week.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
