Skip to content
Shepherd Developers

A Shepherd skill for your AI coding agent

← Back to blog

·Shepherd Engineering ·4 min read

  • announcement
  • api
  • ai

Over the last month or so we’ve heard from a lot of you who are excited to build on top of the Shepherd API. More and more of that building is being done with AI coding assistants, and one question keeps coming up: how can I help my agent develop against Shepherd?

Today we have an answer: the Shepherd OpenAPI skill.

Why a skill

AI coding assistants are great at writing API clients quickly. What they don’t have is the detail about how the Shepherd API actually works, so they fill the gaps with confident guesses: a host that doesn’t serve the API, the clinic id in the request body instead of a header, a list request with no date window, a retry loop around a request that timed out, or an update that sends one field and clears the rest of the record.

Every one of those costs you time. Some of them cost your clinics data, and some slow the API down for everyone else. We built the skill so your agent starts with the right information instead of guessing: you get working code sooner, fewer errors make it out into the world, and the development is done safely.

What your agent gets

Install the skill and your agent knows what’s in this portal’s API reference, plus:

  • Every public endpoint and schema, bundled with the skill, so the agent looks things up instead of inventing them.
  • The rules the schema can’t tell you: which lists need a date window, page-size and embed limits, how rate limits are counted, which failures to retry and which never to retry, and exactly which fields each update keeps or clears.
  • A request linter that checks every request against those rules before your code sends it.
  • A development runner for trying calls against the sandbox, one at a time, under a local rate budget.
  • Starter clients and test suites in Python, TypeScript, C#, and PHP that already handle timeouts, rate limits, paging, error bodies, and safe updates.

It’s free, MIT licensed, and follows the open Agent Skills format, so it’s plain text and one Python script you can read before you install it.

Get started

  1. Download the skill from the skill page.
  2. Install it. In Claude Code, unzip it into ~/.claude/skills/ (or .claude/skills/ in your repository, so your whole team gets it). The skill page has steps for the Claude apps, the Claude API, and other agents.
  3. Put your sandbox keys in environment variables, never in a prompt.
  4. Ask your agent for real work:
    • “Write a job that syncs appointments changed since the last run into our database.”
    • “Add a function that updates a patient’s alerts.”
    • “Add tests for our Shepherd client that cover rate limits and timeouts.”

Use it to get a new integration off the ground, or point it at the integration you already have and ask it to review your Shepherd client. It’s especially good at catching the updates that quietly clear fields and the retries that shouldn’t be there.

We tightened the docs, too

Writing the skill meant checking every rule it teaches against the running API, and that turned up places where this portal was wrong or incomplete. We’ve corrected them:

  • Only the clinic lookup (open-api-clinics) works without the X-Clinic-Id header; the group lookup needs it too.
  • Rate limits are counted in fixed UTC minutes and hours, rejected requests count against them, and there’s no Retry-After header: after a 429, wait for the next UTC minute.
  • Errors come in four body shapes, not two, and the page now says which failures to retry and which never to.
  • The one-month date window and the 10,000-record paging ceiling are enforced only on patient notes, though we still recommend both everywhere. See Conventions.
  • The update pages now spell out which fields are kept and which are cleared for clients, patients, appointments, and tasks.

If you copied update code from our clients, patients, or tasks pages before today, please compare it with the new read, merge, write examples. The older samples didn’t carry every field through, and on these endpoints a missing field is a cleared field.

Tell us how it goes

We’re really excited to see what you build with this. As you use the skill, let us know what works, what doesn’t, and what you wish it knew. Include the skill version and the endpoint you were working with, and we’ll keep making it better.

Thanks for building with us!