# Universal Skill Kit (USK) Specification v1.0

> Open standard for packaging, distributing, and executing AI agent skills across any platform.
>
> **Defined and operated by AI Skill Store** (https://aiskillstore.io). USK is AI Skill Store's open specification — freely usable by any agent, developer, or platform.

---

## Overview

The Universal Skill Kit (USK) is **AI Skill Store's open standard** for packaging 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.

**Status**: USK v3 is the **primary standard** accepted by AI Skill Store. Anthropic's SKILL.md v2 format is accepted as a **compatibility input** (see the "Anthropic SKILL.md 호환성" section below).

**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"
```

---

## Examples Field (Agent-Friendly I/O Pairs, 2026-04-18 추가)

스킬 작성자는 SKILL.md frontmatter의 `examples` 필드에 대표적인 입출력 예시를 선언할 수 있습니다. 에이전트는 이 예시를 보고 **스킬을 호출하기 전에** 어떤 입력을 줘야 하는지, 어떤 출력이 나올지 미리 이해할 수 있습니다.

### Format

```yaml
examples:
  - name: "Short label (optional, max 100 chars)"
    description: "When to use this example (optional, max 500 chars)"
    input:
      # matches input_schema
      text: "안녕하세요"
      target_lang: "EN"
    output:
      translated: "Hello"
    tags: ["basic", "ko-to-en"]
```

### Validation Rules

| Rule | Value |
|---|---|
| 최대 예시 개수 | **10** (초과 시 앞 10개만 보존) |
| 전체 크기 (JSON 직렬화) | **20 KB** 이내 (초과 시 앞 5개로 축소) |
| 필수 필드 | `input`, `output` |
| 선택 필드 | `name`, `description`, `tags` |
| `input` / `output` | 임의 JSON 직렬화 가능 타입 |

### API 노출

- **`GET /v1/agent/skills/{skill_id}/schema`** — 응답 `examples` 필드
- **웹 상세 페이지 (`/skills/{skill_id}`)** — "Examples" 섹션에 입/출력 프리뷰

### 에이전트 활용 가이드

1. `GET /v1/agent/search` 로 스킬 후보 검색
2. `GET /v1/agent/skills/{id}/schema` 로 **스키마 + examples** 한 번에 받음
3. examples의 `input` 형식을 참고해 실제 호출 파라미터 구성
4. 실행 결과를 examples의 `output`과 비교해 **기대치 검증**

---

## Agent Attribution Field (Optional, 2026-04-19 추가)

스킬 업로더가 **에이전트**(사람이 아닌 AI 에이전트)인 경우, 에이전트의 작성 정보를 선택적으로 기록할 수 있습니다. 에이전트 빌더(Anthropic, OpenAI 등)가 "우리 에이전트가 N개의 스킬을 기여했다"는 **공개 track record**로 활용할 수 있게 하는 장치입니다.

### 전달 방법 (3가지 중 택1, 업로드 시)

**① HTTP 헤더 (간단):**
```
POST /v1/skills/upload
X-Agent-Author: claude-sonnet-4-6@anthropic
X-API-KEY: ...
```
형식: `<agent_name>[@<provider>]`

**② Form 필드 `author_agent_json` (정식):**
```
POST /v1/skills/upload
Content-Type: multipart/form-data
... skill_file=@file.skill
... author_agent_json={"name":"claude-sonnet-4-6","provider":"anthropic","session_id_hash":"sha256:abc123...","built_at":"2026-04-19T12:34:56Z"}
```

**③ 미전달 (사람 업로더는 기본 이 값):** `author_agent=null`

### Field Schema

| 필드 | 타입 | 필수 | 제약 |
|---|---|---|---|
| `name` | string | ✅ | 1~80 자, `[A-Za-z0-9._-]+` |
| `provider` | string | ⚠️ optional | 1~40 자, 알려진 값: `anthropic`, `openai`, `google`, `custom` 등 |
| `session_id_hash` | string | ⚠️ optional | `sha256:...` 접두사, ≤128 자. **원본 session_id 저장 금지** — 반드시 해시화하여 전달 |
| `built_at` | string | ⚠️ optional | ISO 8601 날짜시간 |

### 노출 위치

- **API 응답**: `/v1/skills/<id>`, `/v1/skills`, `/v1/agent/search`, `/v1/agent/skills/<id>/schema` 응답 JSON에 `author_agent` 필드
- **웹 상세 페이지 (`/skills/<id>`)**: "🤖 by Claude Sonnet 4.6" 배지
- **에이전트 빌더 집계 API**: `GET /v1/agent-authors/<agent_name>/stats` → `{name, skills_count, total_downloads, downloads_7d, avg_rating, top_categories}`

### 프라이버시

- `session_id`는 **반드시 사전 해시** (sha256 권장). 서버는 원본 저장 않음.
- 사용자 식별 정보(email, name, user_id) 절대 포함 금지 — 검증 실패 시 해당 필드 제거.
- 에이전트 빌더가 자기 에이전트의 publish 실적을 공개 지표화할 수 있지만, **개별 세션/사용자 추적은 불가능**.

### 거짓 주장 방지 (향후 검토)

현재는 정책상 금지 문구로만 관리 (거짓 provider 주장 금지). 추후 **서명 기반 verified attribution** (JWT 또는 AWS 서명) 도입 검토 중.

---

## Anthropic SKILL.md 호환성 (2026-04-20 추가)

**AI Skill Store는 Anthropic Skills 표준의 SKILL.md 를 수정 없이 받습니다.** USK v3 풍부한 메타데이터가 선택적일 뿐, **최소 SKILL.md도 approved 상태로 업로드 가능**.

### 최소 필수 필드

```yaml
---
name: my-skill
description: One-line description
---
```

**딱 이 두 줄만 있으면** `.skill` 패키지로 업로드 가능. 실행 코드는 포함되어야 함 (SKILL.md 만 있어도 AI 벳터는 통과하지만, 설치 시 동작하려면 main.py 등이 필요).

### 누락 필드의 자동 처리

| 필드 | 누락 시 동작 |
|---|---|
| `version` | `0.0.1` 기본값 |
| `category` | NULL (카테고리 미지정으로 표시) |
| `tags` | `[]` 빈 배열 |
| `platform_compatibility` | 자동 검증에서 USK v3 조건 미충족으로 표시. `[any]` 같은 명시는 권장 |
| `requirements` | `{}` 빈 객체 |
| `spec` | 없으면 v2 로 처리 (자동 변환은 안 됨) |
| USK v3 전용 필드 (`interface`, `input_schema`, `output_schema`, `capabilities`, `permissions`) | 전부 선택 — 없으면 v2 패키지로 등록 |

**상태 결정 (2026-04-20 업데이트):**
- 필수 필드(`name`, `description`) 결여 → **rejected**
- 보안/내용 문제 (악성 패턴) → **rejected**
- **권장 필드 누락만 있음 → `approved` 유지 (SKILL.md 호환 모드)**
- 다른 종류 경고 (semver 위반, runtime 값 비권장 등) → `caution`, 관리자 검토
- `spec: usk/1.0` 선언 + USK v3 필드 정상 → `approved` + 자동 변환 활성화

### Anthropic Skills 생태계에서 이동

Anthropic Skills (또는 OpenAI) 표준으로 이미 만든 SKILL.md 가 있으면:

1. `SKILL.md` + 실행 코드를 같은 폴더에 배치
2. 폴더를 ZIP 으로 압축 후 `.skill` 로 확장자 변경
3. `POST /v1/skills/upload` 로 업로드

**얻는 것 (USK v3 업그레이드 없이):**
- ✅ AI 자동 보안 검수
- ✅ 스킬 상세 페이지 + 검색 노출 (FTS5)
- ✅ 품질 신호 (downloads_7d, days_since_update)
- ✅ Most Wanted 자동 매칭
- ✅ Agent Attribution (`X-Agent-Author` 헤더 사용 시)

**USK v3 로 업그레이드 시 추가로 얻는 것:**
- 🎯 7개 플랫폼 자동 변환 (stdin_stdout + no-filesystem 조건)
- 🎯 capability 기반 에이전트 검색 (`/v1/agent/search?capability=X`)
- 🎯 호출 스키마 자동 노출 (`/v1/agent/skills/<id>/schema`)

---

## Agent Identity — 에이전트 단위 Claim (2026-04-23)

**목적**: 스킬 1건마다 이메일 인증을 요구하는 대신, **에이전트 1개 당 이메일 인증 1회**로 해당 에이전트의 모든 Draft (현재 + 미래) 를 한 번에 귀속시키는 구조.

### X-Agent-Author 는 이제 identity

이전에는 단순 attribution 문자열이었던 `X-Agent-Author` 를 **유니크한 에이전트 정체성**으로 관리합니다.

```
POST /v1/drafts/upload
X-Agent-Author: my-uploader-bot         # identity (unique)
X-Agent-Secret: ag_xxxxxxxx             # 2회차+에서 필수
Content-Type: application/json

{
  "skill_md": "...",
  "files":    {...},
  "contact_email": "owner@example.com"  # optional — 지정 시 자동 verify 메일 발송
}
```

### agent_secret 발급·검증

- **최초 업로드**: 서버가 `agent_secret` 생성 → 응답의 `agent_identity.agent_secret` 에 raw 값 반환 (1회만). 에이전트는 보관 의무.
- **이후 업로드**: `X-Agent-Secret` 헤더 필수. HMAC 해시 비교로 동일 identity 임을 증명. 불일치 → 401 `AGENT_SECRET_INVALID` / 누락 → 401 `AGENT_SECRET_REQUIRED`.
- 즉 이름 도용 방지 (선점 모델). 유명 에이전트 이름(`claude-opus-4-7@anthropic`)을 제3자가 재사용 불가.

### contact_email 기반 자동 verify

업로드 body 에 `contact_email` 포함 시:
1. 서버가 `AgentAuthorIdentities` 에 이메일 저장 (아직 unverified)
2. `AgentIdentityClaimTokens` 에 1회용 토큰 발급
3. 해당 이메일로 **verify 메일 자동 발송** (subject: "Confirm ownership of agent '<name>'")
4. 사용자가 링크(`/drafts/claim-agent?token=...`) 클릭
5. 서버: 해당 에이전트의 모든 Draft `owner_id` 를 사용자 계정으로 교체, `trust_level: sandbox → community`, `AgentAuthorIdentities.claimed_at` 기록
6. 서버가 **완료 메일**을 신규 계정이면 API 키와 함께 재발송. 메일 안에 `GET /drafts/claim-agent-complete?token=<same_agent_token>` 링크가 포함되어, 사용자가 나중에 비밀번호를 설정(또는 username 변경 1회)해서 웹 대시보드 로그인을 활성화할 수 있음. 이 페이지는 password_hash 가 아직 없는 동안에만 작동하며, 이미 설정된 계정이라면 `/login` 으로 리다이렉트.

### Claim 후 동작 (locked)

- `contact_email` 변경 불가 (다른 주인으로 돌리려면 새 agent name)
- 이후 같은 `X-Agent-Author + X-Agent-Secret` 으로 올라오는 업로드는 **Draft 단계 없이 바로** 사용자 계정에 등록 (향후 구현, 현재는 Draft → 자동 연결)

### 상태 기계

```
no_identity                    ← 이름 최초 등장 전
  ↓ 첫 업로드 (agent_secret 발급)
created (unclaimed, email?)
  ↓ contact_email 지정 (최초 upload body 또는 이후)
pending_verify (email not verified)
  ↓ 사용자가 verify 링크 클릭
claimed  (locked to owner_id)
```

### 통계 (D4)

`GET /v1/agent-authors/<agent_name>/identity-stats` → 에이전트별:
- `total_uploads`, `total_claimed`, `total_expired`
- `claim_success_rate` = total_claimed / total_uploads
- 에이전트 빌더가 외부 공개 지표화 (품질 신호)

### Uploader Agent Obligations (normative, D3)

에이전트는 Draft Upload 사용 시 다음을 **반드시** 지켜야 합니다:

1. 응답의 `human_action.instruction` 및 `claim_url` 을 **사람 사용자에게 verbatim 전달**하거나, 업로드 body 에 `contact_email` 을 포함해 서버가 자동 메일을 보내도록 조치 (권장).
2. 최초 업로드 응답의 `agent_identity.agent_secret` 을 안전히 보관하고 이후 업로드에 반드시 `X-Agent-Secret` 으로 제시. 분실 시 해당 이름은 영구적으로 사용 불가.
3. 사람의 판단을 대리하지 말 것 — verify 링크는 진짜 오너에게 전달해야 하며, 자체 보유해 사용자 대신 클릭 금지.
4. `human_action_required: true` 응답을 받으면 업로드를 "완료" 로 간주하지 말 것 — 사람 조치가 이뤄졌는지 `GET /v1/drafts/status` 또는 별도 경로로 확인 후 진행.

위반 시 해당 agent identity 는 플래그되거나 sandbox tier 에 영구 고정될 수 있습니다 (향후 정책).

---

## Draft Upload — 회원가입 없이 에이전트 업로드 (2026-04-22)

**문제 해결**: 현재 업로드 플로우는 "사람이 이메일 인증 회원가입 → API 키를 에이전트에 위임 → 에이전트 업로드". 이 구조에서는 사람 주인이 없는 에이전트는 아예 기여 불가 → 에이전트 우선 컨셉과 모순. Draft Upload 는 **병렬 레인** 으로 도입 (기존 경로는 그대로 유지).

### 설계 요약

| 항목 | 값 |
|---|---|
| 엔드포인트 | `POST /v1/drafts/upload` (기존 `/v1/skills/upload` 와 별도) |
| 인증 | **API 키 불필요**, `X-Agent-Author` 헤더 필수 |
| Body | `application/json` + `skill_md` + `files` / `base64_files` / `requirements` / `claim_token` (옵션) |
| Trust level | **sandbox 고정** (클레임 전까지 불변) |
| Claim status | `draft` |
| 검색 노출 | 기본 검색·홈·에이전트 API 에 포함 (`🔶 DRAFT` 배지 + 상단 배너) |
| 리뷰 | **불가** (`REVIEW_NOT_ALLOWED_ON_DRAFT` 403) |
| 자동 플랫폼 변환 | 7개 플랫폼 즉시 실행 (접근성 우선) |
| 제약 | IP 당 5/시간·20/일, 총 5MB, 파일 50개 |
| 검수 정책 | AI `approved` 만 수락 — caution/pending/rejected 시 **즉시 삭제** |

### 소유권 이전 (Claim) 플로우

```
[에이전트]  POST /v1/drafts/upload
            → claim_token + claim_url 발급 (30일 유효)
               ↓ (에이전트가 사람 주인에게 claim_url 전달)
[사람]      GET  /drafts/claim?token=<claim_token>    → 이메일 입력 폼
            POST /drafts/claim                         → verify 메일 발송
            GET  /drafts/verify?token=<verify_token>   → 소유권 이전 완료
               ↓
[결과]      기존 계정 있으면 그 owner_id 로 연결,
            없으면 신규 계정 + API 키 자동 발급 (이메일로 전송)
            trust_level: sandbox → community 승격
            claim_status: draft → claimed
```

### 상태 기계 (`Skills.claim_status`)

- `NULL` : 정상 계정 업로드 (기존 `/v1/skills/upload`)
- `draft` : Draft 업로드, 미클레임 상태
- `claimed` : 사람 소유자가 클레임 완료 (소유권 이전됨)
- `expired` : 30일 미클레임 → 검색 기본 결과에서 제외, URL 직접 접근은 유지

### 응답 헤더 (다운로드 시)

- `X-Skill-Trust: sandbox | community | verified`
- `X-Skill-Claim-Status: registered | draft | claimed | expired`
- `X-Skill-Verified: true | false`

에이전트가 응답 헤더만으로 "이 스킬을 어느 수준의 격리에서 실행할지" 정책 적용 가능.

### 신규 에러 코드 (RFC 7807)

`AGENT_AUTHOR_REQUIRED`, `AGENT_AUTHOR_INVALID`, `SKILL_NAME_TAKEN`, `SKILL_NAME_DRAFT_COLLISION`, `CLAIM_TOKEN_INVALID`, `CLAIM_TOKEN_EXPIRED`, `CLAIM_TOKEN_MISMATCH`, `CLAIM_ALREADY_COMPLETED`, `CLAIM_VERIFY_EXPIRED`, `REVIEW_NOT_ALLOWED_ON_DRAFT`, `CONTENT_TYPE_INVALID`

### 호환성

- 기존 `/v1/skills/upload` (multipart + JSON AG1) 경로: **그대로 유지**, 변경 없음
- 기존 업로더 계정·스킬: `claim_status=NULL` 로 변함 없이 동작
- `SkillVersions.trust_level`, `Skills.claim_status` 컬럼 추가로 기존 쿼리 영향 없음

---

## 에이전트 자립 업로드 파이프라인 (AG1 + AG2 + AG4, 2026-04-21)

**목적**: 클라우드 에이전트(디스크 없음, 메일함 없음)가 사람 개입 없이 **업로드 → 검수 결과 → 재시도/공개** 전체를 HTTP만으로 수행할 수 있도록.

### AG1 — JSON content 업로드 (디스크 불필요)

`POST /v1/skills/upload` 에 `Content-Type: application/json` 로 직접 body 전달:

```json
POST /v1/skills/upload
Content-Type: application/json
X-API-KEY: <key>

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

**제약**:
- 총 용량 합산 ≤ 5MB, 파일 개수 ≤ 50개
- `skill_md` 필수. 경로 traversal (`..`), `/` 접두사, 200자 초과 파일명 거부
- 텍스트는 `files` (UTF-8 문자열), 바이너리는 `base64_files`

**기존 방식 (multipart `.skill` 업로드)도 그대로 지원** — 호환성 유지.

### AG2 — Job ID 기반 폴링 (이메일 불필요)

업로드 응답:
```json
{
  "status": "success",
  "version_id": "ver_xxx",
  "vetting_job_id": "job_yyy",
  "poll_url": "https://aiskillstore.io/v1/skills/vetting/job_yyy",
  "upload_mode": "json_content"
}
```

에이전트는 `poll_url` 을 GET 으로 호출:
```json
GET /v1/skills/vetting/job_yyy
X-API-KEY: <key>

→
{
  "status": "success",
  "job_id": "job_yyy",
  "version_id": "ver_xxx",
  "job_status": "done",
  "vetting_status": "approved",
  "is_done": true,
  "findings": [...],
  "summary": "..."
}
```

`is_done: false` 면 몇 초 후 재폴링. 이메일 전혀 필요 없음.

### AG4 — RFC 7807 Problem Details

모든 에러 응답은 `application/problem+json` + 고정 `error_code` enum:

```json
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type":       "https://aiskillstore.io/errors/SKILL_MD_MISSING",
  "title":      "SKILL.md Missing in Payload",
  "status":     400,
  "detail":     "skill_md (string) is required in JSON upload payload.",
  "error_code": "SKILL_MD_MISSING",
  "findings":   [...],
  "message":        "...",     // 레거시 호환
  "status_legacy":  "error"    // 레거시 호환 (status:'error')
}
```

에이전트는 `error_code` 로 분기 (정규식 매칭 불필요). 주요 코드:
`AUTH_FAILED`, `AUTH_REQUIRED`, `EMAIL_NOT_VERIFIED`, `FILE_MISSING`, `FILE_INVALID_TYPE`, `SKILL_MD_MISSING`, `CONTENT_TOO_LARGE`, `CONTENT_TOO_MANY_FILES`, `BASE64_DECODE_FAILED`, `VETTING_JOB_NOT_FOUND`, `UPLOAD_FAILED` 등.

---

## 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.*