# Universal Skill Kit (USK) Specification v1.0

> Open standard for packaging, distributing, and executing AI agent skills across any platform.

---

## Overview

The Universal Skill Kit (USK) defines a platform-agnostic standard for AI agent skills. A skill packaged to this spec can be discovered, installed, and executed by any agent platform — without requiring platform-specific code from the developer.

**Core principles:**
- **Write once, run anywhere** — one skill package works across all compliant platforms
- **Agent-first** — designed to be consumed by agents, not just humans
- **Self-describing** — a skill declares everything an agent needs to call it correctly
- **Secure by default** — permissions are declared explicitly; vetting is automated

---

## Spec Version

| Field | Value |
|-------|-------|
| Spec version | `usk/1.0` |
| SKILL.md version | `v3` |
| Backward compatible with | SKILL.md v2 |

---

## 1. Package Structure

A `.skill` file is a ZIP archive with the following layout:

```
my-skill/
├── SKILL.md          # Required — metadata + description
├── main.py           # Entry point (any language — see entry_point field)
├── requirements.txt  # Optional — Python dependencies
└── ...               # Any additional files
```

Rules:
- The archive may contain a single root directory or files directly at the root
- `SKILL.md` must exist at the root level
- The entry point declared in `SKILL.md` must exist in the package

---

## 2. SKILL.md Format

`SKILL.md` is a Markdown file with a YAML front matter block at the top:

```
---
<YAML metadata>
---

<Human-readable description (Markdown)>
```

---

## 3. SKILL.md v3 Fields

### 3-1. Identity (Required)

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Unique skill identifier. 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 |
| `spec` | string | Must be `usk/1.0` for v3 skills |

### 3-2. Interface (Required for agent execution)

Defines how an agent calls this skill.

```yaml
interface:
  type: cli                    # cli | http
  entry_point: main.py         # Executable file (any language)
  runtime: python3             # python3 | node | bash | binary | any
  call_pattern: stdin_stdout   # stdin_stdout | args | http_post
```

**`type`**
- `cli` — skill is executed as a subprocess; input via stdin, output via stdout
- `http` — skill exposes an HTTP endpoint (developer-hosted)

**`call_pattern`** (for `type: cli`)
- `stdin_stdout` — agent writes JSON to stdin, reads JSON from stdout *(recommended)*
- `args` — input passed as command-line arguments

**`call_pattern`** (for `type: http`)
- `http_post` — agent sends POST request with JSON body, receives JSON response

### 3-3. Schemas (Required for agent execution)

JSON Schema definitions for input and output. Agents use these to construct calls automatically.

```yaml
input_schema:
  type: object
  properties:
    query:
      type: string
      description: "The search query"
    max_results:
      type: integer
      description: "Maximum number of results to return"
      default: 5
  required:
    - query

output_schema:
  type: object
  properties:
    result:
      type: string
    sources:
      type: array
      items:
        type: string
  required:
    - result
```

