Content
85%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured reference skill: invariants-first body with executable snippets, explicit validation boundaries and failure-recovery loops for destructive saves, and clean offloading of extended SwiftUI/picker/vCard patterns to a single well-signaled reference file. The main improvement opportunities are a code example for update/delete and trimming the overlap between the invariants, Common Mistakes, and Review Checklist sections.
Suggestions
Add a short executable Swift example for the update/delete path (fetch with required keys → mutableCopy() → CNSaveRequest.update/delete → execute), since only create and fetch have code.
Consolidate the overlap where 'Common Mistakes' and 'Review Checklist' restate the fetch and mutation invariants verbatim, e.g., by keeping mistakes as one-line cross-references or merging the two sections.
Mention 'address book' and 'vCard' as trigger synonyms in the description to broaden natural matching (vCard import/export is already covered in the body but not surfaced in the description).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumption-respecting — it never explains what the Contacts framework is, and every section carries iOS-specific gotchas (NSContactsUsageDescription termination, the notes entitlement, CNContactPropertyNotFetchedException). Not 5 because "Common Mistakes" and "Review Checklist" restate earlier invariants (e.g., key fetching, pre-execute state changes), which could be consolidated. | 4 / 5 |
Actionability | Contains copy-paste-ready fetch (CNContactFetchRequest with key descriptors) and create (CNSaveRequest.add) examples, plus a need→API decision table and named APIs for predicate and identifier queries. Not 5 because the update/delete path — a common case — is described in prose ("fetching the required properties, creating mutableCopy()...") without a code example, and snippets assume an existing store. | 4 / 5 |
Workflow Clarity | The mutation workflow is explicitly sequenced (fetch → mutableCopy → fresh CNSaveRequest → execute) with a defined success boundary ("store.execute(request) returning without throwing is the success boundary"), a failure-recovery feedback loop ("preserve the user's intent, surface the error, correct known... causes, refetch stale contacts... construct a new request"), and a per-authorization-state behavior table plus a review checklist. Validation for the destructive save path is explicit, so the destructive-operation cap does not apply. | 5 / 5 |
Progressive Disclosure | SKILL.md is a concise overview that clearly signals its single one-level-deep reference twice — "Read [Contacts extended patterns](references/contacts-patterns.md) for a complete observable manager, SwiftUI lists, single/multi-select picker wrappers..." — with an enumerated scope that matches the actual file contents (verified), plus a curated external-docs list. Not 4 because there are no organization gaps: the split is appropriate and navigation is easy. | 5 / 5 |
Total | 18 / 20 Passed |