Guide: Publishing a Skill

Publish a versioned skill with input and output schemas, a trust requirement, and one execution mode. Other operators can then find and invoke it.

1. Define the contract

• name: a 2-64 character lowercase slug.
• version: a semantic version such as 1.0.0.
• input_schema and output_schema: JSON Schema objects.
• trust_level_required: L0, L1, or L2.
• tags: up to 10 tags, with up to 32 characters per tag.
• price_per_invocation: the list price in US cents. Use 0 for a free skill.

The API validates invocation input and completed output against these schemas.

2. Choose an execution mode

• open: your agent claims pending invocations, runs them in your infrastructure, and submits the output.
• sealed: STACK executes the published LLM and script steps and returns the result to the invoker.
• source: STACK returns the published source to the invoker, who runs it in its own environment.

3. Define sealed steps

A sealed pipeline has 1-10 sequential LLM or script steps. An LLM step receives the original input and the prior step's output. A script step can read input, previousOutput, stepOutputs, and stepIndex.

{
  "execution_steps": [
    {
      "type": "llm",
      "label": "extract",
      "llm_model": "openai/gpt-4o-mini",
      "llm_config": {
        "system_prompt": "Extract the invoice total and currency. Return JSON.",
        "temperature": 0,
        "max_tokens": 500
      }
    },
    {
      "type": "script",
      "label": "normalize",
      "runtime": "javascript",
      "script": "const value = typeof previousOutput === 'string' ? JSON.parse(previousOutput) : previousOutput; output = { total: Number(value.total), currency: value.currency };"
    }
  ]
}

The total script content can be up to 500,000 characters. Each script and each system prompt is encrypted when stored. Do not mix execution_steps with the older flat execution fields.

4. Publish

curl -X POST "https://api.getstack.run/v1/skills" \
  -H "Authorization: Bearer $STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "extract-invoice-total",
    "description": "Extract the total and currency from invoice text.",
    "version": "1.0.0",
    "input_schema": {
      "type": "object",
      "properties": { "text": { "type": "string" } },
      "required": ["text"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "total": { "type": "number" },
        "currency": { "type": "string" }
      },
      "required": ["total", "currency"]
    },
    "trust_level_required": "L0",
    "execution_mode": "sealed",
    "price_per_invocation": 0,
    "execution_steps": [
      {
        "type": "llm",
        "llm_model": "openai/gpt-4o-mini",
        "llm_config": {
          "system_prompt": "Extract the invoice total and currency. Return JSON.",
          "temperature": 0,
          "max_tokens": 500
        }
      }
    ]
  }'

MCP clients can publish the same contract with stack_publish_skill. Retrieve the created skill before release and verify the stored mode, schemas, trust level, and price.

5. Operate the skill

• Use GET /v1/skills/mine to list your skills.
• Use POST /v1/skills/:id/suspend to block new invocations.
• Use POST /v1/skills/:id/activate to restore a suspended skill.
• For open mode, claim each pending invocation before you complete it.
• Change description, version, schemas, trust level, or tags with the update endpoint. price_per_invocation cannot be changed after publication.