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.

Try it on a real task: Academic Plotting is free for 25 runs a month.

#What the SkillGild agent skills SDKs do

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.

#Install

# TypeScript / JavaScript (Node 20+, Bun, Deno, browsers)
npm install @skillgild/sdk

# Python 3.9+
pip install skillgild

# Go 1.22+
go get github.com/skillgild/sdks/go

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

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

#A real run against the live API

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.

#How a hybrid skill session works

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);

# Python
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.

#Hosted skills and safe retries

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.

#SkillGild SDK vs other ways to use Claude skills and agent skills from code

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

• The Claude Agent SDK discovers skills as filesystem artifacts in user and project folders, the same format Claude Code uses.
• The Claude API lets you upload skills and reference them by ID, running in Anthropic's code-execution environment.
• Open-source registries such as agentskills-sdk load 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.

#Agent skills to try first

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

• Logo Design: brand marks from a brief, with an SVG validation tool.
• Academic Plotting: publication-ready research figures.
• Taste Skill: front-end design direction for landing pages and apps.
• HyperFrames: programmatic video from code.
• OpenSpec Propose: a spec before the code, for spec-driven development.

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

#Frequently asked questions

#Is there an SDK for agent skills?

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.

#Can I use Claude skills through an API?

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.

#Are the SkillGild SDKs free?

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.

#Do I need an API key?

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

#Which languages are supported?

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.