Agent skill

Pgo

Profile-guided optimization (PGO) for the pi binary. An agent skill from dimetron/pi-go.

MITAuto-check passed

Install Pgo

skills CLI

$ npx skills add dimetron/pi-go --skill pgo -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install dimetron/pi-go pgo --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/dimetron/pi-go.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.pi-go/skills/pgo .claude/skills/pgo && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "pgo" agent skill from https://github.com/dimetron/pi-go/tree/main/.pi-go/skills/pgo into .claude/skills/pgo/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pgo", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/dimetron/pi-go/tree/main/.pi-go/skills/pgo

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add dimetron/pi-go --skill pgo -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install dimetron/pi-go pgo --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/dimetron/pi-go.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.pi-go/skills/pgo .agents/skills/pgo && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "pgo" agent skill from https://github.com/dimetron/pi-go/tree/main/.pi-go/skills/pgo into .agents/skills/pgo/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pgo", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add dimetron/pi-go --skill pgo -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install dimetron/pi-go pgo --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/dimetron/pi-go.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.pi-go/skills/pgo .cursor/skills/pgo && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "pgo" agent skill from https://github.com/dimetron/pi-go/tree/main/.pi-go/skills/pgo into .cursor/skills/pgo/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pgo", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/dimetron/pi-go.git --path .pi-go/skills/pgo

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add dimetron/pi-go --skill pgo -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install dimetron/pi-go pgo --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/dimetron/pi-go.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.pi-go/skills/pgo .gemini/skills/pgo && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "pgo" agent skill from https://github.com/dimetron/pi-go/tree/main/.pi-go/skills/pgo into .gemini/skills/pgo/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pgo", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install dimetron/pi-go pgo

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add dimetron/pi-go --skill pgo -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/dimetron/pi-go.git skills-src && mkdir -p .github/skills && cp -r skills-src/.pi-go/skills/pgo .github/skills/pgo && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "pgo" agent skill from https://github.com/dimetron/pi-go/tree/main/.pi-go/skills/pgo into .github/skills/pgo/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pgo", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add dimetron/pi-go --skill pgo -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install dimetron/pi-go pgo --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/dimetron/pi-go.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.pi-go/skills/pgo .opencode/skills/pgo && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "pgo" agent skill from https://github.com/dimetron/pi-go/tree/main/.pi-go/skills/pgo into .opencode/skills/pgo/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "pgo", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: pgo
GitHub stars: 207
Token cost: ~1.4k tokens
SKILL.md length: 711 words
Files: 1
Skills in repo: 21
Repo updated: Oct 1, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Profile-guided optimization (PGO) for the pi binary. An agent skill from dimetron/pi-go.

Works in 5 steps: Builds the binary (make build). → Runs the eval-tools suite with… → Runs the TUI render benchmarks with… → …
Recording a new PGO profile (make record-pgo)
SKILL.md covers The core rule: the profile…, How pi-go records a profile, Building with PGO and Merging profiles, plus 3 more sections
Calls go and make

What it does

Pgo is an agent skill from dimetron/pi-go. Profile-guided optimization (PGO) for the pi binary. Use when recording a new PGO profile (make record-pgo), when a build behaves differently after a profile is added or removed, when default.pgo is missing or stale, or when asked to optimize the pi binary with a CPU profile. Covers the go.dev/doc/pgo workflow: collecting a representative CPU profile, merging profiles, and building with PGO via default.pgo in the main package directory.

Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

The repository describes itself as: Go implementation of AI coding agent. The licence is MIT.

When your agent uses it

Recording a new PGO profile (make record-pgo)
A build behaves differently after a profile is added
Default.pgo is missing
Asked to optimize the pi binary with a CPU profile

Example prompts

“/pgo”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

Builds the binary (make build).
Runs the eval-tools suite with PI_EVAL_CPU_PROFILE=tmp/pgo, so every
Runs the TUI render benchmarks with -cpuprofile tmp/pgo/render.pprof.
Merges all profiles into cmd/pi/default.pgo with
Cleans up the scratch profiles.

What it can do on your machine

Read from SKILL.md and the folder at commit 24d1f2b. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- go
- make
From the folder's file list and the shell code blocks in SKILL.md.
Network
Links to these hosts (documentation or services it may open):
- go.dev
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Pgo loads about 1.4k tokens when it runs. Until then it costs about 113 tokens; SKILL.md has 711 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~113
When it runs · the whole SKILL.md, loaded when a task matches: ~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from dimetron/pi-go at commit 24d1f2b, republished under its MIT licence (© dimetron). 711 words, ~1,392 tokens.

