Agent skills SDK: run Claude skills and AI agent skills from code

Agent skills are packaged instructions and tools that teach an AI agent a specific job, like designing a logo or plotting research data. Claude skills are the best-known example. Usually you use skills inside a coding agent such as Claude Code. An agent skills SDK lets your own code use them too.

SkillGild now has open-source SDKs for TypeScript, Python and Go that search the skill catalog, run hosted skills and drive hybrid skill sessions from any app, script, backend or custom agent. The same skills keep working in Claude Code, Codex, Cursor and any MCP client.

The source is public at github.com/SkillGild/sdks under the MIT license. This guide shows how the SDKs work, what a real run looks like, and how they compare with the other ways to call agent skills from code.

Each SDK is a small, dependency-free client for the SkillGild REST API; the developer quickstart gets you from an API key to a first run. All three cover the same operations:

Errors come back as one typed error with the HTTP status, the API's error code and, for rate limits and quotas, the Retry-After delay. Access decisions stay on the server: the SDK never holds skill prompts, so a paid skill stays paid no matter which client calls it.

npm install @skillgild/sdk

pip install skillgild

go get github.com/skillgild/sdks/go

The packages are on npm, PyPI and pkg.go.dev.

Create an API key under Settings → API keys in your account and export it as SKILLGILD_API_KEY. Browsing the catalog needs no key.

We ran this script with the TypeScript SDK, built from the 0.1.0 source, against the production API on October 6, 2026. It searches the catalog, reads a skill's tools, then calls startSession with a deliberately invalid key to show the error you get back.

import { SkillGildClient, SkillGildError } from "@skillgild/sdk";

const client = new SkillGildClient(); // no key needed for the catalog

const { items } = await client.listSkills({ query: "design", limit: 5 });
for (const s of items) console.log(s.slug, s.access_tier, s.runtime_type);

const skill = await client.getSkill("logo-design");
for (const t of skill.tools ?? []) console.log("tool:", t.name);

try {
  await new SkillGildClient({ apiKey: "sg_invalid" }).startSession("logo-design");
} catch (e) {
  if (e instanceof SkillGildError) console.log(e.status, e.code);
}

Every skill in that result is a hybrid skill. That is typical of the current catalog, so most integrations use sessions rather than a single run call.

A hybrid skill splits the work. Your agent and your model do the creative part by following the skill's guide. SkillGild runs the parts that need its code, such as validating an SVG, through server tools.

The same flow in each language:

// TypeScript
const session = await client.startSession("logo-design");
// give session.guide and session.tools to your agent, then:
const check = await client.callTool(session.session_id, "validate_svg", { svg });
await client.endSession(session.session_id);
session = client.start_session("logo-design")
check = client.call_tool(session["session_id"], "validate_svg", {"svg": svg})
client.end_session(session["session_id"])
// Go
session, err := client.StartSession(ctx, "logo-design")
if err != nil { return err }
defer client.EndSession(ctx, session.SessionID)
check, err := client.CallTool(ctx, session.SessionID, "validate_svg", map[string]any{"svg": svg})

Starting a new session uses one run from your monthly allowance. Calling startSession again while a session for the same skill version is open returns that session at no extra cost. Tool input is processed by SkillGild code only; it is not sent to a model provider and not stored. The session limits list how many tool calls a session allows and when it expires.

A hosted (prompt_pipeline) skill runs entirely on SkillGild and returns its output in one call. Pass an idempotency key so a retry after a timeout cannot charge you twice:

import os, time, uuid
from skillgild import SkillGildClient, SkillGildError

client = SkillGildClient(api_key=os.environ["SKILLGILD_API_KEY"])
key = str(uuid.uuid4())
try:
    run = client.run_skill("your-skill", {"prompt": "..."}, idempotency_key=key)
except SkillGildError as error:
    if error.status == 429:
        time.sleep(error.retry_after or 2)  # then retry with the same key

The API stores a successful response for 24 hours and replays it for the same key. Reusing a key with a different request is rejected. See idempotency for the exact rules.

"Agent skills SDK" means different things depending on where the skill lives. Here is how the main options compare:

SKILL.md skills from any source and expose them to your own agent. These are not either-or. A common setup keeps your own skills as local files and calls hosted SkillGild skills, which bring server-side tools and stay up to date, through the SDK. If you only use skills inside a coding agent, you don't need an SDK at all: connect Claude Code, Codex or Cursor over MCP instead. Agent skills vs MCP explains the difference.

All of these are free and work through the SDK today:

Browse by job: Design, Video & Media, Research, Development.

Yes. SkillGild publishes open-source SDKs for TypeScript, Python and Go that search, run and orchestrate hosted agent skills over a REST API. Anthropic's Claude Agent SDK also loads skills, from SKILL.md folders on disk.

Yes, in two ways. Anthropic's Claude API accepts skills you upload to your account. SkillGild's API runs hosted skills, including ones made for Claude Code, from any language, and hybrid skills run with whichever model your agent uses.

The SDKs are free and MIT-licensed. Running skills uses your SkillGild allowance: free skills include monthly runs, and paid skills need a purchase or a Pro plan. See pricing.

Only to run skills, open sessions or read your account. Listing and searching the catalog works without a key.

TypeScript and JavaScript (Node 20+, Bun, Deno and browsers), Python 3.9+ and Go 1.22+. Any other language can call the REST API directly.

Originally published at skillgild.dev.