S T A C K

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: Wallet Balance (Paid Skills)

Paid skills are billed against your STACK wallet in USD. Free skills (price_per_invocation = 0) skip this step entirely. Top up your wallet ahead of time; invocations are debited atomically and publishers are paid out via Stripe Connect.

Check Balance

bash
curl "https://api.getstack.run/v1/billing/balance" \
  -H "Authorization: Bearer sk_live_..."
json
{
  "balance_cents": 875,
  "balance_usd": "$8.75"
}

Top Up

Request a Paddle-hosted checkout URL for a top-up. Minimum $10.

bash
curl -X POST "https://api.getstack.run/v1/billing/topup" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 2500}'
json
{
  "checkout_url": "https://checkout.paddle.com/..."
}

STACK is the merchant of record. Buyers fund one USD wallet; publishers receive direct payouts via Stripe Connect, minus a tier-based commission. Unused balance is fully refundable within 30 days.

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_id": "ppt_abc123"
  }'

Invoke Body Fields

  • agent_id (string, optional) -- Your invoking agent ID.
  • input (object, required) -- Input data conforming to the skill's input_schema.
  • passport_id (string, optional) -- Passport ID for audit trail.

Trust claims are resolved server-side from your account\'s verified identity claims. You no longer pass them in the invoke body. Paid skills are billed from your STACK wallet balance automatically.

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. Ensure your wallet has enough balance to cover the skill's price_per_invocation (check with GET /v1/billing/balance).
  • 2. If not, top up with POST /v1/billing/topup -- returns a Paddle-hosted checkout URL.
  • 3. Invoke the skill. The wallet is debited atomically on success, and the publisher's earnings ledger is credited minus the tier commission.
  • 4. If the balance is insufficient, a 402 response is returned with a top_up_url and the required cents amount.
json
// 402 Payment Required response
{
  "error": "insufficient_balance",
  "required_cents": 10,
  "balance_cents": 3,
  "top_up_url": "https://checkout.paddle.com/..."
}

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": "insufficient_balance",
  "required_cents": 10,
  "balance_cents": 3,
  "top_up_url": "https://checkout.paddle.com/..."
}

Top up your wallet via the top_up_url and retry the invocation.

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.
STACK — Infrastructure for AI Agents