Skills 使用指南

更新于 2026-08-24

PerfKitty Skills 将设备性能采集、云端报告分析和版本对比流程封装为 AI Agent 可以执行的标准工作流。安装后，你不需要记忆 PerfKitty CLI 命令或 MCP 工具参数，只需要用自然语言告诉 Agent 想测试或分析什么。

Skills 本身不会替代 PerfKitty 客户端、CLI 或 MCP。它们的作用是告诉 Agent 应该如何检查环境、选择设备和应用、调用工具，并根据真实数据组织分析结果。

1. 在哪里找到 Skills

安装 PerfKitty Windows 客户端后，打开 PerfKitty 安装目录下的 Skills 文件夹，可以看到以下压缩包：

Skills\
├── perfkitty-performance.zip
├── perfkitty-report-analysis.zip
└── perfkitty-local-collection.zip

无需从其他网站单独下载。根据需要选择一个压缩包，解压后再安装到所使用 Agent 的 Skills 目录。

请复制解压得到的整个 Skill 文件夹，不要只复制其中的 SKILL.md，也不要直接把 ZIP 文件放进 Agent 的 Skills 目录。Skill 文件夹内还包含 Agent 执行任务时需要读取的参考资料。

2. 三套 Skill 怎么选

Skill	适合场景	需要准备
`perfkitty-performance`	从连接设备、采集和上传到报告分析、问题定位及版本对比的完整流程	PerfKitty CLI；需要分析云端报告时还需配置 MCP
`perfkitty-report-analysis`	查找、分析或对比已经上传到 PerfKitty 云端的报告	PerfKitty MCP
`perfkitty-local-collection`	控制 Android 或 iOS 设备进行本地采集、保存、导出或上传	PerfKitty CLI

大多数用户建议安装 perfkitty-performance。 它覆盖本地采集和云端分析，可以完成从测试到结论输出的完整流程。

如果你的需求比较单一，可以只安装对应的 Skill：

已经有云端报告，只需要让 Agent 分析数据：安装 perfkitty-report-analysis。
只需要控制设备采集并保存本地文件：安装 perfkitty-local-collection。
同时需要采集、上传、诊断和版本对比：安装 perfkitty-performance。

三套 Skill 不需要全部安装。安装多个 Skill 时，Agent 会根据任务描述选择更匹配的工作流；如果希望固定使用某一个，也可以在指令中直接写出 Skill 名称。

3. 支持的 Agent

PerfKitty Skills 可用于：

Codex
Claude Code
OpenCode
其他支持 SKILL.md 格式的 Agent

不同 Agent 的 Skills 目录可能不同。升级或更换 Agent 后，请以该 Agent 当前版本的官方说明为准。

4. 安装方法

4.1 解压 Skill

打开 PerfKitty 安装目录下的 Skills 文件夹。
选择需要的 ZIP，例如 perfkitty-performance.zip。
解压 ZIP，得到同名文件夹 perfkitty-performance。
将整个文件夹复制到 Agent 的 Skills 目录。

安装完成后的目录应类似：

<Agent Skills 目录>\
└── perfkitty-performance\
    ├── SKILL.md
    ├── agents\
    └── references\

关键检查点是：SKILL.md 应直接位于 Skill 文件夹中。请避免解压成下面这样的重复嵌套目录：

perfkitty-performance\perfkitty-performance\SKILL.md

4.2 Codex

复制到：

~/.codex/skills/<skill-name>/

例如：

~/.codex/skills/perfkitty-performance/

在 Windows 中，~ 表示当前用户目录，通常也可以写成：

%USERPROFILE%\.codex\skills\perfkitty-performance\

4.3 Claude Code

个人使用时复制到：

~/.claude/skills/<skill-name>/

需要随项目共享时复制到：

<项目目录>/.claude/skills/<skill-name>/

4.4 OpenCode

个人使用时复制到：

~/.config/opencode/skills/<skill-name>/

需要随项目共享时复制到：

