Skills

Esta página aún no está disponible en tu idioma.

Skills are reusable LLM or API building blocks. Workflows compose skills into multi-step runs. Two kinds:

type=llm — prompt template + model. Input schema fields appear as {{variable}} placeholders in the prompt.
type=api — HTTP request wrapper. Same {{variable}} placeholders in URL / headers / body template; response mapping projects the response into an output object.

30-second start

List available LLM models (free, no creds beyond your key):

curl 'https://be.graph8.com/api/v1/skills/models' \
  -H "Authorization: Bearer $G8_API_KEY"

import { g8 } from '@graph8/sdk';
g8.init({ apiKey: process.env.G8_API_KEY! });

const { data: models } = await g8.skills.listModels();
console.log(models); // → [{ id: 'claude-sonnet-4-6', label, provider }, ...]

g8 skill-list-models

Ask your agent: “What models can I use for skills?” → tool: g8_skill_list_models.

Quick reference

Endpoint	Method	Purpose
`/skills`	GET	List skills (paginated, filterable by `type`)
`/skills`	POST	Create — both LLM and API types via `type` field
`/skills/{id}`	GET / PUT / DELETE	Read / update / delete
`/skills/{id}/variables`	GET	Input variables extracted from prompt / template
`/skills/{id}/execute`	POST	Run with an input payload (test / preview)
`/skills/from-template`	POST	Create from a built-in template
`/skills/from-node`	POST	Lift a workflow node into a reusable skill
`/skills/validate`	POST	Validate a definition without saving
`/skills/templates`	GET	List built-in templates
`/skills/models`	GET	List available LLM models

LLM skill shape

{
  type: "llm",
  title: "Qualify inbound lead",
  description: "Score and tag inbound leads",
  prompt: "You are an SDR. Contact: {{contact}}. Company: {{company}}. Return JSON {tier:A|B|C, reason}.",
  model: "claude-sonnet-4-6",
  input_schema: {
    fields: [
      { name: "contact", type: "object", required: true },
      { name: "company", type: "object", required: true }
    ]
  },
  output_schema: { tier: "string", reason: "string" }   // optional
}

API skill shape

{
  type: "api",
  title: "Enrich domain via Clearbit",
  method: "GET",
  url: "https://company.clearbit.com/v2/companies/find?domain={{domain}}",
  headers: { "Authorization": "Bearer sk_xxx" },
  body_template: null,
  response_mapping: { name: "$.name", industry: "$.category.industry" },
  input_schema: { fields: [{ name: "domain", type: "string", required: true }] }
}

Create

POST /api/v1/skills
Content-Type: application/json

{ ...skill body... }

The shape is determined by type. Use the LLM or API shape from above.

From a template

POST /api/v1/skills/from-template
{ "title": "Reply summarizer", "template_id": "summarize_reply", "overrides": { "model": "claude-opus-4-7" } }

Templates are pre-built skill definitions for common use cases (summarize, extract emails, draft email, classify intent, etc.).

Lift from a workflow node

POST /api/v1/skills/from-node
{ "title": "Lifted draft node", "node_id": "n_draft_reply_456" }

Produces a byte-identical skill from a node already configured inside a workflow — useful for promoting one-off node configs into reusable skills.

Update / delete

PUT /api/v1/skills/{id}
{ "type": "llm", "title": "Renamed", "model": "claude-opus-4-7" }

DELETE /api/v1/skills/{id}

Pass the type on update so the server knows which schema applies. Delete fails if in-use workflows reference the skill.

Validate

POST /api/v1/skills/validate
{ ...full skill body... }

Returns { valid: bool, errors: [...] }. Use before save to fail fast on schema / template / model issues.

Execute (test / preview)

POST /api/v1/skills/{id}/execute
Content-Type: application/json

{ "contact": { "name": "Jane Smith" }, "company": { "domain": "acme.com" } }

Returns { data: { output, latency_ms, tokens?, error } }. Use for preview / testing inside the builder UI; production execution happens inside workflow runs.

Discovery

GET /api/v1/skills/models       # Available LLM models (claude-sonnet-4-6, claude-opus-4-7, gpt-4, etc.)
GET /api/v1/skills/templates    # Built-in skill templates
GET /api/v1/skills/{id}/variables   # Variables extracted from a skill's prompt / body_template

Credit costs

Operation	Credits
List / get / variables / models / templates	Free
Create / update / delete / validate	Free
LLM execute	1 per 1,000 tokens (input + output)
API execute	Free from graph8; third-party charges apply

Errors

Status	Cause	Fix
`401`	Missing or invalid `Authorization: Bearer` header	Get a key
`402`	Out of credits (waterfall enrichment, AI generation, voice minutes)	Top up in Settings → Billing, or switch to Platform
`404`	Resource ID doesn’t exist	List first to verify the ID
`422`	Validation error in request body	Inspect `error.message` + `error.field` in the response
`429`	Rate limit (5 rps per org)	Backoff per `Retry-After` header. See Rate Limits
`5xx`	graph8 error	Retry with exponential backoff (5s → 30s → 120s)

The full error envelope shape: { "error": { "code": "...", "message": "...", "field": "...", "request_id": "..." } }. Include the request_id in any support ticket. See Errors for the canonical reference.