Download SKILL.mdSave it as .claude/skills/pgo/SKILL.md (or your agent's skills folder).

name: pgo
description: Profile-guided optimization (PGO) for the pi binary. Use when recording a new PGO profile (`make record-pgo`), when a build behaves differently after a profile is added or removed, when `default.pgo` is missing or stale, or when asked to optimize the pi binary with a CPU profile. Covers the go.dev/doc/pgo workflow: collecting a representative CPU profile, merging profiles, and building with PGO via `default.pgo` in the main package directory.

PGO — Profile-Guided Optimization

Source: go.dev/doc/pgo (authoritative).

PGO feeds a CPU pprof profile from representative runs of the application back into the compiler for the next build, which uses it to make more informed optimization decisions (e.g. more aggressive inlining of hot functions). As of Go 1.22, representative programs improve ~2–14%. The compiler expects a CPU pprof profile — exactly what runtime/pprof and net/http/pprof produce.

The core rule: the profile must be representative

A profile that is not representative of real behavior yields little or no gain. Microbenchmarks are bad PGO candidates — they exercise a small part of the program. Collect from a representative workload instead. For pi-go that means both of the binary's hot paths, not one:

The headless agent/tool loop — the tool-coverage eval suite: one pi --mode print scenario per tool family.
The TUI render loop — RenderMessages, collapseBlankLines, and matchLexer. A live profile attributed ~24% of CPU to the ansi.Strip call blankFast replaces; bubbletea calls View() once per token during streaming, so this is a first-class hot path. It is exercised by the render benchmarks, not by --mode print.

A profile from only one workload optimizes only one half of the program.

How pi-go records a profile

make record-pgo does the whole loop:

Builds the binary (make build).
Runs the eval-tools suite with PI_EVAL_CPU_PROFILE=tmp/pgo, so every scenario's pi --mode print writes a per-scenario CPU profile via the --cpuprofile flag.
Runs the TUI render benchmarks with -cpuprofile tmp/pgo/render.pprof.
Merges all profiles into cmd/pi/default.pgo with go tool pprof -proto.
Cleans up the scratch profiles.

go build auto-detects default.pgo in the main package directory (cmd/pi/) and enables PGO — no -pgo flag needed. So make build after a record-pgo is a PGO build.

Manual collection

For a one-off profile of a specific workload:

bash

pi --cpuprofile /tmp/pi.pprof --mode print "some representative prompt"

The --cpuprofile flag writes a runtime CPU profile for the process lifetime and flushes it on exit. It is a persistent flag, so it works on subcommands too (pi memory mine . --cpuprofile /tmp/mine.pprof).

Building with PGO

Default: go build detects cmd/pi/default.pgo and enables PGO (-pgo=auto).
Disable: go build -pgo=off.
Explicit path: go build -pgo=/tmp/foo.pprof ./cmd/pi. A path applies to all main packages in the invocation, so keep one profile per binary.

Merging profiles

bash

go tool pprof -proto a.pprof b.pprof > merged.pprof

The merge is a straight sum of samples regardless of wall duration, so when profiling a long-running server, keep all slices the same duration or longer slices dominate. For pi-go's per-scenario profiles this is not a concern — each scenario is a short, bounded run.

Show full SKILL.md (300 more words)Show less

Source and iterative stability

Go PGO is robust to skew between the profiled version and the version being built:

Source stability: samples are matched by line offsets within functions. Adding code outside a hot function, or moving a function to another file in the same package, does not break matching. Renaming a function, moving it to another package, or editing inside a hot function may lose some optimizations (graceful degradation).
Iterative stability: the compiler is conservative, so successive PGO builds do not oscillate. No two-stage canary build is required.

Consequence: collect a fresh profile regularly. Degradation accumulates slowly as code drifts from the profile, and new code paths get no PGO benefit until a new profile reflects them. After a large refactor that renames or moves many functions, re-record.

Guidelines

Re-record after meaningful code changes — a stale profile optimizes the old code shape. make record-pgo is the one-step refresh.
Never profile a microbenchmark for PGO; use the eval suite or a real workload.
Commit default.pgo — the docs recommend committing the profile so builds are reproducible and performant from a fresh clone. It is a build input, not scratch.
make clean removes cmd/pi/default.pgo — re-run make record-pgo after a clean if you want PGO back.
Verify PGO is on: go build -x ./cmd/pi 2>&1 | grep -i pgo shows the -pgo flag the toolchain passes. Or check the binary size / go version -m for the profile.
A non-representative profile should not make the program slower than no PGO — it just optimizes cold paths. If you see a real regression, file an issue at go.dev/issue/new.

Examples

/pgo — explain the PGO workflow and check whether default.pgo is current.
make record-pgo — record a fresh profile from the eval suite.
pi --cpuprofile /tmp/pi.pprof --mode print "..." — one-off manual profile.
go build -pgo=off ./cmd/pi — build without PGO to compare.

Files

Just SKILL.md in .pi-go/skills/pgo of dimetron/pi-go.

Open the folder on GitHubat commit 24d1f2b

Compare with similar skills

Pgo next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Pgo compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Pgo this skilldimetron/pi-go	207	—	~1.4k	Automated safety check: Pass	MIT	7 days ago
Recordingcodewhale-hq/Codewhale	41k	—	~540	Automated safety check: Pass	MIT	today
Profileccusage/ccusage	19k	—	~430	Automated safety check: Pass	Custom licence	today
Write Guidevercel/next.js	143k	—	~1.6k	Automated safety check: Pass	MIT	today
Cpu ProfileClickHouse/ClickHouse	50k	—	~1.9k	Automated safety check: Notes	Apache-2.0	today
Architecture Decision Recordsaffaan-m/ECC	275k	4 repos	~1.8k	Automated safety check: Pass	MIT	3 days ago

Similar skills

Recording
codewhale-hq/Codewhale
Capture screenshots on registered computers, record on macOS or HarmonyOS, and manage saved captures.
41k GitHub stars~540 tokensUpdated today
Productivity & AutomationAuto-check passed
Profile
ccusage/ccusage
Profiles ccusage performance. An agent skill from ccusage/ccusage.
19k GitHub stars~430 tokensUpdated today
Auto-check passed
Write Guide
vercel/next.js
Official
Generates technical guides that teach real-world use cases through progressive examples.
143k GitHub stars~1.6k tokensUpdated today
DevelopmentAuto-check passed
Cpu Profile
ClickHouse/ClickHouse
Profile a ClickHouse query using the sampling query profiler and system.tracelog.
50k GitHub stars~1.9k tokensUpdated today
DatabasesAuto-check: notes
Architecture Decision Records
affaan-m/ECC
Capture architectural decisions as numbered ADR markdown files in docs/adr/ with context, alternatives considered, consequences, and an index README.
275k GitHub starsUsed in 4 repos~1.8k tokens
DevelopmentAuto-check passed
Architecture Decision Records
affaan-m/ECC
在Claude Code会话期间，将做出的架构决策捕获为结构化的架构决策记录（ADR）。自动检测决策时刻，记录上下文、考虑的替代方案和理由。维护一个ADR日志，以便未来的开发人员理解代码库为何以当前方式构建。
275k GitHub starsUsed in 1 repo~863 tokens
DevelopmentAuto-check passed

Questions about Pgo

What does Pgo do?

Profile-guided optimization (PGO) for the pi binary. An agent skill from dimetron/pi-go. Pgo is an agent skill from dimetron/pi-go. Profile-guided optimization (PGO) for the pi binary.

When should I use Pgo?

Pgo fits situations like: recording a new PGO profile (make record-pgo); A build behaves differently after a profile is added; default.pgo is missing; asked to optimize the pi binary with a CPU profile.

How do I install Pgo in Claude Code?

Run `npx skills add dimetron/pi-go --skill pgo -a claude-code`. Or copy the skill folder (.pi-go/skills/pgo in dimetron/pi-go) into .claude/skills/pgo in your project. Claude Code loads it when a task matches its description.

How do I install Pgo in Codex?

Run `npx skills add dimetron/pi-go --skill pgo -a codex`. Or copy the skill folder (.pi-go/skills/pgo in dimetron/pi-go) into .agents/skills/pgo in your project. Codex loads it when a task matches its description.

Can I use Pgo in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add dimetron/pi-go --skill pgo -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/pgo, .gemini/skills/pgo, .github/skills/pgo and .opencode/skills/pgo in your project.

What does Pgo need to run?

Going by SKILL.md and its folder, Pgo needs the command-line tools its instructions call (go and make).

Does Pgo access the network?

SKILL.md names 1 domain. As links in the text: go.dev. This is read from the text; nothing was executed.

Is Pgo safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Pgo use?

Pgo is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Pgo use?

About 1.4k tokens (SKILL.md is roughly 5.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Pgo?

Skills that share tags, products or a category with Pgo: Recording (codewhale-hq/Codewhale, 41k stars), Profile (ccusage/ccusage, 19k stars), Write Guide (vercel/next.js, 143k stars) and Cpu Profile (ClickHouse/ClickHouse, 50k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Pgo?

dimetron (a GitHub user) maintains it in dimetron/pi-go, which has 207 GitHub stars. The repository holds 21 skills in this directory. The repository was last updated on October 1, 2026.

Source: dimetron/pi-go on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Pgo

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

PGO — Profile-Guided Optimization

The core rule: the profile must be representative

How pi-go records a profile

Manual collection

Building with PGO

Merging profiles

Source and iterative stability

Guidelines

Examples

Files

Compare with similar skills

Similar skills

More from dimetron/pi-go

Questions about Pgo