Index

Building Agent Skills for iMessage

At Photon, we build infrastructure for AI agents on iMessage. Our SDKs let developers send and receive iMessages programmatically, manage group chats, schedule messages, build real-time conversational AI — all through TypeScript.

But building SDKs is only half the problem. The other half is making sure AI agents actually know how to use them.

I spent the last couple weeks building, publishing, and iterating on agent skills for our iMessage SDKs. What started as a straightforward documentation exercise turned into a crash course in how the AI agent ecosystem actually works — discoverability, security audits, prompt injection surfaces, and the surprisingly important difference between writing docs for humans and writing instructions for agents.

The Problem

Here's the situation in early 2026: AI coding agents — Cursor, Claude Code, Copilot, OpenCode, Gemini CLI — are becoming the primary interface for developers. People don't read documentation pages anymore. They ask their agent to build something, and the agent figures out how.

This works great for popular libraries. React, Next.js, Express — agents have seen enough training data to know these APIs cold. But for newer, specialized SDKs like ours? The agent has no idea.

I watched developers try to use our iMessage SDKs through Cursor. The agent would hallucinate method names, invent parameters that didn't exist, mix up our two different SDKs. It knew about iMessage in some abstract sense, but it couldn't write working code against our specific API.

The traditional fix is better documentation. But agents don't browse docs sites. They need instructions delivered in a format they can consume at the point of use — inside the IDE, at the moment the developer asks for help.

That's what agent skills solve.

What Agent Skills Are

Agent skills are markdown files that follow the Agent Skills specification. They get installed into your project and are automatically loaded by compatible AI agents when relevant tasks come up.

Think of them as package.json for agent knowledge. Instead of shipping code, you ship instructions — complete API references, usage patterns, error handling guides, best practices. The agent references these while writing code for you.

The format is simple: a SKILL.md file with YAML frontmatter and markdown content. The skills.sh registry handles discovery and distribution.

npx skills add photon-hq/skills --skill imessage

One command, and your agent knows how to build iMessage applications.

What I Shipped

Two skills:

imessage — the comprehensive reference for both our Self-Hosted Kit (@photon-ai/imessage-kit) and our Advanced Kit (@photon-ai/advanced-imessage-kit). The Self-Hosted Kit runs on your Mac and reads the iMessage database directly — full control, your infrastructure. The Advanced Kit is managed production infrastructure through Photon — no macOS servers to babysit. Different tools for different situations. 1,600+ lines of structured API reference covering every method, type, event, and pattern across both.

chat-adapter-imessage — the reference for our Vercel AI SDK adapter, which connects AI chatbots built with the Vercel AI SDK directly to iMessage.

Both are live on skills.sh/photon-hq/skills.

Everything That Went Wrong

The framing problem

My first version framed the two SDKs as "Free Tier" and "Production Tier." Bad idea. Agents (and developers reading the generated code) perceived the Self-Hosted Kit as some kind of limited starter version you'd graduate from. That's not what it is at all — both kits are fully capable, they just make different tradeoffs around hosting and control. I rewrote the kit selection guide to make that clear, and agents immediately started presenting the options better instead of defaulting to whatever sounded most "pro."

The security audit wake-up call

Within days of publishing, the skill got flagged by two independent security auditors on skills.sh — Gen Agent Trust Hub and Snyk. Both identified the same issue: indirect prompt injection risk.

Legitimate finding. My code examples showed an echo-bot pattern:

await sdk.messages.sendMessage({ chatGuid, message: `You said: ${text}` });

This is exactly how prompt injection works. A malicious sender crafts an iMessage containing instructions that manipulate the agent's behavior — because message.text is untrusted input and the code was echoing it raw.

I took this seriously. Added a dedicated Security section covering structured LLM role separation, input validation with allowlisted commands, no-echo patterns, safe logging. Updated every code example that touched message content. Added explicit warnings in the Common Mistakes table.

The W011 warning will probably persist on re-scan because the skill inherently ingests third-party content — that's what an iMessage AI agent does. You can't build a messaging agent that doesn't read messages. But you can teach developers to handle them safely.

If you're building skills that involve processing external input, assume the security auditors will flag it. Get ahead of it.

The discoverability problem

Publishing a skill doesn't mean anyone can find it. The npx skills find [query] command matches against the skill's name and description fields in the YAML frontmatter. There's no separate tags or keywords field.

My original description was something like "Build iMessage bots with @photon-ai/imessage-kit." Someone searching for "messaging," "text message," "chatbot," or "apple messages" would never see it.

I restructured the description to front-load the highest-signal phrase and appended a keywords tail — imessage, apple messages, sms, text message, send message, messaging, chat, chatbot, conversational ai, macos, webhooks, mcp. There's a 1,024 character limit. Treat it like SEO because it is.

The second skill that didn't exist

I had two skills in the repo from day one. But skills.sh only showed one. The chat-adapter-imessage skill just wasn't indexed.

Turns out skills.sh indexes skills when they're first installed, not when they're pushed to a repo. My imessage skill had been installed by early users. chat-adapter-imessage hadn't been installed by anyone.

Fix was one command:

npx skills add photon-hq/skills --skill chat-adapter-imessage

Install your own skills after publishing. Don't wait for organic discovery to trigger indexing.

One file, one source of truth

I started with the API reference in SKILL.md and a separate best-practices.md. This split meant agents would sometimes find one file but not the other, leading to incomplete guidance. Merged everything into a single SKILL.md within a week. Agents work best with a single, comprehensive reference. Splitting knowledge across files creates gaps.

What Actually Changed After Shipping

The difference was immediate. Before the skills, agents would guess at our API — wrong method names, invented parameters, confused SDK variants. After, they just got it right. The code they generated compiled and ran on the first try. That's not a small thing when the whole point of an AI coding agent is to move fast.

We also documented the full Photon ecosystem within the skill — the Webhook Bridge with HMAC-SHA256 verification examples in TypeScript, Python, Go, and Rust, and the MCP server with 67 tools at mcp.photon.codes. So when a developer asks their agent "set up a webhook for iMessage events" or "give my Claude agent iMessage access via MCP," the agent has complete instructions.

What I'd Do Differently

If I was starting over:

  1. Write the security section first. The audit findings were legitimate and the fix was straightforward, but it would have been cleaner to ship with security guidance from day one.

  2. Install your own skills immediately. Don't wait for organic installs to trigger indexing.

  3. One file per skill, always. I split things within the first week and merged them back within the second. Wasn't worth the detour.

  4. Treat the description like ad copy. Front-load the highest-signal phrase. Add a keywords tail. That description field is your entire discoverability surface.

  5. Include the ecosystem, not just the SDK. Webhook bridges, MCP servers, deployment guides — if it's part of building with your platform, it belongs in the skill.

Why This Matters

Agent skills feel like a new primitive that's still early but clearly important. The specification is evolving, the discoverability layer is nascent, the security tooling is just starting to catch up. But the trajectory is obvious: AI agents are becoming the primary developer interface, and the SDKs that make themselves agent-accessible will win over the ones that don't.

I keep thinking about this: the bottleneck in modern development isn't typing speed or even thinking speed — it's how quickly the agent can translate intent into working code. If your SDK has a great API but the agent can't use it, developers will choose a worse API that the agent knows. Skills close that gap.

npx skills add photon-hq/skills --skill imessage

Photon builds infrastructure for AI agents on iMessage. Learn more at photon.codes.