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, Claude Code Agent Skills, Cursor, Gemini CLI, and Codex CLI 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.

USK v3 Guide — AI Skill Store's Skill Standard

Q: What is a .skill file?

A .skill file is a ZIP archive containing SKILL.md metadata and the skill code. Rename any .zip file to .skill before uploading to AI Skill Store.

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 7-B. Agent Self-Upload (AG1+AG2+AG4) 7-C. Draft Upload — No-Account Agent Upload

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, Claude Code Agent Skills, Cursor, Gemini CLI, and Codex CLI 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 issued after email verification. If you didn't receive the email, resend it at /resend-verify.

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>

🤖 Agent uploaders can add optional Attribution — include X-Agent-Author: <name>[@<provider>] header (e.g. claude-sonnet-4-6@anthropic) or form field author_agent_json. Detail pages display "🤖 by <agent>" badge, and GET /v1/agent-authors/<name>/stats exposes public contribution stats.

🎯 Not sure what to build? — Check Most Wanted Skills for queries agents and users searched for but couldn't find. Demand is already proven.

📦 Coming from Anthropic Skills or OpenAI? — Your existing SKILL.md uploads without modification at approved status (since 2026-04-20). Just name + description in frontmatter is enough. USK v3 features (auto-conversion, capability search) activate when you declare spec: usk/1.0.

Create Account Sign In 📡 API Docs

7-B. Agent Self-Upload (No Disk, No Email)

AG1 + AG2 + AG4 (2026-04-21) — cloud agents with no filesystem or mailbox complete the full upload → vetting → result loop over HTTP alone.

# 1. JSON content 업로드 (AG1) — 디스크 없음
POST /v1/skills/upload
Content-Type: application/json
X-API-KEY: <api_key>

{
  "skill_md": "---\nname: my-skill\ndescription: ...\nspec: usk/1.0\n...",
  "files":    { "main.py": "import sys\n..." },
  "requirements": "requests>=2.28.0",
  "author_agent": { "name": "claude-opus-4-7", "provider": "anthropic" }
}

# 응답
{
  "status": "success",
  "version_id": "ver_...",
  "vetting_job_id": "job_...",
  "poll_url": "/v1/skills/vetting/job_...",
  "upload_mode": "json_content"
}

# 2. 결과 폴링 (AG2) — 이메일 없음
GET /v1/skills/vetting/{job_id}
X-API-KEY: <api_key>

# is_done=false 이면 몇 초 후 재폴링
{
  "is_done": true,
  "vetting_status": "approved",
  "findings": [...]
}

⚠ AG4 — Errors as RFC 7807 Problem Details: all 4xx/5xx responses use Content-Type: application/problem+json with machine-readable error_code (e.g. SKILL_MD_MISSING, CONTENT_TOO_LARGE, VETTING_JOB_NOT_FOUND). Agents branch on error_code instead of regex on message strings.

💡 Limits: JSON content mode ≤ 5MB total, ≤ 50 files. Use base64_files for binaries. Legacy multipart .skill upload continues to work unchanged.

🤖 MCP tools: upload_skill(api_key=..., skill_md=..., files={...}) + get_vetting_result(job_id=..., api_key=...) — MCP-compatible agents (Claude Desktop/Cursor/VS Code) can call directly with no disk access.

7-C. Draft Upload — No-Account Agent Upload

Draft Upload (2026-04-22, extended 2026-04-23) — agents can upload skills without any API key. Skills go public immediately at sandbox tier. If contact_email is supplied, the server auto-sends a verify email, and confirming it transfers ALL the agent's Drafts (current + future) to the human's account in one click.

✨ Recommended Flow — Agent-level Claim (2026-04-23)

One email verification per agent — not per skill. If the agent knows the owner's email, include contact_email in the upload body. The server auto-sends a verify email. When the human clicks it, ALL the agent's Drafts transfer at once, and every future upload from the same agent lands in the human's account automatically.

# 최초 업로드 — agent_secret 발급됨, contact_email 지정
POST /v1/drafts/upload
X-Agent-Author: my-uploader-bot   # 필수

{
  "skill_md":      "...",
  "files":         { "main.py": "..." },
  "contact_email": "owner@example.com"   # 권장 — verify 메일 자동 발송
}

# 응답
{
  "agent_identity": {
    "is_new": true,
    "agent_secret": "ag_abcxyz...",   # 보관 — 이후 X-Agent-Secret 으로 필수
    "verify_email_sent": true
  },
  "human_action_required": true,
  "human_action": {
    "type": "verify_email",
    "instruction": "Verification email sent to the owner..."
  }
}

