BLUEPRINT

제4장: 스킬 디스크립터

4.1 개요

Skill Descriptor(스킬 디스크립터)는 프로토콜의 핵심 데이터 구조로, JSON 문서 형태로 존재하며 스킬의 메타데이터를 완전히 기술합니다. 스킬 제공자와 소비자 간의 계약으로 기능하며, 제공자는 Descriptor를 통해 스킬의 능력을 선언하고, 소비자는 Descriptor를 통해 스킬 호출 방법을 이해합니다.

4.2 완전한 필드 정의

필수 필드

필드	타입	설명
`protocol`	ProtocolVersion	프로토콜 버전 정보
`id`	string	스킬 고유 식별자
`name`	string	스킬 이름
`version`	string	스킬 버전(SemVer 형식)
`capability_type`	CapabilityType	능력 유형
`description`	string	스킬 설명
`provider`	object	스킬 제공자 정보
`endpoint`	InvocationEndpoint	호출 엔드포인트 설정
`inputs`	ParameterDefinition[]	입력 파라미터 정의
`output`	OutputDefinition	출력 형식 정의
`auth`	AuthConfig	인증 설정
`access`	AccessPolicy	접근 제어 정책

선택 필드

필드	타입	설명
`tags`	string[]	태그(검색 및 분류용)
`documentation_url`	string	스킬 문서 URL
`created_at`	string	생성 시간(ISO 8601)
`updated_at`	string	업데이트 시간(ISO 8601)

4.3 열거형 타입

CapabilityType(능력 유형)

["plugin", "api", "knowledge", "task"]

plugin: 임베드 가능한 기능 모듈
api: 원격 서비스 인터페이스
knowledge: 구조화된 지식 리소스
task: 인간 또는 iFay가 실행 가능한 태스크

AccessPolicy(접근 제어 정책)

["public", "restricted", "private"]

public: 공개. 누구나 발견 및 호출 가능
restricted: 제한. 발견 가능하지만 호출에는 인증 필요
private: 비공개. 인증 없이는 발견 불가

AuthType(인증 방식)

["api_key", "oauth2", "custom", "none"]

4.4 하위 구조 정의

ProtocolVersion(프로토콜 버전)

{
  "version": "1.0.0",
  "changelog_url": "https://example.com/changelog"
}

version(필수): SemVer 형식의 프로토콜 버전 번호
changelog_url(선택): 버전 변경 로그 URL

InvocationEndpoint(호출 엔드포인트)

{
  "url": "https://example.com/skills/translate/invoke",
  "method": "POST",
  "content_type": "application/json",
  "status_url": "https://example.com/skills/translate/status/{execution_id}",
  "result_url": "https://example.com/skills/translate/result/{execution_id}",
  "timeout_ms": 30000,
  "retry": {
    "max_attempts": 3,
    "backoff_ms": 1000
  }
}

ParameterDefinition(파라미터 정의)

{
  "name": "text",
  "type": "string",
  "description": "번역할 텍스트",
  "required": true,
  "default": null,
  "schema": { "minLength": 1, "maxLength": 10000 }
}

AuthConfig(인증 설정)

API Key 인증 예시:

{
  "type": "api_key",
  "description": "HTTP Header를 통해 API Key 전달",
  "header": "X-API-Key"
}

OAuth 2.0 인증 예시:

{
  "type": "oauth2",
  "oauth2": {
    "authorization_url": "https://example.com/oauth/authorize",
    "token_url": "https://example.com/oauth/token",
    "scopes": {
      "skill:invoke": "스킬 호출",
      "skill:read": "스킬 정보 읽기"
    }
  }
}

OutputDefinition(출력 형식 정의)

{
  "content_type": "application/json",
  "schema": {
    "type": "object",
    "properties": {
      "translated_text": { "type": "string" },
      "source_language": { "type": "string" },
      "target_language": { "type": "string" }
    }
  },
  "description": "번역 결과. 번역문과 언어 정보를 포함"
}

4.5 완전한 예시

다음은 번역 스킬의 완전한 Descriptor 예시입니다:

{
  "protocol": {
    "version": "1.0.0",
    "changelog_url": "https://skill-sharing.org/changelog"
  },
  "id": "com.example.translate-v1",
  "name": "Universal Translator",
  "version": "2.1.0",
  "capability_type": "api",
  "description": "100개 이상의 언어를 지원하는 고품질 텍스트 번역 서비스",
  "provider": {
    "name": "Example Corp",
    "url": "https://example.com",
    "contact": "skills@example.com"
  },
  "endpoint": {
    "url": "https://api.example.com/skills/translate/invoke",
    "method": "POST",
    "content_type": "application/json",
    "status_url": "https://api.example.com/skills/translate/status/{execution_id}",
    "result_url": "https://api.example.com/skills/translate/result/{execution_id}",
    "timeout_ms": 30000,
    "retry": {
      "max_attempts": 3,
      "backoff_ms": 1000
    }
  },
  "inputs": [
    {
      "name": "text",
      "type": "string",
      "description": "번역할 텍스트",
      "required": true,
      "schema": { "minLength": 1, "maxLength": 10000 }
    },
    {
      "name": "target_language",
      "type": "string",
      "description": "대상 언어 코드(ISO 639-1)",
      "required": true
    },
    {
      "name": "source_language",
      "type": "string",
      "description": "소스 언어 코드(비워두면 자동 감지)",
      "required": false,
      "default": "auto"
    }
  ],
  "output": {
    "content_type": "application/json",
    "schema": {
      "type": "object",
      "properties": {
        "translated_text": { "type": "string" },
        "source_language": { "type": "string" },
        "target_language": { "type": "string" },
        "confidence": { "type": "number" }
      }
    },
    "description": "번역 결과"
  },
  "auth": {
    "type": "api_key",
    "description": "X-API-Key header를 통해 키 전달",
    "header": "X-API-Key"
  },
  "access": "restricted",
  "tags": ["translation", "nlp", "multilingual"],
  "documentation_url": "https://docs.example.com/skills/translate",
  "created_at": "2025-01-15T08:00:00Z",
  "updated_at": "2025-03-20T14:30:00Z"
}