- Follows [JSON Schema Draft-07](https://json-schema.org/specification-links.html#draft-7)
- Every property should have a `description` — agents use this to understand the field
- `required` lists the fields that are always present in the output

### 3-4. Capabilities (Required for discovery)

Semantic tags used by agents to find skills by function, not just by name.

```yaml
capabilities:
  - web_search
  - information_retrieval
  - real_time_data
```

Recommended capability vocabulary:

| Category | Values |
|----------|--------|
| Information | `web_search`, `document_search`, `database_query`, `information_retrieval` |
| Processing | `text_summarization`, `translation`, `classification`, `extraction` |
| Generation | `text_generation`, `code_generation`, `image_generation` |
| Action | `file_management`, `email`, `calendar`, `notification` |
| Data | `data_analysis`, `visualization`, `calculation`, `conversion` |
| Integration | `api_integration`, `webhook`, `automation` |

Custom capabilities are allowed. Use `snake_case`.

### 3-5. Permissions (Required)

Declares what the skill accesses. Agents and platforms use this to decide whether to auto-install.

```yaml
permissions:
  network: true          # Makes outbound HTTP/HTTPS requests
  filesystem: false      # Reads or writes local files
  subprocess: false      # Spawns child processes
  env_vars:
    - TAVILY_API_KEY     # Environment variables required at runtime
```

- All permission fields default to `false` if omitted
- Be accurate — underreporting permissions may cause your skill to be rejected
- `env_vars` lists keys that must be set in the environment before the skill runs

### 3-6. Classification (Optional but recommended)

```yaml
category: search              # Single primary category
tags:                         # Free-form search tags
  - tavily
  - search
  - real-time
author: your-username         # Skill Store username
license: MIT                  # SPDX license identifier
homepage: https://github.com/...
```

### 3-7. Platform Compatibility (Optional)

```yaml
platform_compatibility:
  - any                 # Works on any USK-compliant platform
  # or list specific platforms:
  # - OpenClaw
  # - ClaudeCode
  # - CustomAgent
```

Use `any` when your skill uses only `stdin_stdout` CLI interface with no platform-specific code.

### 3-8. Requirements (Optional)

```yaml
requirements:
  python_packages:
    - requests>=2.28.0
    - tavily-python
  node_packages: []
  min_python: "3.9"
  min_node: "18"
```

### 3-9. Changelog (Optional)

```yaml
changelog: "1.0.0: Initial release"
```

---

## 4. Complete Example

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

interface:
  type: cli
  entry_point: main.py
  runtime: python3
  call_pattern: stdin_stdout

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_schema:
  type: object
  properties:
    result:
      type: string
      description: "Summarized answer"
    sources:
      type: array
      description: "Source URLs"
      items:
        type: string
  required:
    - result

capabilities:
  - web_search
  - information_retrieval
  - real_time_data

permissions:
  network: true
  filesystem: false
  subprocess: false
  env_vars:
    - TAVILY_API_KEY

category: search
tags:
  - tavily
  - search
  - real-time
author: your-username
license: MIT
platform_compatibility:
  - any

requirements:
  python_packages:
    - tavily-python>=0.3.0

changelog: "1.0.0: Initial release"
---

## Tavily Web Search

Performs real-time web search using the Tavily API and returns a summarized answer with source URLs.

### Usage

Set `TAVILY_API_KEY` environment variable before running.

### Input

```json
{ "query": "latest AI news", "max_results": 5 }
```

### Output

```json
{
  "result": "Summary of search results...",
  "sources": ["https://...", "https://..."]
}
```
```

---

## 5. Execution Contract

When a platform executes a `cli` + `stdin_stdout` skill:

```
# Platform writes to stdin:
{"query": "hello world", "max_results": 3}

# Skill reads from stdin, processes, writes to stdout:
{"result": "...", "sources": [...]}
```

Rules the skill must follow:
1. Read exactly one JSON object from stdin
2. Write exactly one JSON object to stdout
3. All log/debug output goes to **stderr**, never stdout
4. Exit code `0` on success, non-zero on error
5. On error, stdout must be: `{"error": "description of error"}`

---

## 6. Auto-Conversion

When a v3 skill is uploaded to Skill Store, the platform automatically generates platform-specific packages:

| Target | What is generated |
|--------|------------------|
| OpenClaw | `openclaw_wrapper.py` + install manifest |
| Claude Code | Slash command `.md` + runner script |
| CustomAgent | REST adapter + OpenAPI snippet |

The developer writes only the core logic + `SKILL.md`. Wrappers are generated automatically.

**Conversion is possible only when:**
- `interface.type` is `cli` and `call_pattern` is `stdin_stdout`
- `permissions.filesystem` is `false`
- `platform_compatibility` includes `any` or the target platform

Skills that cannot be auto-converted are marked as `manual_install` and require the user to follow platform-specific instructions.

---

## 7. Agent Discovery API

Agents discover and use skills via the Skill Store API:

```
# Search by capability
GET /v1/agent/search?capability=web_search&platform=any

# Get full schema for a skill (agent uses this to construct calls)
GET /v1/agent/skills/{skill_id}/schema

# Get platform-specific package
GET /v1/agent/skills/{skill_id}/download?platform=OpenClaw

# Health check / spec version
GET /v1/agent/info
```

All responses are JSON. No HTML, no sessions, no cookies.

---

## 8. Authentication

Skill Store uses API key authentication for all write operations:

```
Authorization: Bearer sk_...
```

- API keys are issued per developer account
- An agent acts on behalf of a developer using their API key
- Read operations (search, download) are unauthenticated for public skills

---

## 9. Backward Compatibility

SKILL.md v2 packages (without `spec: usk/1.0`) continue to work. They are treated as `manual_install` only — auto-conversion and agent discovery features require v3.

| Feature | v2 | v3 |
|---------|----|----|
| Upload & publish | ✅ | ✅ |
| Security vetting | ✅ | ✅ |
| Manual download | ✅ | ✅ |
| Auto-conversion | ❌ | ✅ |
| Agent search (capability) | ❌ | ✅ |
| Agent schema fetch | ❌ | ✅ |

---

## 10. Versioning This Spec

This document is versioned as `usk/1.0`. Future versions will be backward-compatible unless a major version bump occurs. The `spec` field in `SKILL.md` declares which version of USK a skill targets.

---

*USK Specification — maintained by Skill Store. Contributions and feedback welcome via GitHub Issues.*