<项目目录>/.opencode/skills/<skill-name>/

4.5 重新加载 Agent

复制完成后，重新启动或重新加载 Agent，使其重新扫描 Skills 目录。然后可以输入：

你能使用哪些 PerfKitty Skills？请说明它们分别适合什么任务。

如果 Agent 能识别已安装的 Skill，并说明本地采集或报告分析能力，表示安装已经生效。

5. 配置本地性能采集

本节适用于：

perfkitty-performance
perfkitty-local-collection

开始前请确认：

已安装包含 PerfKitty.CLI.exe 的 PerfKitty Windows 客户端。
Android 或 iOS 设备已经通过 USB 连接到电脑。
Android 设备已经开启开发者选项和 USB 调试，并允许当前电脑调试。
iOS 设备已经信任当前电脑，且所需驱动和设备服务可正常工作。
需要登录时，由你根据 Agent 或 PerfKitty 的提示在浏览器中完成登录。

配置完成后，可以先让 Agent 检查环境：

检查 PerfKitty CLI 环境、登录状态和设备连接是否正常。

Agent 会根据实时命令结果检查环境并列出设备。存在多个设备或应用时，Agent 应先让你确认目标，而不是猜测设备 ID、包名或进程名。

你也可以直接发起采集任务：

用 PerfKitty 测试当前连接的 Android 手机上正在运行的应用，采集 60 秒并保存为 JSON，不要上传。

采集这个 iOS 应用 90 秒，并导出 Excel 文件。

本地采集当前面向 Android 和 iOS。实际可采指标取决于设备型号、操作系统、应用状态和当前采集能力。

6. 配置云端报告分析

本节适用于：

perfkitty-performance
perfkitty-report-analysis

云端分析需要先为 AI Agent 配置 PerfKitty MCP。推荐在 PerfKitty Windows 客户端中完成配置：

登录 PerfKitty 客户端。
打开客户端中的 MCP 配置入口。
选择需要接入的 AI 客户端和 MCP Key。
执行配置后，重新启动或重新加载对应的 Agent。

也可以按照 Agent 的 MCP 配置方式手动添加：

{
  "mcpServers": {
    "perfkitty-mcp-tools": {
      "url": "https://perfkitty.com/mcp",
      "headers": {
        "X-Mcp-Key": "你的 MCP Key"
      }
    }
  }
}

MCP Key 只应保存在 Agent 客户端配置中。不要把真实 Key 写入 Skill 文件、项目仓库、日志或聊天内容。

配置完成后，可以输入下面的指令进行验证：

列出我在 PerfKitty 中可以访问的项目和最近报告。

如果 Agent 能返回当前账号有权限访问的项目或报告，说明 MCP 已经连接成功。

7. 使用示例

7.1 完整采集与分析

适合使用 perfkitty-performance：

帮我测试这台 Android 手机上的前台游戏，采集 60 秒，上传后分析 FPS、CPU 和内存表现。

我刚优化了一个版本。请重新采集相同场景，并和上一次报告比较是否有性能退化。

测试这个 App 5 分钟，找出明显掉帧的时间段，并结合 CPU、GPU 和内存数据分析可能原因。

完整流程通常为：

检查环境 → 确认设备和应用 → 探测采集能力 → 采集 → 保存或上传 → 分析报告 → 输出结论

Agent 不应为了“更全面”擅自上传数据、开启连续截图或扩大采样范围。未指定采集时长时，Agent 可能建议使用一个有明确结束时间的测试时长，并在执行前说明。

7.2 分析已有云端报告

适合使用 perfkitty-report-analysis：

分析 PerfKitty 报告 <报告ID>，重点关注 FPS、CPU 和内存。

报告 <报告ID> 在第 30 秒附近为什么掉帧？请列出数据证据和判断置信度。

对比报告 <报告ID-A> 和 <报告ID-B>，判断新版本是否出现性能退化。

查找这个项目最近一周上传的 PerfKitty 报告，并列出设备、版本和测试时间。

