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"
}