Perfetto Skills

This directory holds skills: self-contained, model-agnostic instructions that teach an AI agent how to do something useful with Perfetto. Skills are how Perfetto and the teams that use it encode the knowledge an expert would share when sitting next to a colleague — what to look at, which tables to query, what good queries look like, and how to interpret the results.

The format follows the Agent Skills convention: each skill is a directory containing a SKILL.md with YAML frontmatter (name, description) and a markdown body. Any tool that implements the convention — Claude Code, Gemini CLI, OpenAI Codex — can load them.

This is the seed of a much larger skill ecosystem described in RFC-0025: AI in Perfetto. External teams will eventually contribute their own skills, either checked in here or served from extension servers.

Skills are designed to be copied

A skill is portable. It will be vendored into agent contexts (e.g. ~/.claude/skills/), pasted into other repos, and read by tools running without access to the Perfetto source tree. So:

• Never use repo-relative paths like src/trace_processor/... or docs/analysis/... — they don't resolve outside this checkout. Link to perfetto.dev instead.
• Don't refer to “this repo” or tools/... scripts — assume the reader only has a Perfetto build (trace_processor) and the trace.
• Keep the skill self-sufficient. If a skill needs a SQL helper or example, ship it inside the skill directory next to SKILL.md.

Layout

The directory is flat: every skill is a direct child of ai/skills/. This matches the discovery rules of every supported agent (<root>/<slug>/SKILL.md), so the same tree drops into ~/.claude/skills/, ~/.gemini/skills/, or ~/.agents/skills/ without any flattening step.

ai/skills/
├── README.md
├── perfetto_infra_querying_traces/
│   └── SKILL.md
├── perfetto_infra_getting_trace_processor/
│   └── SKILL.md
└── perfetto_workflow_android_heap_dump/
    └── SKILL.md

The slug doubles as the taxonomy: perfetto_ is the vendor prefix (so Perfetto skills don't collide with anything else the user has installed), then a category, then any sub-categories, then the skill name. Two categories today:

• perfetto_infra_* — domain-agnostic mechanics of working with Perfetto: how to query a trace, how to install the binary, etc.
• perfetto_workflow_<domain>_* — domain-specific investigation workflows: how to investigate a heap dump on Android, jank on Chrome, etc.

A workflow skill uses infra skills — it tells the agent “you‘ll need to query the trace; here’s the bit specific to this problem.”

Authoring a skill

Create a directory under ai/skills/ whose name follows the perfetto_<category>_<name> pattern, with a SKILL.md inside:

---
name: perfetto-infra-querying-traces
description: Use when the user wants to load a Perfetto trace, run
  a SQL query against it, or discover which tables and columns are
  available. Covers trace_processor invocation and the PerfettoSQL
  standard library.
---

# Body of the skill, written for an AI agent to follow.

Guidelines:

• name must be the dashed version of the directory slug (e.g., perfetto-infra-querying-traces for the perfetto_infra_querying_traces directory). Agents key off the frontmatter name and discovery is a single level deep.
• description must clearly state when the skill should be invoked. The agent uses this line to decide whether the skill is relevant, so be specific about the trigger conditions, not just the topic.
• The body is regular markdown. Write it in the imperative (“run X”, “check Y”), the same way you would write a runbook.
• Always link to absolute URLs on perfetto.dev/docs, not repo-relative paths.
• Test your skill against a real trace before checking it in. Skills that have never been run end up with broken syntax and wrong column names.
• A skill directory can contain additional files (example scripts, reference SQL). Reference them from SKILL.md by relative path.
• Keep the body focused. If a skill grows past a couple of pages, split it.