⚡

凤凰技能开发指南Skill phoenix-skill-development

这个技能用于指导如何开发、精炼和维护 AI 代理技能，包括创建新技能、更新现有技能、添加规则文件以及提高技能质量和一致性。关键词：AI技能开发、技能指南、规则文件、Phoenix工具、AI智能体。

AI智能体 1 次安装 2 次浏览 更新于 3/10/2026

name: 凤凰技能开发 description: 在 skills/ 目录中开发、精炼和维护技能。用于创建新技能、更新现有技能、添加规则文件或提高技能质量和一致性。 license: Apache-2.0 metadata: author: oss@arize.com version: “1.0.0” internal: true

技能开发

本指南用于在此存储库的 skills/ 目录中创建和精炼技能。技能是打包的指令，用于教 AI 代理如何使用 Phoenix 功能。

目录结构

skills/
  {skill-name}/           # kebab-case，前缀为 "phoenix-" 用于 Phoenix 功能
    SKILL.md              # 必需：技能定义和索引
    README.md             # 可选：面向人类的概述
    rules/                # 可选：详细规则文件
      {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

每个技能都需要一个 SKILL.md，带有 YAML frontmatter：

---
name: {skill-name}
description: {它做什么。何时使用。包括触发短语。}
license: Apache-2.0
metadata:
  author: oss@arize.com
  version: "1.0.0"
  languages: Python, TypeScript  # 如果语言无关，则省略
---

Frontmatter 规则：

  • name: kebab-case，匹配目录名
  • description: 第三人称，具体，包括触发术语
  • license: 总是 Apache-2.0
  • metadata.author: 使用 oss@arize.com 用于 Phoenix 技能
  • metadata.version: Semver 字符串 (例如，"1.0.0")
  • metadata.languages: 仅当技能有语言特定内容时包括
  • metadata.internal: 设置为 true 用于不打算公开列出的技能 (例如，在 .agents/skills/ 中的技能)。对于在 skills/ 中的公开技能，省略。

3. 结构化 SKILL.md 主体

SKILL.md 作为索引和入口点。代理首先读取此文件，并根据需要导航到规则文件。

必需部分：

部分 目的
标题 (# 名称) 技能名称，带有简短描述
快速参考 映射任务到规则文件的表格
规则类别 前缀模式的表格

可选部分 (根据相关包括)：

部分 目的
何时应用 触发场景
工作流程 通过规则的逐步路径
关键原则 核心决策指导
常见属性 参考表格
如何使用 导航指导
参考文献 外部文档和 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            # 好：扁平，带有前缀
  setup-typescript.md
  span-llm.md                # 好：无语言后缀 (语言无关)
  evaluators-code-python.md  # 好：前缀-主题-语言

5. 编写规则文件

标准结构

# 标题

此规则涵盖内容的简短描述。

## 元数据 (可选)

| 字段 | 值 |
| ----- | ----- |
| 优先级 | 1 (关键) |
| 设置时间 | 5 分钟 |

## 快速开始 / 基本模式

最小工作示例。

## 详细部分

带有示例的扩展内容。

## 另请参见

- `related-rule.md` — 简短描述
- [外部文档](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 的快速参考和规则类别中添加条目
  4. 在新文件的“另请参见”部分交叉引用相关规则

更新 SKILL.md

当向 SKILL.md 添加内容时，保持其为索引 — 将详细内容移动到规则文件。SKILL.md 应保持在 500 行以下。

提高一致性

精炼时修复的常见问题：

问题 修复
缺少元数据表格 添加优先级、设置时间，如果适用
不一致的标题 标准化到 ## 快速开始, ## 另请参见
内联代码转储 提取到规则文件，从 SKILL.md 链接
缺少交叉引用 添加 ## 另请参见 与相关规则
模糊描述 使 frontmatter 描述具体，带有触发术语

质量检查清单

SKILL.md

  • [ ] Frontmatter 具有所有必需字段 (name, description, license, metadata)
  • [ ] metadata.internal: true 为在 .agents/skills/ 中的技能设置；为在 skills/ 中的技能省略
  • [ ] 描述是第三人称，具体，包括触发术语
  • [ ] 快速参考表格映射任务到规则文件
  • [ ] 规则类别表格列出所有使用的前缀
  • [ ] 少于 500 行
  • [ ] 无属于规则文件的详细内容

规则文件

  • [ ] 遵循 {prefix}-{topic}[-{language}].md 命名
  • [ ] 具有清晰的 # 标题 和简短描述
  • [ ] 包括带有语言标签的工作代码示例
  • [ ] 在 ## 另请参见 中交叉引用相关规则
  • [ ] 使用一致的标题结构

整体技能

  • [ ] 扁平 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 的快速参考和规则类别表格中反映。

工作流程摘要

1. 规划范围 → 单个 SKILL.md 或 SKILL.md + rules/?
2. 创建目录: skills/{skill-name}/
3. 编写 SKILL.md，带有 frontmatter 和索引
4. 创建 rules/ 目录 (如果需要)
5. 编写规则文件，遵循命名约定
6. 更新 SKILL.md 索引以引用所有规则
7. 运行质量检查清单