What are the auto-conversion conditions for USK v3?

Three conditions: interface.type must be 'cli', interface.call_pattern must be 'stdin_stdout', and permissions.filesystem must be false. Skills meeting all three are automatically packaged for OpenClaw, Claude Code, and Custom Agent on upload.

What is the stdin_stdout call pattern?

A call pattern where the agent passes a JSON object to the skill process via stdin and reads the JSON result from stdout. The skill runs as a subprocess — no HTTP server required.

How does trust level work in AI Skill Store?

Security vetting result maps to trust level: approved → verified, caution → community, flagged → sandbox. Agents can filter skills by trust using the ?trust= parameter on /v1/agent/search.

SKILL.md Guide — How to Build & Publish AI Agent Skills

Contents

1. What is a .skill package? 2. USK v3 — agent-compatible skills 3. Field reference 4. Full example 5. Package structure 6. Upload & vetting 7. Agent API

1. What is a .skill package?

A .skill file is a ZIP archive containing your skill's code, metadata, and everything needed to run it. Upload it once — AI Skill Store automatically converts it for every supported agent platform.

Every package must include a SKILL.md at the root. Declare spec: usk/1.0 to unlock auto-conversion and agent discovery features.

2. USK v3 — Agent-Compatible Skills

USK v3 adds four blocks to SKILL.md that make your skill callable by any agent without platform-specific code:

✅ Auto-conversion condition: interface.type = cli + call_pattern = stdin_stdout + permissions.filesystem = false

3. Field Reference

Identity (required)

Field	Type	Description
spec	string	Must be usk/1.0 for agent-compatible skills
name	string	Unique ID. Lowercase + hyphens only. e.g. web-search
version	string	Semantic version. e.g. 1.0.0
description	string	One-line description shown in search results

Interface (required for USK v3)

Field	Values	Description
interface.type	cli \| http	cli = subprocess; http = developer-hosted endpoint
interface.entry_point	filename	Executable file. Any language. e.g. main.py, index.js
interface.runtime	python3 \| node \| bash \| binary \| any	Runtime environment
interface.call_pattern	stdin_stdout \| args \| http_post	stdin_stdout recommended for auto-conversion

Permissions (required for USK v3)

Field	Type	Description
permissions.network	boolean	Makes outbound HTTP/HTTPS requests
permissions.filesystem	boolean	Reads or writes local files (disables auto-convert)
permissions.subprocess	boolean	Spawns child processes
permissions.env_vars	list	Environment variable names required at runtime

Optional Fields

Field	Description
capabilities	Semantic tags for agent search. e.g. [web_search, information_retrieval]
platform_compatibility	List of platforms or [any]
category	Primary category. e.g. search, translation, code
tags	Free-form search tags
author	Your AI Skill Store username
license	SPDX license. e.g. MIT, Apache-2.0
homepage	URL to source code or docs
requirements.python_packages	pip packages. e.g. requests>=2.28.0
requirements.min_python	Minimum Python version. e.g. "3.9"
changelog	What changed in this version

4. Full Example

---
spec:        usk/1.0
name:        tavily-web-search
version:     1.0.0
description: Real-time web search powered by Tavily API

# How to run this skill
interface:
  type:          cli
  entry_point:   main.py
  runtime:       python3
  call_pattern:  stdin_stdout   # JSON in → JSON out

# Input the agent sends
input_schema:
  type: object
  properties:
    query:
      type: string
      description: "Search query string"
    max_results:
      type: integer
      description: "Max number of results"
      default: 5
  required: [query]

# Output the skill returns
output_schema:
  type: object
  properties:
    result:
      type: string
      description: "Summarized answer"
    sources:
      type: array
      description: "Source URLs"
  required: [result]

# Agents search by capability, not name
capabilities:
  - web_search
  - information_retrieval
  - real_time_data

# What this skill accesses
permissions:
  network:     true
  filesystem:  false
  subprocess:  false
  env_vars:    [TAVILY_API_KEY]

category:    search
author:      your-username
license:     MIT
platform_compatibility: [any]
requirements:
  python_packages: [tavily-python>=0.3.0]
---

## Tavily Web Search

Real-time web search skill using the Tavily API.

✅ This skill satisfies auto-conversion conditions → packages for OpenClaw, Claude Code, and Custom Agent are generated automatically on upload.

5. Package Structure

ZIP your files and rename the archive to .skill. Keep it minimal — only include what's needed to run the skill.

tavily-web-search-1.0.0.skill (ZIP archive) ├── SKILL.md # Required — USK v3 metadata + description ├── main.py # Entry point — reads JSON stdin, writes JSON stdout └── requirements.txt # pip dependencies (optional)

# main.py — minimal stdin_stdout skill
import sys, json

def main():
    data = json.loads(sys.stdin.read())
    query = data["query"]
    # ... call your API ...
    result = {"result": "answer", "sources": []}
    print(json.dumps(result))   # stdout only

if __name__ == "__main__":
    main()

⚠ stderr is for logs only. Never write non-JSON to stdout. Exit code must be 0 on success.

6. Upload & Vetting

STEP 1

Create account

Register at /register — API key is auto-generated

STEP 2

Package skill

ZIP your files + SKILL.md → rename to .skill

STEP 3

Upload

Developer Portal → Upload tab, or POST /v1/skills/upload with API key

STEP 4

Auto-vetting

Security scan runs automatically. USK v3 skills are also validated for auto-convert eligibility.

💡 Agents can upload skills too — use POST /v1/skills/upload Authorization: Bearer <api_key>

Create Account Sign In 📡 API Docs

7. Agent API

Agents discover and install skills programmatically — no human needed.

# 1. Discover skills by capability
GET /v1/agent/search?capability=web_search&platform=any

# 2. Get full call schema
GET /v1/agent/skills/{skill_id}/schema

# 3. Download platform-specific package
GET /v1/agent/skills/{skill_id}/download?platform=OpenClaw
GET /v1/agent/skills/{skill_id}/download?platform=ClaudeCode
GET /v1/agent/skills/{skill_id}/download?platform=CustomAgent

# 4. Service info
GET /v1/agent/info

Read endpoints are public (no auth). Upload requires Authorization: Bearer <api_key>

FAQ

What is a .skill file?+

A .skill file is a ZIP archive containing SKILL.md (metadata) and the skill code (e.g. main.py). Rename any .zip to .skill before uploading.

What are the auto-conversion conditions?+

Three conditions must all be true: interface.type = cli, interface.call_pattern = stdin_stdout, and permissions.filesystem = false. Skills meeting these are automatically packaged for OpenClaw, Claude Code, and Custom Agent on upload.

What is stdin_stdout?+

A call pattern where the agent passes a JSON object to the skill via stdin and reads the JSON result from stdout. No HTTP server needed — the skill runs as a subprocess.

Can skills use external libraries?+

Yes. List pip packages under requirements.python_packages in SKILL.md. For auto-conversion to work, avoid packages that require compiled binaries specific to one OS.

How does trust level work?+

Vetting result maps to trust: approved → verified (green), caution → community (yellow), flagged → sandbox (grey). Agents can filter by trust using the ?trust= parameter on /v1/agent/search.

📖 SKILL.md Guide