phoenix-skill-development

スキルの開発

このリポジトリの skills/ ディレクトリでスキルを作成し、改善するためのガイドです。スキルは、Phoenix の機能を使って作業する方法を AI エージェントに教えるためのパッケージ化された手順です。

ディレクトリ構成

skills/
  {skill-name}/           # kebab-case, prefixed with "phoenix-" for Phoenix features
    SKILL.md              # Required: skill definition and index
    README.md             # Optional: human-oriented overview
    rules/                # Optional: detailed rule files
      {prefix}-{topic}.md
      {prefix}-{topic}-{lang}.md

既存のスキル

スキル	目的	ルールの有無
phoenix-tracing	OpenInference のインストルメンテーションとスパンの種類	あり（31 ファイル）
phoenix-evals	評価器の開発と検証	あり（33 ファイル）
phoenix-cli	CLI のデバッグと分析	なし（単一の SKILL.md）

新しいスキルの作成

1. 範囲を計画する

スキルにルールファイルが必要かどうかを判断します。

• 単一の SKILL.md（phoenix-cli など）：自己完結型のトピック、コマンドリファレンス、単一ワークフローのツール
• SKILL.md + rules/（phoenix-tracing、phoenix-evals など）：言語固有のガイドを含む多面的なトピック、複数のワークフロー、または広範なリファレンス資料

2. SKILL.md を作成する

すべてのスキルに YAML フロントマターを含む SKILL.md が必要です。

---
name: {skill-name}
description: {What it does. When to use it. Include trigger phrases.}
license: Apache-2.0
metadata:
  author: [email protected]
  version: "1.0.0"
  languages: Python, TypeScript  # omit if language-agnostic
---

フロントマターのルール：

• name：ケバブケースを使用し、ディレクトリ名と一致させます
• description：三人称で具体的に記述し、トリガーとなる用語を含めます
• license：常に Apache-2.0 を指定します
• metadata.author：Phoenix のスキルでは [email protected] を使用します
• metadata.version：セマンティックバージョニング形式の文字列（例："1.0.0"）
• metadata.languages：スキルに言語固有のコンテンツがある場合にのみ含めます
• metadata.internal：公開リストへの掲載を意図しないスキル（例：.agents/skills/ 内のスキル）では true に設定します。skills/ 内の公開スキルでは省略します。

3. SKILL.md の本文を構成する

SKILL.md は索引とエントリーポイントとして機能します。エージェントは最初にこれを読み、必要に応じてルールファイルを参照します。

必須セクション：

セクション	目的
タイトル（# Name）	スキル名と簡単な説明
クイックリファレンス	タスクとルールファイルの対応表
ルールカテゴリ	接頭辞パターンの表

任意のセクション（必要に応じて追加）：

セクション	目的
適用するタイミング	トリガーとなる状況
ワークフロー	ルールに沿った手順
主要な原則	中核となる意思決定の指針
共通属性	リファレンス表
使用方法	ナビゲーションのガイダンス
参考資料	外部ドキュメントと API リンク

4. ルールファイルを整理する

命名規則

パターン： {prefix}-{topic}[-{language}].md

接頭辞カテゴリ（各スキルで共通して使用します）：

接頭辞	目的	例
setup-*	インストール、設定	setup-python.md
fundamentals-*	基本概念、リファレンス	fundamentals-overview.md
instrumentation-*	自動／手動の設定	instrumentation-auto-python.md
span-*	スパンの種類の仕様	span-llm.md
evaluators-*	評価器の種類、パターン	evaluators-code-python.md
experiments-*	データセット、実験の実行	experiments-running-typescript.md
production-*	デプロイ、モニタリング	production-python.md
annotations-*	フィードバック、スコアリング	annotations-overview.md
validation-*	キャリブレーション、テスト	validation-calibration-python.md

言語のサフィックス：

• -python.md — Python 固有のコンテンツ
• -typescript.md — TypeScript 固有のコンテンツ
• サフィックスなし — 言語に依存しない内容、または概要（例：span-llm.md、evaluators-overview.md）

概要ファイル： 概念の紹介には -overview.md サフィックスを使用します（例：fundamentals-overview.md、production-overview.md）。

フラット構成

すべてのルールファイルは rules/ 直下に配置し、サブディレクトリは作成しません。フォルダーではなく接頭辞を使って整理します。

rules/
  setup-python.md            # Good: flat with prefix
  setup-typescript.md
  span-llm.md                # Good: no language suffix (language-agnostic)
  evaluators-code-python.md  # Good: prefix-topic-language

