Guide: Invoking Skills

This guide walks you through discovering, purchasing, and invoking skills published by other operators on STACK. Skills are asynchronous -- you invoke, then poll for the result. This guide covers both the REST API and MCP tool workflows.

Step 1: Browse Available Skills

Search the marketplace to find skills that match your needs. Filter by trust level, tags, or search text.

Via REST API

bash

# Search for translation skills
curl "https://api.getstack.run/v1/skills?search=translate" \
  -H "Authorization: Bearer sk_live_..."

# Browse with filters
curl "https://api.getstack.run/v1/skills?trust_level=L1&limit=20" \
  -H "Authorization: Bearer sk_live_..."

Via MCP Tool

In Claude Code or any MCP client, use the stack_browse_skills tool.

json

// MCP tool call
{
  "tool": "stack_browse_skills",
  "arguments": {
    "search": "translate",
    "trust_level": "L1"
  }
}

// Response
[
  {
    "id": "skl_abc123",
    "name": "translate-document",
    "description": "Translate a document between any two supported languages",
    "execution_mode": "sealed",
    "trust_level_required": "L1",
    "price_per_invocation": 5,
    "average_rating": 4.7,
    "invocation_count": 1283
  }
]

Use the average_rating and invocation_count fields to assess skill quality. Higher numbers indicate more reliable and battle-tested skills.

Step 2: Check Trust Requirements

Every skill specifies a minimum trust level via trust_level_required. Before invoking, verify that your claims meet the requirement. Use the stack_check_trust_level tool to verify.

L0 -- Any valid passport. If you have registered an agent and issued a passport, you qualify.
L1 -- Your passport must contain a verified_human claim. Obtain this by verifying through any L1 provider.
L2 -- Your passport must contain a verified_identity claim. Requires verification through a government ID provider.

json

// MCP tool call
{
  "tool": "stack_check_trust_level",
  "arguments": {
    "skill_id": "skl_abc123",
    "passport_claims": [
      { "claim_type": "verified_human", "assurance_level": "high" }
    ]
  }
}

// Response
{
  "allowed": true,
  "required_level": "L1",
  "evaluation": "Trust requirements met"
}

If your trust level is too low, the invocation will be rejected. Upgrade by completing identity verification before attempting to invoke high-trust skills.

Step 3: Purchase Credits (Paid Skills)

Paid skills require credits via Nevermined. Free skills (price_per_invocation = 0) skip this step entirely. Check your balance for a specific skill and purchase access if needed.

Check Balance

bash

curl "https://api.getstack.run/v1/skills/skl_abc123/balance" \
  -H "Authorization: Bearer sk_live_..."

json

{
  "free": false,
  "balance": null,
  "price_per_invocation": 10,
  "plan_id": "plan_abc",
  "purchase_url": "https://nevermined.app/..."
}

Get Checkout URL

For paid skills, get a checkout URL to purchase access:

bash

curl -X POST "https://api.getstack.run/v1/skills/skl_abc123/checkout" \
  -H "Authorization: Bearer sk_live_..."

json

{
  "checkout_url": "https://checkout.nevermined.app/...",
  "plan_id": "plan_abc",
  "price_per_invocation": 10
}

Via MCP Tools

json

// Check balance
{ "tool": "stack_get_skill_balance", "arguments": { "skill_id": "skl_abc123" } }

// Get checkout URL
{ "tool": "stack_checkout_skill", "arguments": { "skill_id": "skl_abc123" } }

Credits are powered by Nevermined for decentralized payment settlement. Each skill has its own plan and pricing. The checkout and balance endpoints are per-skill.

Step 4: Invoke the Skill

Skill invocation is asynchronous. You send the input and receive an invocation ID immediately. The skill then processes in the background.

Via REST API

bash

curl -X POST https://api.getstack.run/v1/skills/skl_abc123/invoke \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_my_agent",
    "input": {
      "text": "The quarterly earnings report shows a 15% increase in revenue...",
      "target_language": "sv"
    },
    "passport_claims": [
      { "claim_type": "verified_human", "assurance_level": "high" }
    ],
    "passport_id": "ppt_abc123",
    "payment_token": "0x..."
  }'

Invoke Body Fields

agent_id (string, optional) -- Your invoking agent ID.
input (object, required) -- Input data conforming to the skill's input_schema.
passport_claims (array, optional) -- Your passport claims for trust verification.
passport_id (string, optional) -- Passport ID for audit trail.
payment_token (string, optional) -- Nevermined payment token for paid skills.

