phoenix-skill-development

技能开发

本指南介绍如何在此仓库的 skills/ 目录中创建和完善技能。技能是成套的指令，用于教 AI Agent 如何使用 Phoenix 功能。

目录结构

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 插桩和 span 类型	是（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 frontmatter 的 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
---

Frontmatter 规则：

• name：使用 kebab-case，并与目录名一致
• description：使用第三人称，描述具体，并包含触发词
• license：始终设为 Apache-2.0
• metadata.author：Phoenix 技能使用 [email protected]
• metadata.version：Semver 格式的字符串（例如 "1.0.0"）
• metadata.languages：仅在技能包含特定语言内容时填写
• metadata.internal：对于不面向公开展示的技能（例如 .agents/skills/ 中的技能），设为 true。对于 skills/ 中的公开技能，省略此项。

3. 编写 SKILL.md 正文

SKILL.md 充当索引和入口。Agent 会先读取此文件，并在需要时跳转到规则文件。

必需章节：

章节	用途
标题（# Name）	技能名称和简短描述
快速参考	将任务与规则文件对应的表格
规则类别	前缀模式表

可选章节（按需添加）：

章节	用途
何时应用	触发场景
工作流	按步骤说明如何使用规则
核心原则	核心决策指导
常见属性	参考表格
使用方法	导航指南
参考资料	外部文档和 API 链接

4. 组织规则文件

命名约定

模式： {prefix}-{topic}[-{language}].md

前缀类别（在不同技能间重复使用）：

前缀	用途	示例
setup-*	安装、配置	setup-python.md
fundamentals-*	核心概念、参考资料	fundamentals-overview.md
instrumentation-*	自动／手动设置	instrumentation-auto-python.md
span-*	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 引用外部文档
• 交叉引用最多一层（SKILL.md → 规则文件，不要规则 → 规则 → 规则）

优化现有技能

添加规则文件

1. 从上方的表格中选择合适的前缀（或新建一个）
2. 遵循命名约定：{prefix}-{topic}[-{language}].md
3. 在 SKILL.md 的 Quick Reference 和 Rule Categories 下添加条目
4. 在新文件的 “See Also” 部分交叉引用相关规则

更新 SKILL.md

向 SKILL.md 添加内容时，应将其保留为索引，并将详细内容移至规则文件。SKILL.md 应少于 500 行。

提高一致性

优化时需要修复的常见问题：

问题	修复方法
缺少元数据表	添加 Priority、Setup Time（如适用）
标题不一致	统一使用 ## Quick Start、## See Also
内联代码过多	提取到规则文件中，并从 SKILL.md 链接到这些文件
缺少交叉引用	添加包含相关规则的 ## See Also
描述含糊	在 frontmatter 中加入具体描述和触发词

质量检查清单

SKILL.md

• Frontmatter 包含所有必填字段（name、description、license、metadata）
• 对于 .agents/skills/ 中的技能，设置 metadata.internal: true；对于 skills/ 中的技能，则省略该字段
• 描述使用第三人称，具体明确，并包含触发词
• Quick Reference 表将任务映射到规则文件
• Rule Categories 表列出所有使用的前缀
• 少于 500 行
• 不包含应放在规则文件中的详细内容

规则文件

• 遵循 {prefix}-{topic}[-{language}].md 命名约定
• 包含清晰的 # 标题 和简短描述
• 包含带语言标签且可运行的代码示例
• 在 ## See Also 中交叉引用相关规则
• 使用一致的标题结构

整体技能

• rules/ 目录保持扁平（无子目录）
• 所有文件中的术语保持一致
• 按语言拆分的内容放入 -python.md / -typescript.md 文件
• 与语言无关的内容不使用语言后缀
• 不包含时效性信息（不含日期或版本注意事项）

反模式

在 SKILL.md 中放入过多内容。 SKILL.md 是索引。如果某个部分的内容超过约 30 行，请将其提取到规则文件中。

交叉引用链过深。 规则文件不应依赖阅读其他规则文件才能发挥作用。每条规则都应足够独立，可单独使用。

规则名称过于通用。 使用 evaluators-code-python.md，而不是 code-eval.md。使用前缀可通过 ls rules/{prefix}-* 查找文件。

在同一文件中混用多种语言。 除非内容确实与语言无关，否则应拆分为 -python.md 和 -typescript.md。

忘记更新 SKILL.md。 每个新增规则文件都必须反映在 SKILL.md 的 Quick Reference 和 Rule Categories 表中。

工作流摘要

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