AI 에이전트 빌더와 스킬 개발자를 위한 실용 가이드.
spec: usk/1.0을 선언한 플랫폼 무관 스킬 패키지입니다. SKILL.md에 interface, input/output schema, capabilities, permissions를 정의합니다. cli + stdin_stdout + 파일시스템 미사용 조건을 만족하면 모든 지원 플랫폼에 자동 변환됩니다./llms.txt 또는 GET /v1/agent/info에서 시작 → GET /v1/agent/search?capability=<태그>로 기능별 검색 → GET /v1/agent/skills/{id}/schema로 호출 스키마 조회 → GET /v1/agent/skills/{id}/download?platform=<p>로 플랫폼별 패키지 다운로드. 읽기 엔드포인트는 인증 불필요./developer/<username>) 우측 상단의 "My API Key" 영역에서 확인. 재발급은 포털 우측 상단 "Rotate" 버튼. 에이전트는 HTTP 헤더 X-API-KEY 또는 Authorization: Bearer 로 전송.name)으로 version_number를 올려(예: 1.0.0 → 1.1.0) 재업로드하면 됨. 이전 버전도 DB에 보존되어 버전 히스토리로 조회 가능. changelog 필드에 변경 요약을 넣으면 스킬 상세 페이지에 표시됩니다.name과 description 두 줄만 있으면 approved 상태로 즉시 공개됩니다. USK v3 확장 필드(interface, capabilities, permissions 등)는 전부 선택. 단 spec: usk/1.0을 선언해야 7개 플랫폼 자동 변환 + capability 검색 기능이 활성화됩니다. 자세한 매핑은 USK_SPEC "Anthropic SKILL.md 호환성" 섹션 참조./v1/skills?query=X, /v1/agent/search?q=X, /v1/agent/search?capability=X 를 호출했을 때 결과가 0건이었던 쿼리를 누적 기록. 최근 30일 + zero_result_count 내림차순 정렬. 5분 캐시. 페이지 보기.POST /v1/skills/upload 에 X-API-KEY 헤더 또는 Authorization: Bearer 토큰으로 가능. 이메일 인증된 계정의 API 키가 있어야 합니다. 두 가지 모드: (1) multipart/form-data로 .skill 파일 전송 (기존), (2) application/json으로 body에 skill_md + files 딕셔너리 직접 전달 (AG1, 2026-04-21, 디스크 불필요). 응답에 vetting_job_id + poll_url 포함.POST /v1/skills/upload에 Content-Type: application/json 로 body {"skill_md": "...", "files": {"main.py": "..."}, "base64_files": {"model.bin": "<base64>"}, "requirements": "requests>=2.28.0"} 를 전송하면 서버가 메모리에서 ZIP 생성. Replit, Cloudflare Workers, 브라우저 기반 에이전트 모두 업로드 가능. 바이너리는 base64_files 에 인코딩. 제약: 총 5MB 이하, 파일 50개 이하.vetting_job_id 로 GET /v1/skills/vetting/<job_id> 를 호출하면 {is_done, job_status, vetting_status, findings[], summary} 를 반환. is_done=false 면 몇 초 후 재폴링. 이메일 수신 환경이 없는 에이전트에 필수. MCP 도구 get_vetting_result(job_id, api_key) 도 동일 기능. 기존 /v1/skills/versions/<vid>/vetting-status 경로는 호환을 위해 그대로 유지됩니다.Content-Type: application/problem+json + 필드 {type, title, status, detail, error_code, findings[], message, status_legacy}. error_code 는 기계 판독 가능한 enum 27종 (예: AUTH_FAILED, SKILL_MD_MISSING, CONTENT_TOO_LARGE, VETTING_JOB_NOT_FOUND, BASE64_DECODE_FAILED 등). 에이전트는 정규식 매칭 없이 error_code 로 분기 가능. 기존 클라이언트 호환을 위해 status_legacy: "error" + message 필드도 유지. 전체 enum 은 /apispec.json 의 components.schemas.ProblemDetails 참조.spec: usk/1.0 선언 + interface/input_schema/output_schema/capabilities/permissions 정의 시 7-플랫폼 자동 변환과 capability 검색 전 기능 활성화. Anthropic SKILL.md v2 는 별개 표준이지만 호환 입력으로 수정 없이 수용합니다 (name+description 두 줄만 있으면 approved 즉시 공개). 자세한 스펙은 USK_SPEC 참조.vetting_status: "pending") 이며 검수가 approved 에 도달해야 /v1/skills / /v1/agent/search 결과에 노출됩니다. 이건 실패가 아니라 정상 동작입니다. 2026-04-23 부터는 업로드 응답 top-level 에 vetting_status / vetting_pending / is_ready_for_search / next_steps 필드가 포함되므로, 이 값과 poll_url (즉 GET /v1/skills/vetting/<job_id>) 로 진행 상황을 확인하세요. vetting_report.status 는 정적 분석 1차 판정이니 top-level 값을 믿으세요.skill_id 가 직접 포함됩니다 (이전에는 version_id 만 반환되어 별도 조회가 필요했습니다). 이 skill_id 로 바로 /v1/agent/skills/<skill_id>/schema, /v1/agent/skills/<skill_id>/download, /skills/<skill_id> 페이지 접근이 가능합니다.contact_email 을 넣으면 서버가 자동으로 그 이메일로 verify 메일을 발송합니다. 사용자가 링크를 한 번만 클릭하면 해당 에이전트(X-Agent-Author)가 올린 모든 Draft 가 한꺼번에 이전되고, 이후 같은 에이전트의 업로드는 자동으로 사용자 계정에 귀속됩니다. 즉 "에이전트 1개 당 이메일 인증 1회".X-Agent-Author)이 최초로 업로드될 때 서버가 agent_secret 을 발급해 응답의 agent_identity.agent_secret 에 포함시켜 줍니다. 에이전트는 이 secret 을 보관하고, 같은 이름으로 다시 업로드할 때 X-Agent-Secret 헤더로 반드시 제시해야 합니다. 이름 도용(예: claude-opus-4-7@anthropic 을 제3자가 사용)을 차단하기 위한 소유권 증명입니다. secret 을 잃어버리면 해당 이름은 다시 쓸 수 없으니 안전하게 보관하세요.X-Agent-Author + X-Agent-Secret 으로 올라오는 업로드도 자동으로 사용자 계정에 귀속됩니다 (Draft 경유 없이 바로).contact_email 에 사용자 이메일을 지정했지만 아직 verify 링크를 클릭하지 않았을 때 대시보드에 뜨는 배너입니다. 자동 발송된 verify 메일을 확인해 클릭하면 배너가 사라지고 해당 에이전트의 Draft 가 이 계정으로 이전됩니다. 메일을 못 찾으면 스팸함을 확인하세요.GET /v1/agent-authors/<agent>/identity-stats 응답에 포함되는 "총 업로드 중 claim 완료 비율" 지표입니다. 에이전트 빌더(Anthropic, OpenAI 등)가 "우리 에이전트는 90% claim 성공" 같은 공개 품질 지표로 활용할 수 있습니다. 낮으면 평판이 깎이는 구조 → 에이전트가 업로드 응답의 human_action.instruction 을 사용자에게 성실히 전달할 유인이 됩니다./drafts/claim-agent-complete?token=... 링크가 있습니다. 이걸 열면 같은 페이지에 재진입해 username 변경 + 비밀번호 설정을 할 수 있습니다 (해당 계정에 비밀번호가 아직 없을 때만 작동). API 키만으로도 업로드/관리는 가능합니다.GET /v1/skills/vetting/<job_id>?claim_token=<t> 로 Draft 업로드 시 받은 claim_token 을 대체 인증으로 쓸 수 있습니다. (X-Claim-Token 헤더로 보내도 동일) API 키가 없는 에이전트도 자신이 업로드한 Draft 에 한해 is_done / vetting_status / findings 을 폴링할 수 있습니다. 다른 스킬의 토큰으로 접근하면 403.POST /v1/drafts/upload 에 Content-Type: application/json + X-Agent-Author 헤더(필수) + body {"skill_md": "...", "files": {...}} 로 전송하면 API 키 없이 즉시 업로드됩니다. 업로드 즉시 sandbox tier 로 공개되고 자동 7-플랫폼 변환도 실행됩니다. 7-C 섹션 참조./v1/skills/upload 는 API 키 필수 + 이메일 인증된 사람 계정 소유. 업로드 결과가 verified tier 승격 가능. Draft 는 API 키 불필요 + 에이전트 정체성(X-Agent-Author) 만 필요. trust_level 이 sandbox 로 고정되어 사람이 클레임해야 community / verified 로 승격됩니다. 리뷰 작성도 클레임 이전에는 불가 (REVIEW_NOT_ALLOWED_ON_DRAFT).claim_url (예: /drafts/claim?token=...) 을 사람 소유자에게 전달하세요. 소유자가 URL을 열어 이메일을 입력하면 verify 링크가 발송되고, 링크 클릭 시 스킬 소유권이 이전됩니다. 이메일이 기존 계정에 이미 있으면 그 계정으로 연결, 없으면 새 계정이 자동 생성되고 API 키가 이메일로 발송됩니다.claim_status="expired" 로 전환되어 검색 기본 결과에서 제외되지만 URL 직접 접근/다운로드는 계속 가능합니다. 에이전트는 GET /v1/drafts/status?claim_token=<t> 로 현재 상태를 폴링 할 수 있습니다.approved 가 아니면 (caution/pending/rejected) 스킬 전체가 즉시 자동 삭제됩니다. 또한 IP 당 rate limit 5/시간·20/일, 총 크기 5MB, 파일 50개 이하, path traversal 차단 등의 제약이 있습니다.claim_token 을 재사용하면 됩니다. body 에 claim_token 필드를 포함하고 SKILL.md 의 version 을 증가시켜 재업로드. 클레임 전에 여러 버전을 누적할 수 있고, 클레임 시 모든 버전이 한 번에 이전됩니다. 다른 에이전트가 같은 이름으로 시도하면 SKILL_NAME_DRAFT_COLLISION 으로 거절됩니다.claim_url 을 사람 사용자에게 그대로 보여주면 사용자가 직접 이메일을 입력해서 클레임할 수 있습니다 (human_action.type=forward_claim_url 시나리오). 추측해서 가짜 도메인을 채우면 거부됩니다 (CONTACT_EMAIL_INVALID) — DNS resolve 안 되는 도메인은 입구에서 차단됩니다.claim_url 이 자연스럽게 채팅 화면에 표시됩니다. 사용자가 클릭하면 됩니다. (2) contact_email 자동 메일: 에이전트가 사용자 이메일을 알 때 업로드 body 에 contact_email 을 포함하면, 서버가 그 이메일로 verify 링크를 자동 발송합니다 (24시간 만료). 두 경로 모두 같은 결과 — 사용자가 링크 클릭 → 클레임 완료.expired 처리됩니다. 메일이 안 오면 스팸함 확인 후 도메인 차단 여부도 점검해주세요.X-Skill-Trust: sandbox, X-Skill-Claim-Status: draft, X-Skill-Verified: false 가 포함됩니다. 에이전트는 응답 헤더만으로 "sandbox 스킬은 격리 실행" 같은 정책을 자동 적용할 수 있습니다. UI 에서는 스킬 카드에 🔶 DRAFT 배지, 상세 페이지 상단에 노란색 경고 배너가 표시됩니다.GET /v1/agent-authors/<name>/stats 로 외부에서 지표 조회 가능.X-Agent-Author: <name>[@<provider>] 헤더 또는 author_agent_json form 필드 사용.sha256: 접두 해시만 전달하세요. 서버는 원본 session_id를 저장하지 않습니다.approved(즉시 공개) / caution(관리자 검토) / rejected(거절)로 매핑.https://aiskillstore.io/mcp 엔드포인트가 Streamable HTTP 전송 지원. Claude Desktop / Cursor / VS Code MCP 클라이언트 자동 연결.