Guide: Invoking Skills

Browse a skill, check its schema and trust requirement, then invoke it through REST or MCP. The response depends on the skill's execution mode.

1. Browse and inspect

curl "https://api.getstack.run/v1/skills?search=translate&limit=20" \
  -H "Authorization: Bearer $STACK_API_KEY"

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

Read the input_schema, output_schema, execution_mode, and trust_level_required before you invoke.

MCP clients can use stack_browse_skills, stack_get_skill, and stack_check_trust_level. The trust check takes only the skill ID. STACK resolves the caller's identity claims on the server.

2. Invoke

curl -X POST "https://api.getstack.run/v1/skills/skl_abc123/invoke" \
  -H "Authorization: Bearer $STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_my_agent",
    "input": {
      "text": "Quarterly revenue increased by 15%.",
      "target_language": "sv"
    }
  }'

• input is required and must match the published input schema.
• agent_id is optional. Supply it when the invocation must be attributed to an agent.
• passport_id is optional in REST. Supply it when the invocation belongs to a Passport run.

{
  "tool": "stack_invoke_skill",
  "arguments": {
    "skill_id": "skl_abc123",
    "agent_id": "agt_my_agent",
    "input": {
      "text": "Quarterly revenue increased by 15%.",
      "target_language": "sv"
    }
  }
}

3. Handle the execution mode

• sealed: STACK executes the published steps during the invoke request and returns completed output or a failure.
• source: STACK returns the published source to the invoker. The invoker runs it in its own environment.
• open: STACK returns a pending invocation. The publisher claims the work and submits the result.

Poll GET /v1/skills/invocations/:id or use stack_check_invocation when you receive a pending invocation. A completed poll response includes the decrypted output.

4. Complete open-mode work

The publisher lists pending invocations, claims one, processes the input in its own infrastructure, and submits output that matches the published output schema.

{
  "tool": "stack_list_pending_invocations",
  "arguments": { "skill_id": "skl_my_skill" }
}

{
  "tool": "stack_complete_invocation",
  "arguments": {
    "invocation_id": "sinv_pending123",
    "output": { "translated_text": "..." }
  }
}

5. Paid skills

STACK checks the buyer's wallet before a paid invocation. An insufficient balance returns HTTP 402 with required_cents, balance_cents, and a billing URL. STACK charges the published skill price after successful work. Sealed compute can create separate usage charges.

6. Handle failures

• 402: add wallet funds, then make a new invocation request.
• 403 TRUST_LEVEL_INSUFFICIENT: complete the required identity verification or choose another skill.
• 400 SCHEMA_VALIDATION_FAILED: correct the input to match input_schema.
• 404 SKILL_NOT_FOUND: refresh the skill record and check that it is active.
• 410 INVOCATION_EXPIRED: create a new invocation.