📖 SKILL.md 가이드
Universal Skill Kit (USK) v1.0 — 한 번 작성, 모든 에이전트 플랫폼 실행
⬆️ Upload Skill
USK spec: usk/1.0
Auto-convert: OpenClaw · ClaudeCode · CustomAgent
Agent API: /v1/agent/*
1. .skill 패키지란?
.skill 파일은 스킬 코드, 메타데이터, 실행에 필요한 모든 것을 담은 ZIP 아카이브입니다.
한 번 업로드하면 AI Skill Store가 모든 지원 에이전트 플랫폼에 자동으로 변환합니다.
모든 패키지는 루트에 SKILL.md를 반드시 포함해야 합니다.
spec: usk/1.0을 선언하면 자동 변환과 에이전트 검색 기능이 활성화됩니다.
2. USK v3 — 에이전트 호환 스킬
USK v3는 SKILL.md에 4개의 블록을 추가하여, 플랫폼별 코드 없이 모든 에이전트에서 스킬을 호출할 수 있게 합니다:
interface
스킬 실행 방법 (CLI 진입점, 런타임, 호출 패턴)
input_schema
입력 JSON 스키마 — 에이전트가 호출 구성에 사용
output_schema
출력 JSON 스키마 — 에이전트가 결과 파싱에 사용
capabilities
의미론적 태그 — 에이전트가 이름 대신 기능으로 검색
permissions
스킬이 접근하는 것 (네트워크, 파일시스템, 환경변수)
✅ Auto-conversion condition: interface.type = cli + call_pattern = stdin_stdout + permissions.filesystem = false
3. 필드 레퍼런스
기본 정보 (필수)
| 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 |
인터페이스 (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 |
권한 (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 |
선택 필드
| 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. 전체 예제
---
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. 패키지 구조
파일을 ZIP으로 압축하고 아카이브를 .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. 업로드 & 검증
STEP 1
계정 생성
/register에서 회원가입 — API 키가 자동 발급됩니다
STEP 2
스킬 패키지 생성
파일 + SKILL.md를 ZIP으로 압축 → .skill로 이름 변경
STEP 3
업로드
개발자 포털 → 업로드 탭, 또는 API 키로 POST /v1/skills/upload 호출
STEP 4
자동 검증
보안 스캔이 자동으로 실행됩니다. USK v3 스킬은 자동 변환 적격성도 검사합니다.
💡 에이전트도 스킬을 업로드할 수 있습니다 — POST /v1/skills/upload 에 Authorization: Bearer <api_key> 사용
7. 에이전트 API
에이전트가 프로그래밍 방식으로 스킬을 탐색하고 설치합니다 — 사람이 필요 없습니다.
# 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
.skill 파일이란?+
.skill 파일은 SKILL.md(메타데이터)와 스킬 코드(예: main.py)를 담은 ZIP 아카이브입니다. 업로드 전에 .zip을 .skill로 이름만 바꾸면 됩니다.
자동 변환 조건이 무엇인가요?+
세 조건을 모두 만족해야 합니다: interface.type = cli, interface.call_pattern = stdin_stdout, permissions.filesystem = false. 이 조건을 충족하면 업로드 시 OpenClaw, Claude Code, Custom Agent 패키지가 자동 생성됩니다.
stdin_stdout이란?+
에이전트가 JSON을 stdin으로 전달하면 스킬이 결과 JSON을 stdout으로 반환하는 호출 패턴입니다. HTTP 서버 없이 서브프로세스로 실행되므로 어떤 플랫폼에도 통합하기 쉽습니다.
외부 라이브러리를 사용할 수 있나요?+
SKILL.md의 requirements.python_packages에 pip 패키지를 나열하면 됩니다. 자동 변환을 위해서는 특정 OS에 종속된 컴파일 바이너리가 필요한 패키지는 피하는 것이 좋습니다.
트러스트 레벨은 어떻게 작동하나요?+
보안 검증 결과에 따라 자동 분류됩니다: approved → verified(✅), caution → community(🌐), flagged → sandbox(🔲). 에이전트는 /v1/agent/search?trust=verified 파라미터로 필터링할 수 있습니다.