Hey everyone — Ata here, PM on the Sinch developer platform team. I want to share something we've been working on that I think will meaningfully change how you build with Sinch APIs when using AI coding tools.
We shipped Sinch Skills today. Here's the honest story of why we built them.
The thing that kept coming up
Over the past year, we've watched more and more developers use AI coding agents — Claude Code, Cursor, Gemini CLI, Codex — to successfully build Sinch integrations. On occasion we saw some similar patterns: the agent would generate code that looked right, but had subtle problems that only showed up when you actually ran the code:
Wrong auth methods
Missing regional endpoints
No state verification before a billable retry
Webhook setup that worked in a test environment but broke in production.
None of these are obscure gotchas. They're things any experienced developer knows. But agents don't have that experience — they have training data, which isn't the same thing.
We kept patching this with better docs, better SDK examples. But the real fix was giving agents the knowledge directly, in a format they can actually use.
What we built
Sinch Skills are structured knowledge files — one per API — that your AI coding agent reads as context. Each skill is a SKILL.md file containing auth setup, getting started code, key concepts, the patterns that actually work in production, and the gotchas we've learned the hard way.
We built on the Agent Skills open standard, which means skills work across Claude Code, Gemini CLI, Cursor, Codex, GitHub Copilot, Windsurf, and any other tool that supports SKILL.md files.
You can install the full library with one command:
npx skills add sinch/skills
We're launching with a set of skills covering the full Sinch portfolio — Conversation API (one API for omnichannel messaging), Voice, Verification, Mailgun, Numbers, 10DLC, SIP Trunking, In-App Calling, Fax, and more.
How Skills Prevent Common API Errors
Using Sinch Skills provides a clear advantage by ensuring your code works correctly on the first try. Without them, it's easy to make critical mistakes.
Here’s a simple comparison:
With Skills (Correct)
Without Skills (Incorrect)
Authentication
Uses the correct OAuth2 token.
Invents a non-existent HMAC signing method.
Recipient
Uses the documented channel_identities format.
Guesses the wrong field ( to: ).
Channel
Specifies the required channel, like "SMS" .
Forgets to specify a channel.
Outcome
Success! The API call works.
Failure. The API call would be rejected.
Code Examples
With Skills
// Step 1: Exchange credentials for an OAuth2 token.
const tokenResponse = await axios.post(
'https://us.api.sinch.com/oauth2/token',
'grant_type=client_credentials',
{
auth: {
username: 'YOUR_KEY_ID',
password: 'YOUR_KEY_SECRET',
},
},
);
const { access_token } = tokenResponse.data;
// Step 2: Use the token to send a message.
const messageResponse = await axios.post(
'https://us.api.sinch.com/v1/projects/YOUR_PROJECT_ID/messages:send',
{
recipient: {
identified_by: {
channel_identities: [{ channel: 'SMS', identity: '15551234567' }],
},
},
message: {
text_message: { text: 'Hello from Sinch!' },
},
},
{
headers: {
Authorization: `Bearer ${access_token}`,
},
},
);
Without Skills
// Step 1: Create a signature for the request.
const signature = crypto
.createHmac("sha256", 'YOUR_KEY_SECRET')
.update(new Date().toISOString())
.digest("base64");
// Step 2: Send a message using the signature.
const messageResponse = await axios.post(
'https://us.api.sinch.com/v1/projects/YOUR_PROJECT_ID/messages:send',
{
recipient: {
to: ['15551234567']
},
message: {
text_message: { text: 'Hello from Sinch!' }
},
},
{
headers: {
Authorization: `Signature keyId="YOUR_KEY_ID", signature="${signature}"`,
},
},
);
Why is the Authentication difference so important?
The section on "Authentication: OAuth2 vs. Invented HMAC Signing" is highlighted because it’s the most critical first step. It's like having the right key to unlock a door.
The Problem: AI models sometimes guess the wrong security method (like HMAC signing) because they've seen it used for other, unrelated APIs.
The Consequence: If you use the wrong "key," the server immediately rejects your request with an error. Your API call fails before it's even processed.
The sinch-authentication skill prevents this by providing the correct key (OAuth2), ensuring your request is accepted.
More about Sinch Skills and what they cover
Here's what the skills actually contain that agents would otherwise struggle with:
Conversation API offers one single API endpoint for sending and receiving messages globally using SMS, RCS, WhatsApp, Viber Business, Facebook messenger and other popular channels. The corresponding Conversation API skill covers regional endpoint rules, processing modes, webhook setup, and the WhatsApp template constraint outside the 24-hour window.
The 10DLC skill covers the full six-step registration workflow, including why TCR rejects vague campaign descriptions and why FULL registration type is the right choice for production.
The Voice skill covers that cli is required for TTS callouts to connect, that SVAML instruction order matters, and that ACE callbacks aren't sent for in-app destinations.
The Verification skill leads with the auth pattern that breaks most often in agent-generated code: Application Key and Secret is required — not project OAuth2.
We built the skills from the many lessons we learnt from building and supporting the Sinch APIs. We packaged it for your agent so you don't have to prompt-engineer your way to correct output.
It's open source
The repository is Apache-2.0. If you find something missing, wrong, or outdated — open an issue or submit a PR. We're treating this as a living set of documents, not a one-time release.
→ github.com/sinch/skills → github.com/sinch/sinch-plugins (for automatic updates via plugin and plugin setup)
I'd love to hear from you
If you try out Sinch Skills, I genuinely want to know what happened. Did they help? Did the agent still get something wrong? Is there a skill we're missing that you need?
Drop a comment below or open an issue in the repo. Your feedback will directly shape what we build next.
If you find this useful, please give us a ⭐️ on GitHub to help us grow the community.
— Ata
... View more
