Black FridayBlack Friday starts early: 60% off SkillGild Pro

Code BFCM60Claim 60%

Black FridayBlack Friday starts early: 60% off SkillGild Pro

Claim 60%
SkillGild

Run your first AI agent skill with curl or an SDK

Create an API key, find a skill, read its input schema and run it from curl or an SDK in five minutes.

4 min readQuickstart

Use your first skill from code in five minutes: create a key, find a skill, start a session, call its tools, and end the session.

This quickstart uses a hosted hybrid skill. Your code or agent does the reasoning with its own model, and calls SkillGild server tools for the steps that stay private. Starting a session uses one run from your allowance; the tool calls inside it are capped per session, not billed one by one.

#1. Create an API key

Sign in, open Account → Agent connections → API keys, and create a key. Copy the secret immediately; it is shown only once.

sh
export SKILLGILD_API_KEY="sg_live_…"

Keys start with sg_live_ and can run skills. They expire after 90 days by default, and each account can have five active keys.

#2. Find a skill

The catalog is public, so this call needs no key:

sh
curl "https://api.skillgild.dev/v1/skills?q=plot&limit=5"

Each item includes its slug, access_tier, distribution_mode, free_runs_per_month and runtime_type. Use a hosted hybrid_tools skill for this session walkthrough. Community listings (distribution_mode: open_source) install and run locally; they do not support session or run endpoints. A community listing's runtime_type is not a hosted execution promise.

#3. Start a session

sh
curl -X POST "https://api.skillgild.dev/v1/skills/academic-plotting/sessions" \
  -H "Authorization: Bearer $SKILLGILD_API_KEY"
json
{
  "data": {
    "session_id": "251d3a9e-fe09-4a8a-afb9-7e5158103f58",
    "skill_slug": "academic-plotting",
    "version": "1.1.0",
    "expires_at": "2026-11-04T19:54:45Z",
    "max_tool_calls": 100,
    "tool_calls_used": 0,
    "resumed": false,
    "tools": [
      {
        "name": "validate_palette",
        "title": "Validate palette and contrast",
        "input_schema": { "type": "object", "required": ["colors", "pairs"], "…": "…" }
      }
    ],
    "guide": "# Academic Plotting …",
    "usage": { "used": 1, "limit": 25, "reset_at": "2026-11-01T00:00:00Z", "access_tier": "free" }
  }
}
  • guide is the skill's instructions. Give it to the model that does the work.
  • tools lists the server tools this session may call, each with its JSON Schema.
  • usage shows this month's allowance. Starting the same skill again while a session is open returns that session ("resumed": true) at no cost.

#4. Call a tool

sh
curl -X POST "https://api.skillgild.dev/v1/skill-sessions/$SESSION_ID/tools/validate_palette" \
  -H "Authorization: Bearer $SKILLGILD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"colors":{"ink":"#000000","paper":"#FFFFFF"},"pairs":[{"foreground":"ink","background":"paper","minimum_ratio":4.5}]}}'
json
{
  "data": {
    "session_id": "251d3a9e-fe09-4a8a-afb9-7e5158103f58",
    "tool": "validate_palette",
    "result": {
      "ok": true,
      "errors": [],
      "warnings": [],
      "pairs": [{ "foreground": "ink", "background": "paper", "minimum_ratio": 4.5, "passes": true, "ratio": 21 }]
    },
    "tool_calls_used": 1,
    "tool_calls_remaining": 99
  }
}

Wrap the tool's input in {"input": …} and match the tool's input_schema. Every call counts against the session's cap, including one with invalid input.

#5. End the session

sh
curl -X DELETE "https://api.skillgild.dev/v1/skill-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $SKILLGILD_API_KEY"

A 204 means the session is closed and its remaining tool calls can no longer be used.

#6. Handle the common errors

Every error has the shape { "error": { "code": "…", "message": "…" } }.

Status and code What to do
400 invalid_input Fix the tool input. The message names the field. The call still counted.
401 invalid_api_key The key is wrong, expired or revoked. Create a new one.
402 entitlement_required The skill is paid and you don't have access to it.
404 skill_not_found, tool_not_found Check the slug or tool name against the catalog and the session's tools.
410 session_ended, session_expired Start a new session.
429 quota_exceeded This month's allowance is used. error.reset_at says when it resets: 00:00 UTC on the 1st.
429 tool_call_limit This session's tool calls are used up. End it and start a new one.
429 rate_limited Slow down. Wait a minute before retrying.
503 runtime_paused, free_tier_paused SkillGild has paused runs. Try again later.

See Session errors for the full list.

#7. Use an SDK

Install with npm install @skillgild/sdk, pip install skillgild or go get github.com/skillgild/sdks/go. The source is at github.com/SkillGild/sdks, and the agent skills SDK guide walks through a real run.

ts
import { SkillGildClient } from "@skillgild/sdk";

const client = new SkillGildClient({ apiKey: process.env.SKILLGILD_API_KEY });
const session = await client.startSession("academic-plotting");
try {
  const check = await client.callTool(session.session_id, "validate_palette", {
    colors: { ink: "#000000", paper: "#FFFFFF" },
    pairs: [{ foreground: "ink", background: "paper", minimum_ratio: 4.5 }],
  });
  console.log(check.result);
} finally {
  await client.endSession(session.session_id);
}

Python (start_session, call_tool, end_session) and Go (StartSession, CallTool, EndSession) clients work the same way. See the SDK reference.

#Next

#Continue your workflow

For a concrete first example, explore Academic Plotting and the research plotting guide. Compare a different output workflow with Excalidraw Diagram. If you are building agent capabilities yourself, continue with MCP Builder or Skill Creator.