5. ルールファイルを記述する

標準構成

# Title

Brief description of what this rule covers.

## Metadata (optional)

| Field | Value |
| ----- | ----- |
| Priority | 1 (Critical) |
| Setup Time | 5 minutes |

## Quick Start / Basic Pattern

Minimal working example.

## Detailed Sections

Expanded content with examples.

## See Also

- `related-rule.md` — Brief description
- [External docs](https://docs.arize.com/phoenix)

コード例

• 常に言語タグ付きのフェンスコードブロックを使用します：python、typescript、bash、json
• 動作し、そのままコピーして実行できる例を示します
• 該当する場合は、最小構成と本番環境向けのパターンを両方含めます

相互参照

• ファイル名で他のルールファイルを参照します：setup-python.md、span-llm.md
• 外部ドキュメントは完全な URL で参照します
• 参照は1段階にとどめます（SKILL.md → ルールファイルとし、ルール → ルール → ルールとはしません）

既存のスキルを改善する

ルールファイルを追加する

1. 上の表から適切なプレフィックスを選びます（または新たに設定します）
2. 命名規則 {prefix}-{topic}[-{language}].md に従います
3. SKILL.md の「クイックリファレンス」と「ルールカテゴリー」に項目を追加します
4. 新しいファイルの「関連項目」セクションで、関連するルールを相互参照します

SKILL.md を更新する

SKILL.md に内容を追加するときは、インデックスとしての役割を保ち、詳細な内容はルールファイルに移します。SKILL.md は500行未満にしてください。

一貫性を高める

改善時によくある問題と修正方法は次のとおりです。

問題	修正
メタデータテーブルがない	該当する場合は、優先度とセットアップ時間を追加します
見出しに一貫性がない	## Quick Start、## See Also に統一します
インラインコードが多すぎる	ルールファイルに切り出し、SKILL.md からリンクします
相互参照がない	関連するルールを記載した ## See Also を追加します
説明が曖昧	トリガー用語を含め、frontmatter の説明を具体的にします

品質チェックリスト

SKILL.md

• frontmatter に必須項目（name、description、license、metadata）がすべて含まれている
• .agents/skills/ 内のスキルでは metadata.internal: true が設定されており、skills/ 内のスキルでは省略されている
• 説明が三人称で具体的であり、トリガー用語が含まれている
• クイックリファレンステーブルでタスクとルールファイルが対応付けられている
• ルールカテゴリーのテーブルに、使用されているプレフィックスがすべて記載されている
• 500行未満である
• ルールファイルに含めるべき詳細な内容がない

ルールファイル

• {prefix}-{topic}[-{language}].md の命名規則に従っている
• 明確な # Title と簡潔な説明がある
• 言語タグ付きの動作するコード例が含まれている
• ## See Also で関連するルールを相互参照している
• 見出し構造に一貫性がある

スキル全体

• rules/ ディレクトリがフラットである（サブディレクトリがない）
• すべてのファイルで用語が統一されている
• 言語固有の内容が -python.md／-typescript.md ファイルに分割されている
• 言語に依存しない内容には言語サフィックスがない
• 時期に左右される情報（日時やバージョンに関する注意書き）がない

アンチパターン

SKILL.md に詰め込みすぎる。 SKILL.md はインデックスです。セクションの内容が約30行を超える場合は、ルールファイルに切り出してください。

参照が何段階にもなる。 ルールファイルは、役立てるために別のルールファイルを読む必要がないようにしてください。各ルールは、それぞれ独立して実行に移せる程度に自己完結させてください。

汎用的すぎるルール名。 code-eval.md ではなく、evaluators-code-python.md を使ってください。プレフィックスを使うと ls rules/{prefix}-* で見つけやすくなります。

1つのファイルで複数の言語を扱う。 内容が本当に言語に依存しない場合を除き、-python.md と -typescript.md に分割してください。

SKILL.md の更新を忘れる。 新しいルールファイルはすべて、SKILL.md のクイックリファレンスとルールカテゴリーのテーブルに反映してください。

ワークフローの概要

1. Plan scope → single SKILL.md or SKILL.md + rules/?
2. Create directory: skills/{skill-name}/
3. Write SKILL.md with frontmatter and index
4. Create rules/ directory (if needed)
5. Write rule files following naming conventions
6. Update SKILL.md index to reference all rules
7. Run quality checklist