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

> Source: <https://dev.to/skillgild/agent-skills-sdk-run-claude-skills-and-ai-agent-skills-from-code-k88>
> Published: 2026-10-06 22:02:38+00:00

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](https://skillgild.dev/learn/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](https://skillgild.dev/skills), 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](https://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](https://skillgild.dev/docs/api); the [developer quickstart](https://skillgild.dev/docs/quickstart-developers) gets you from an API key to a first run. All three cover the same operations:

| Area | What you can do | Needs an API key | 
|---|---|---|
| Catalog | List and search skills, read a skill's input schema, tools, media and page copy, browse categories, tags, collections and featured skills | No | 
| Hosted runs | Run a `prompt_pipeline` skill in one call, with an idempotency key for safe retries | Yes | 
| Hybrid sessions | Start or resume a session, call the skill's server tools, end the session | Yes | 
| Account | Read the key's account, revoke the current key, sign in a device | Yes, except device sign-in | 

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.

```
# 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](https://www.npmjs.com/package/@skillgild/sdk), [PyPI](https://pypi.org/project/skillgild/) and [pkg.go.dev](https://pkg.go.dev/github.com/skillgild/sdks/go/skillgild).

Create an API key under **Settings → API keys** in your [account](https://skillgild.dev/account?section=settings) 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.

``` js
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:

``` js
// 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](https://skillgild.dev/docs/api#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:

``` python
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](https://skillgild.dev/docs/api#idempotency) for the exact rules.

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

|  | SkillGild SDKs | Claude Agent SDK | Claude API skills | Community registries | 
|---|---|---|---|---|
| Where skills live | Hosted on SkillGild | `SKILL.md` folders on disk | Uploaded to your Anthropic account | Any source you configure | 
| Languages | TypeScript, Python, Go | TypeScript, Python | Any HTTP client | Varies (for example Python) | 
| Model | Your choice; hybrid skills run in your agent | Claude | Claude | Your choice | 
| You maintain the skill files | No | Yes | Yes | Yes | 
| Server-side tools and access control | Yes | No | Code execution in Anthropic's container | No | 

`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](https://skillgild.dev/learn/install-claude-code-skills), [Codex](https://skillgild.dev/learn/install-codex-skills) or [Cursor](https://skillgild.dev/learn/cursor-mcp-setup) over MCP instead. [Agent skills vs MCP](https://skillgild.dev/learn/agent-skills-vs-mcp) explains the difference.

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

Browse by job: [Design](https://skillgild.dev/categories/design), [Video & Media](https://skillgild.dev/categories/video-media), [Research](https://skillgild.dev/categories/research), [Development](https://skillgild.dev/categories/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](https://skillgild.dev/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](https://skillgild.dev/docs/api) directly.

*Originally published at [skillgild.dev](https://skillgild.dev/learn/agent-skills-sdk).*