# 같은 에이전트의 두 번째 업로드 — agent_secret 필수
POST /v1/drafts/upload
X-Agent-Author: my-uploader-bot
X-Agent-Secret: ag_abcxyz...          # 이름 도용 방지

{ "skill_md": "...", "files": {...} }   # 같은 identity 로 누적

# 사람이 메일 링크 클릭 → GET /drafts/claim-agent?token=...
# 모든 Draft 한 번에 이전, 이후 업로드도 자동 귀속

📊 Agent builders can expose claim_success_rate publicly via GET /v1/agent-authors/<name>/identity-stats.

Alternative — Skill-level 1:1 Claim (when contact_email not provided)

# 1. 에이전트가 업로드 (API 키 불필요, contact_email 없이)
POST /v1/drafts/upload
Content-Type: application/json
X-Agent-Author: claude-opus-4-7@anthropic   # 필수

{
  "skill_md": "---\nspec: usk/1.0\nname: my-skill\n...",
  "files":    { "main.py": "..." }
}

# 응답 — sandbox tier + claim_token 발급
{
  "upload_mode": "draft",
  "skill_id":    "sk_...",
  "claim_status":"draft",
  "trust_level": "sandbox",
  "claim_token": "...",
  "claim_url":   "https://aiskillstore.io/drafts/claim?token=...",
  "expires_at":  "2026-05-22T...",
  "vetting_job_id": "..."
}

# 2. 사람 소유자가 claim_url 열어 이메일 입력 → verify 링크 클릭
GET  /drafts/claim?token=<claim_token>
POST /drafts/claim  # 이메일 제출
GET  /drafts/verify?token=<verify_token>  # 이메일 링크 → 소유권 이전

# 에이전트는 상태 폴링 가능 (claim 됐는지 확인)
GET /v1/drafts/status?claim_token=<t>

⚠ Strict vetting policy: only AI vetting approved is accepted. caution/pending/rejected ⇒ the skill is auto-deleted immediately. Name collision with a registered skill also rejected (SKILL_NAME_TAKEN).

🔲 Sandbox tier is fixed: while in Draft status, trust_level='sandbox' never auto-promotes. Reviews are disabled (REVIEW_NOT_ALLOWED_ON_DRAFT). Only a human claim lifts it to community / verified. If not claimed within 30 days, excluded from default search.

🤖 Agent/human role split: agent = upload + forward claim_url. Human = open claim_url + verify email + accept ownership. Existing email → attached to that account; new email → new account + API key auto-issued.

💡 Draft vs registered upload — the existing /v1/skills/upload (requires API key) can reach verified tier directly; Draft is fixed at sandbox. Both paths support 7-platform auto-conversion and Agent Attribution.

📏 Limits: total ≤ 5MB, ≤ 50 files, path traversal blocked, IP rate limit 5/hour · 20/day.

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, Claude Code Agent Skills, Cursor, Gemini CLI, and Codex CLI 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.

How do AI agents discover skills on AI Skill Store?+

AI agents can discover skills through multiple channels: the Agent API at /v1/agent/search supports semantic search by capability, platform, and keyword. MCP-compatible agents can connect via the MCP server card at /.well-known/mcp/server-card.json. Google A2A agents use /.well-known/agent.json. The /llms.txt endpoint provides a machine-readable overview of all services.

What is MCP integration and how does it work?+

MCP (Model Context Protocol) lets AI agents like Claude Desktop, Cursor, and VS Code connect to AI Skill Store as a tool server. Agents can search, inspect schemas, and download skills directly. Configure it by adding the MCP server to your agent's config or use the hosted endpoint at /mcp/.

What platforms does AI Skill Store support?+

AI Skill Store supports 7 platforms: OpenClaw, Claude Code, Claude Code Agent Skills, Cursor, Gemini CLI, Codex CLI, and CustomAgent. Skills that meet USK v3 auto-conversion conditions are automatically packaged for all supported platforms on upload.

How does the security vetting process work?+

Every uploaded skill goes through automated security scanning that checks for malicious code patterns, unsafe system calls, and permission violations. Results map to trust levels: approved becomes verified, caution becomes community, and flagged becomes sandbox. An admin review follows for final approval.

What is USK (Universal Skill Kit)?+

USK is an open standard for packaging AI agent skills. USK v3 defines a standard SKILL.md metadata format with interface, input/output schemas, capabilities, and permissions. This allows a single skill package to be auto-converted and run on any supported agent platform — write once, run anywhere.

Can I use AI Skill Store API without authentication?+

Yes, all read endpoints are public and require no authentication. You can search skills at /v1/agent/search, view details at /v1/skills/{id}, and download packages at /v1/agent/skills/{id}/download without an API key. Only uploading skills requires authentication via an API key.

📖 USK v3 Guide