Skills 入出力仕様設計

優れた Skill は、タスクを完了できるだけでなく、「何を受け取るか」「何を生み出すか」を明確に定義する必要があります。

適切な入出力仕様は、Skill が確実に動作するための基盤です。

なぜ入出力仕様を定義するのか

Skills は実際のユーザーリクエストを扱うため、入力形式はさまざまです。

明確な仕様がない Skill の場合、Claude が入力の意図を推測することになり、動作が不安定になります。

仕様は制限ではなく、Claude に明確な行動範囲を与え、曖昧さを減らし、出力の一貫性を高めるものです。

入力仕様の4つの要素

要素	説明	例
入力タイプ	ファイル、テキスト、URL、パラメータなど	ユーザーがアップロードした PDF ファイル
形式の要件	ファイル拡張子、エンコーディング、構造	.csv、UTF-8 エンコーディング、1行目がヘッダー
必須/任意	どの入力が必須か	ファイルパスは必須、列名は任意
デフォルトの動作	任意パラメータが指定されていない場合の処理方法	列名が指定されていない場合はすべての列を分析

SKILL.md で入力仕様を定義する

例

## 入力仕様

### 必須入力

- **データファイル**：ユーザーがアップロードした`.csv` 或 `.xlsx`ファイル
- エンコーディング：UTF-8（CSV）または標準の Excel 形式
- 1行目は列見出しである必要があります
- ファイルサイズは 50MB 以下

### 任意入力

- **対象列**：分析する列を指定します。デフォルトではすべての数値列を分析します
- **出力形式**：`table`（テーブル）または`text`（テキスト要約）、デフォルト`table`
- **精度**：小数部の桁数、デフォルト2 位

### 入力がない場合の処理

ファイルがアップロードされていない場合は、ユーザーに次のように伝えます：「分析する CSV または Excel ファイルをアップロードしてください。」
ファイル形式がサポートされていない場合は、ユーザーに伝え、サポートされている形式のリストを表示します。

出力仕様の3つの次元

次元1：出力内容

何を出力するかを明確に指定し、漏れや過剰な出力を防ぎます。

例

## 出力内容

分析完了後、以下の内容を提供します：

1. **統計サマリーテーブル**：各列の行数、平均値、最大/最小値、空値の数
2. **データ品質レポート**：検出された問題をリストアップ（例：空値が多すぎる、データ型の混在）
3. **ファイルパス**：出力ファイルを生成した場合は、ダウンロードパスを提供

次元2：出力形式

出力をどのような形式で表示するか、およびどこに保存するかを指定します。

出力先	形式	保存先
会話内で表示	Markdown テーブル、コードブロック	保存不要
ダウンロード可能なファイル	.xlsx、.pdf、.html	`/mnt/user-data/outputs/`
中間結果	JSON、CSV	`/home/claude/`（一時）

次元3：出力タイミング

いつ出力するかを指定します。一度にすべて出力するか、ステップごとに段階的に表示するかを指定します。

例

## 出力タイミング

1. **ファイル読み込み後**：ファイルの基本情報（行数、列数、サイズ）をすぐにユーザーに伝えます
2. **分析中**：分析にかかる時間が10秒を超える場合は、先に進捗通知を出力
3. **分析完了後**：完全な統計サマリーを出力
4. **ファイル生成後**：ファイルパスを表示し、present_files ツールを呼び出します

完全な入出力仕様の例

以下は、ドキュメント要約 Skill の完全な入出力仕様です：

例

---
name: doc-summarizer
description: >
ユーザーがアップロードしたドキュメントから要約を抽出します。PDF、Word（.docx）、プレーンテキストに対応しています。
ユーザーがドキュメントの内容を素早く把握したい、重要な情報を抽出したい、ドキュメントの要約を生成したい場合に使用します。
---

# ドキュメント要約器

## 入力仕様

### 必須
- ドキュメントファイル（.pdf、.docx または .txt）

### 任意
- **要約の長さ**：`short`（3文）/ `medium`（1段落）/ `long`（3段落）、デフォルト`medium`
- **言語**：出力言語。デフォルトは原文と同じ
- **重点方向**：例：「結論部分に重点を置く」、「数値データを抽出する」

### 異常処理
- ファイルが 10MB を超える場合：ファイルが大きすぎることをユーザーに伝え、分割してアップロードするよう提案
- 形式がサポートされていない場合：サポートされている形式をリストアップし、ユーザーに再アップロードを依頼
- ドキュメントが画像スキャンで文字を認識できない場合：処理できないことを伝え、OCR ツールでの前処理を提案

## 出力仕様

### 出力内容（順番に）
1. ドキュメントの基本情報：タイトル（ある場合）、ページ数、推定文字数
2. コア要約：ユーザーが指定した長さで出力
3. キーワード：5-8個のテーマキーワード

### 出力形式
- すべて会話内で Markdown 形式を使用して表示
ユーザーが明示的に保存を要求しない限り、追加ファイルは生成しない

### 出力例
---
**ドキュメント**：サンプル-annual-report.pdf（24ページ、約12,000 字）

**要約**：本レポートではサンプルの年間ビジネス実績を振り返り、ユーザー数は前年比で増加35%，
技術ドキュメントのカバレッジは98%。収入構造は多様化が進み、広告と会員収入の比率は横ばいです。

**キーワード**：年間レポート、ユーザー成長、技術ドキュメント、収入構造、多様化
---

スクリプトレベルの入出力取り決め

Skill にスクリプトが付属する場合、Claude が結果を解析しやすいよう、構造化された入出力形式として JSON を使用することをお勧めします。

例

# ファイルパス：scripts/summarize.py
# 標準化された JSON 入出力パターン

import json
import sys

def summarize(file_path: str, length: str = "medium") -> dict:
"""
ドキュメントの要約を実行

パラメータ：
file_path: ドキュメントパス（必須）
length: 要約の長さ、short/medium/long（任意、デフォルトは medium）

戻り値：
dict。status、data、または error フィールドを含む
"""
try:
# ドキュメント読み込みのシミュレーション
with open(file_path, "r", encoding="utf-8") as f:
content = f.read()

# 要約生成のシミュレーション
summary = content[:200] + "..." # 実際には本物の要約ロジックを呼び出すべき

return {
"status": "success",
"data": {
"word_count": len(content),
"summary": summary,
"length": length
}
}

except FileNotFoundError:
return {"status": "error", "error": f"ファイルが存在しません：{file_path}"}
except Exception as e:
return {"status": "error", "error": str(e)}

if __name__ == "__main__":
file_path = sys.argv[1] if len(sys.argv) > 1 else ""
length = sys.argv[2] if len(sys.argv) > 2 else "medium"

result = summarize(file_path, length)

# 統一された JSON を出力し、Claude が解析しやすくする
print(json.dumps(result, ensure_ascii=False, indent=2))

{
  "status": "success",
  "data": {
    "word_count": 12480,
    "summary": "サンプル 年度报告回顾了平台在过去一年的业务表现...",
    "length": "medium"
  }
}

スクリプトの出力形式として JSON を使用することで、Claude は自由テキストを推測して解釈する必要がなく、結果を安定して解析できます。

その他の拡張

Skills 応用

Skills 実践プロジェクト