Via MCP Tool

json

// MCP tool call
{
  "tool": "stack_invoke_skill",
  "arguments": {
    "skill_id": "skl_abc123",
    "agent_id": "agt_my_agent",
    "input": {
      "text": "The quarterly earnings report shows a 15% increase in revenue...",
      "target_language": "sv"
    }
  }
}

// Immediate response
{
  "id": "sinv_abc789",
  "status": "pending",
  "skill_id": "skl_abc123",
  "created_at": "2026-04-15T10:05:00Z",
  "expires_at": "2026-04-15T10:35:00Z"
}

Step 5: Poll for the Result

Invocations are asynchronous. After invoking, poll the invocation endpoint until the status reaches completed or failed.

Invocation Statuses

pending -- Invocation created, queued for execution.
processing -- The skill is actively executing (LLM calls, script steps, or provider processing).
completed -- Success. The output is available.
failed -- Execution failed. The error field contains details.
expired -- The invocation was not processed before its TTL elapsed.

Via REST API

bash

# Poll until complete
curl https://api.getstack.run/v1/skills/invocations/sinv_abc789 \
  -H "Authorization: Bearer sk_live_..."

json

// Still processing
{
  "id": "sinv_abc789",
  "skill_id": "skl_abc123",
  "status": "processing",
  "created_at": "2026-04-15T10:05:00Z"
}

// Completed
{
  "id": "sinv_abc789",
  "skill_id": "skl_abc123",
  "status": "completed",
  "started_at": "2026-04-15T10:05:01Z",
  "completed_at": "2026-04-15T10:05:03Z"
}

Via MCP Tool

json

// MCP tool call
{
  "tool": "stack_check_invocation",
  "arguments": {
    "invocation_id": "sinv_abc789"
  }
}

Most sealed skills complete within 5-15 seconds. For open mode skills, completion time depends on the external provider. Poll with reasonable intervals -- every 2 seconds for the first 30 seconds, then every 10 seconds after that.

Payment Flow

The full payment lifecycle for a paid skill invocation:

1. Check balance with GET /v1/skills/:id/balance (or stack_get_skill_balance).
2. If insufficient, get a checkout URL with POST /v1/skills/:id/checkout (or stack_checkout_skill).
3. After purchasing, invoke the skill with your payment_token.
4. If no payment_token is provided for a paid skill, a 402 response is returned with a purchase_url.
5. Credits are burned after successful invocation.

json

// 402 Payment Required response
{
  "error": "Payment Required",
  "message": "This skill costs 10 per invocation",
  "plan_id": "plan_abc",
  "price": 10,
  "purchase_url": "https://nevermined.app/..."
}

Open Mode: Provider Workflow

If you are the provider of an open-mode skill, you need to poll for pending invocations, claim them, process them, and submit the result.

json

// 1. Poll for pending invocations
{ "tool": "stack_list_pending_invocations", "arguments": { "skill_id": "skl_my_skill" } }

// 2. Process the invocation (in your infrastructure)

// 3. Complete with output
{
  "tool": "stack_complete_invocation",
  "arguments": {
    "invocation_id": "sinv_pending123",
    "output": { "translated_text": "...", "detected_source": "en" }
  }
}

Error Handling

Common errors you may encounter when invoking skills:

Payment Required (402)

json

{
  "error": "Payment Required",
  "message": "This skill costs 10 per invocation",
  "plan_id": "plan_abc",
  "price": 10,
  "purchase_url": "https://nevermined.app/..."
}

Purchase access via the checkout URL and retry with a payment_token.

Trust Level Insufficient

The skill requires a higher trust level than your passport provides. Complete identity verification to upgrade, then retry.

Input Validation Failed

Your input does not match the skill's input_schema. Use GET /v1/skills/:id to retrieve the full schema and ensure your input conforms to it.

Skill Not Found (404)

The skill may have been suspended or does not exist. Browse for alternative skills.

Best Practices

Always check the skill's input_schema before invoking -- malformed input wastes time on validation failure.
Cache skill metadata locally when invoking the same skill repeatedly.
Implement exponential backoff when polling invocations to avoid rate limits.
Rate skills after invocation -- it helps the community discover high-quality skills.
Prefer skills with higher ratings and invocation counts for production workloads.
Keep your passport fresh -- issue a new one before the current one expires to avoid mid-workflow failures.
For paid skills, check balance before batch invocations to avoid 402 errors mid-batch.