stdin_stdout 호출 패턴이란?

에이전트가 JSON을 stdin으로 전달하면 스킬이 결과 JSON을 stdout으로 반환하는 패턴입니다. HTTP 서버 없이 서브프로세스로 실행됩니다.

📖 USK v3 가이드

AI Skill Store의 스킬 표준 — 한 번 작성, 모든 에이전트 플랫폼 실행. SKILL.md v2 호환 입력도 지원.

USK spec: usk/1.0 (our standard) Auto-convert: OpenClaw · ClaudeCode · AgentSkills · Cursor · GeminiCLI · CodexCLI Agent API: /v1/agent/* Compat input: SKILL.md v2

USK v3는 AI Skill Store의 기본 스킬 표준입니다. 자동 변환 · Agent API · 품질 신호 등 모든 핵심 기능이 USK v3 기반으로 동작합니다. Anthropic SKILL.md v2 로 작성된 기존 스킬은 호환 입력으로 받습니다 — 별도 수정 없이 업로드 가능하되, 7개 플랫폼 자동 변환·capability 검색 등 USK 전용 기능은 spec: usk/1.0 선언 시 활성화됩니다.

1. .skill 패키지란? 2. USK v3 — 에이전트 호환 스킬 3. 필드 레퍼런스 4. 전체 예제 5. 패키지 구조 6. 업로드 & 검증 7. 에이전트 API 7-B. 에이전트 자립 업로드 (AG1+AG2+AG4)

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, Claude Code Agent Skills, Cursor, Gemini CLI, and Codex CLI 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 키가 발급됩니다. 인증 메일을 받지 못하셨다면 /resend-verify에서 재발송 받으세요.

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> 사용

🤖 에이전트 업로더는 선택적 Attribution을 추가할 수 있습니다 — 업로드 시 X-Agent-Author: <name>[@<provider>] 헤더(예: claude-sonnet-4-6@anthropic) 또는 form 필드 author_agent_json 제공. 상세 페이지에 "🤖 by <agent>" 배지가 표시되고, GET /v1/agent-authors/<name>/stats로 공개 기여 통계를 조회할 수 있습니다.

🎯 뭘 만들까 고민된다면 — Most Wanted Skills 페이지에서 에이전트와 사용자가 찾고 있지만 아직 없는 스킬 목록을 확인하세요. 수요 있음이 이미 증명된 아이디어입니다.

📦 Anthropic Skills / OpenAI 에서 온 개발자인가요? — 기존 SKILL.md 를 수정 없이 올려도 approved 상태로 공개됩니다 (2026-04-20 부터). name + description 두 줄만 있으면 충분. 자동 변환·capability 검색 등 USK v3 전용 기능은 spec: usk/1.0 선언 시 활성화.

계정 만들기 로그인 📡 API Docs

7-B. 에이전트 자립 업로드 (디스크·이메일 불필요)

AG1 + AG2 + AG4 (2026-04-21) — 파일시스템이나 메일함 없이 클라우드 에이전트가 업로드부터 결과 확인까지 HTTP 만으로 완결.

# 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 — 에러는 RFC 7807 Problem Details: 모든 400/401/403/404/500 응답은 Content-Type: application/problem+json + 기계 판독 가능한 error_code (예: SKILL_MD_MISSING, CONTENT_TOO_LARGE, VETTING_JOB_NOT_FOUND). 에이전트는 정규식 매칭 없이 error_code 로 분기.

💡 제약: JSON content 모드는 총 크기 5MB, 파일 50개 이하. 바이너리는 base64_files 에 base64 인코딩하여 전달. 기존 multipart .skill 업로드 방식도 그대로 지원 (호환성 유지).

🤖 MCP 도구: upload_skill(api_key=..., skill_md=..., files={...}) + get_vetting_result(job_id=..., api_key=...) — MCP 호환 에이전트(Claude Desktop/Cursor/VS Code 등)는 디스크 접근 없이 바로 사용 가능.

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, Cursor, Gemini CLI, Codex CLI 패키지가 자동 생성됩니다.

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 파라미터로 필터링할 수 있습니다.

AI 에이전트가 AI Skill Store에서 스킬을 어떻게 찾나요?+

여러 경로로 찾을 수 있습니다: /v1/agent/search Agent API는 능력(capability), 플랫폼, 키워드로 검색을 지원합니다. MCP 호환 에이전트는 /.well-known/mcp/server-card.json으로 연결하고, Google A2A 에이전트는 /.well-known/agent.json을 사용합니다. /llms.txt는 모든 서비스의 기계 판독 가능한 개요를 제공합니다.

MCP 연동이란 무엇이고 어떻게 작동하나요?+

MCP(Model Context Protocol)를 사용하면 Claude Desktop, Cursor, VS Code 같은 에이전트가 AI Skill Store를 도구 서버로 연결할 수 있습니다. 에이전트가 직접 스킬을 검색하고, 스키마를 확인하고, 다운로드할 수 있습니다. 에이전트 설정에 MCP 서버를 추가하거나 /mcp/ 호스팅 엔드포인트를 사용하세요.

AI Skill Store는 어떤 플랫폼을 지원하나요?+

OpenClaw, Claude Code, Claude Code Agent Skills, Cursor, Gemini CLI, Codex CLI, CustomAgent 총 7개 플랫폼을 지원합니다. USK v3 자동 변환 조건을 충족하는 스킬은 업로드 시 모든 지원 플랫폼용으로 자동 패키징됩니다.

보안 검수(vetting) 과정은 어떻게 작동하나요?+

업로드된 모든 스킬은 악성 코드 패턴, 안전하지 않은 시스템 호출, 권한 위반을 검사하는 자동 보안 스캔을 거칩니다. 결과는 신뢰 등급으로 매핑됩니다: approved → verified, caution → community, flagged → sandbox. 이후 관리자 검토를 거쳐 최종 승인됩니다.

USK(Universal Skill Kit)란 무엇인가요?+

USK는 AI 에이전트 스킬을 패키징하기 위한 오픈 표준입니다. USK v3는 interface, input/output 스키마, capabilities, permissions를 포함하는 표준 SKILL.md 메타데이터 형식을 정의합니다. 이를 통해 하나의 스킬 패키지가 지원되는 모든 에이전트 플랫폼에서 자동 변환·실행됩니다.

AI Skill Store API를 인증 없이 사용할 수 있나요?+

네, 모든 읽기 엔드포인트는 공개되어 있으며 인증이 필요 없습니다. /v1/agent/search로 스킬 검색, /v1/skills/{id}로 상세 조회, /v1/agent/skills/{id}/download로 패키지 다운로드가 API 키 없이 가능합니다. 스킬 업로드만 API 키 인증이 필요합니다.