Feedback on your automating-contacts skill

[RichardHightower]

I took a look at your automating-contacts skill and wanted to share some thoughts.

Links:

• GitHub
• Your agentic skill in the SkillzWave marketplace

The TL;DR

You're at 99/100, which puts you in solid A territory. This is based on Anthropic's skill best practices rubric. Your strongest area is Spec Compliance (14/15) - the YAML is clean, naming conventions are correct, and your trigger phrases are solid. The weakest spot is Utility (18/20), mainly because your recipe examples could use better validation outputs to show what success looks like.

What's Working Well

• Progressive Disclosure Architecture is chef's kiss. Your SKILL.md clocks in at 95 lines with zero fluff, and you've properly isolated the massive PyXA API reference (880+ lines) into a separate file. The "What to load" section makes navigation crystal clear.

• Your trigger phrases are doing the heavy lifting. Six specific triggers like "JXA contacts", "macOS address book", and "AppleScript contacts automation" make this discoverable. That's the kind of specificity that actually helps people find your skill.

• The workflow is actionable. Eight numbered steps with a validation checklist at the end means someone can actually follow this and know when they're done. That's real utility.

The Big One

Your recipe examples show code patterns but don't show expected outputs. This matters because someone using your skill needs to know what success looks like. Right now you've got patterns like:

const matches = Contacts.people.whose({firstName: 'Ada'})();

But no comment showing what matches actually contains. Add inline comments with sample outputs:

const matches = Contacts.people.whose({firstName: 'Ada'})();
// Returns: [{firstName: 'Ada', lastName: 'Lovelace', email: 'ada@example.com'}, ...]

This is probably worth +1 point and makes the recipes genuinely useful instead of just illustrative. Do this in contacts-recipes.md for your core CRUD examples.

Other Things Worth Fixing

1. Tighten the "Relationship to Other Skills" section. It's taking up 4 bullets explaining when to use this vs. other skills. Compress it to one line: "Standalone skill. Load automating-mac-apps for TCC setup, ObjC bridges, or UI scripting fallbacks." You'd gain back some token budget here.

2. Add a table of contents to contacts-pyxa-api-reference.md. At 880+ lines, people need navigation. A simple TOC at the top pointing to sections would help.

3. Your multi-value field examples could show common gotchas. The basics are there, but adding a "Common Mistakes" subsection would bump up utility when someone hits the edge cases you've already thought through.

Quick Wins

• Add sample output comments to recipe code examples (+1 point)
• Condense relationship section to one line (cleaner, same info)
• Add TOC to the big API reference for navigation
• Call out common edge cases in multi-value field docs

---

Checkout your skill here: [SkillzWave.ai](https://skillzwave.ai) | [SpillWave](https://spillwave.com) We have an agentic skill installer that install skills in 14+ coding agent platforms. Check out this guide on how to improve your agentic skills.