不知道报告 ID 也没关系。可以告诉 Agent 项目名、包名、平台、设备、版本或大致测试时间，让它列出匹配的报告供你选择。

7.3 只进行本地采集

适合使用 perfkitty-local-collection：

列出当前连接的设备和设备上的应用。

采集当前应用 60 秒，保存成 PerfKitty JSON，不要上传。

采集 90 秒并导出 Excel 文件。

采集这个 Android 应用的指定子进程。

对于 Android 子进程采集，请提供或确认完整进程名。Agent 应从真实设备信息中选择目标，不能自行编造包名或进程名。

8. Agent 可以输出什么

根据 PerfKitty 实际返回的数据，Agent 可以提供：

设备、应用、采集时长和样本数量等执行结果；
FPS、Jank、CPU、GPU、内存等指标概览；
指标趋势、异常点和可疑时间窗口；
掉帧时段与其他指标变化之间的关联；
多份报告或多个版本之间的性能对比；
可能的性能问题原因及判断置信度；
当前数据不足以判断的内容和下一步复测建议。

Skill 要求 Agent 只引用 PerfKitty 返回的真实数据，并区分以下内容：

观测事实：报告中实际存在的数值、时间窗和设备信息。
分析推断：根据指标变化、相关性或规则得出的可能解释。
待验证假设：需要通过复测、源码分析或更详细诊断进一步确认的原因。

指标相关不等于因果关系。Agent 给出的根因通常是候选方向，不应被当作已经证明的源码级结论。

9. 常见问题

三套 Skill 都要安装吗？

不需要。大多数用户只安装 perfkitty-performance 即可；只需要云端分析或本地采集时，可以安装对应的单项 Skill。

安装后 Agent 没有识别到 Skill 怎么办？

依次检查：

是否已经解压 ZIP，而不是直接复制 ZIP 文件。
是否复制了整个 Skill 文件夹。
SKILL.md 是否直接位于 <Agent Skills 目录>/<skill-name>/ 下。
是否出现了两层同名文件夹。
是否已经重新启动或重新加载 Agent。
当前 Agent 版本是否支持 SKILL.md 格式。

Skill 为什么找不到 PerfKitty CLI？

确认已安装包含 PerfKitty.CLI.exe 的 PerfKitty Windows 客户端。如果 Agent 无法自动找到 CLI，可以把 PerfKitty 的实际安装位置告诉 Agent，但不要提供开发仓库或其他电脑上的示例路径。

本地采集后为什么没有云端分析？

云端分析需要把采集结果上传到 PerfKitty，并在 Agent 中配置 MCP。只想保留本地 JSON 或 Excel 文件时，不需要上传，也不需要配置 MCP。

找不到需要分析的报告怎么办？

告诉 Agent 项目名、包名、设备、平台、版本或测试时间。匹配到多个报告时，应先查看候选报告的元数据，再选择正确的报告。

MCP Key 和 PerfKitty 登录有什么区别？

PerfKitty 登录用于本地采集、上传和报告管理；MCP Key 用于授权 AI Agent 读取和分析当前账号有权限访问的云端数据。两者用途不同，请勿把密码或 MCP Key 直接发送给 Agent。

Agent 的分析结果可信吗？

Skill 会约束 Agent 使用 PerfKitty 返回的真实数据，并明确数据缺口和判断置信度。但性能根因仍可能受到测试场景、设备状态、样本时长和未采集指标影响。重要结论建议通过相同环境复测、版本对比和更详细的诊断数据进一步验证。

10. 更新 Skill

PerfKitty 客户端升级后，如果安装目录下的 Skill ZIP 有更新，请重新解压对应 ZIP，并用新文件夹替换 Agent Skills 目录中的旧版本，然后重新加载 Agent。

替换前如曾自行修改 Skill，建议先备份修改内容。不要把新旧版本文件混合复制，以免参考资料和 SKILL.md 版本不一致。