How to use the Honeycomb Tracing agent skill (honeycomb-tracing)

What the honeycomb-tracing skill makes the agent do

An agent skill is a folder of instructions and reference files that an AI agent loads when a request matches its description. This one covers Paperclip runs, requests and full CI suites in Honeycomb. Its job is to produce an inspectable waterfall (a timeline of timed steps called spans) tied to the actual run or CI attempt, explain which intervals dominate elapsed time, and suggest the smallest useful next experiment.

The skill also covers configuring opt-in OpenTelemetry and adding missing spans. It states that tracing alone does not authorize replaying tasks, changing credentials, or deploying instrumentation, so a diagnosis request stays a diagnosis request.

• Find the trace for a run UUID or CI attempt
• Read the timeline and separate serial time from parallel time
• Explain which intervals dominate elapsed time
• Suggest the smallest useful next experiment
• Design readable, foldable waterfalls and add missing spans when asked

Install the skill from a ZIP file

Download the honeycomb-tracing ZIP from this page and unzip it. Put the resulting folder in one of two places: ~/.claude/skills/ to make it available to you across projects, or the .claude/skills/ folder inside a specific project to make it available only there.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

The ZIP contains agents/openai.yaml, references/ci.md, references/runtime.md, references/trace-design.md and SKILL.md. SKILL.md is the entry point the agent reads first; the reference files are loaded for specific tasks.

Trigger the skill with natural requests

You do not need to type the skill name. The skill's description says it applies when you want to trace Paperclip runs, requests or full CI suites in Honeycomb, find traces, diagnose latency, design waterfalls, configure opt-in OpenTelemetry or add missing spans. Phrase your request around one of those tasks and include the identifier you have.

Give the agent the run UUID when you have it. The skill notes that a task identifier is not a run UUID, because one task can have several runs.

• Why was run 3f2a... slow before the model started? Use the Honeycomb trace.
• Which test files are delaying the full PR suite for PR #123?
• Diagnose the latency of this issue page load and tell me where the time goes.
• Add the missing spans for the workspace preparation step and show me where they belong.

Examples of a good investigation

A typical run investigation starts from the run UUID. The agent computes a 12-character correlation hash from that UUID with Node.js, filters Honeycomb to that hash and the service name, and groups by trace ID to find matching traces. It then opens each trace and reads span durations and parent-child relationships. The skill warns that a count-only query cannot establish durations or causes.

For CI, the skill exports recorded timing for one complete attempt rather than requiring application tracing settings or a run UUID. It asks the agent to record the run ID, attempt, tested revision and job list so the result can be checked later.

What you need before you start

The workflow depends on real run data, so the skill is not useful on its own. You need access to a Paperclip instance and a Honeycomb account, either through a signed-in browser or through an authorized query tool. The agent also needs Node.js available locally to compute the correlation hash, and a Paperclip repository checkout, because the skill points to docs and code paths inside it.

• Honeycomb access (signed-in browser UI or an authorized query tool)
• Node.js available locally
• A Paperclip repository checkout for the referenced docs and code
• The skill runs scripts and uses the network

Safety notes: scripts, network and secrets

This skill runs scripts and uses the network. The correlation step runs a local Node.js command, and queries go to Honeycomb. The skill tells the agent to read only the secret fields it needs, never to dump a secrets file, and to keep secret values out of commands, artifacts, repository files and reports.

Do not paste API keys into the chat. The skill's warning reduces the risk but does not remove it if secrets are handled carelessly. The skill also says that when queries are unavailable, the agent should use the signed-in UI rather than create a new key or upgrade permissions.

• Keep API keys out of prompts and commands
• Expect the agent to avoid replaying tasks or deploying instrumentation during a diagnosis
• Verify the Honeycomb destination before comparing data, because defaults in the code are not proof of every deployment's target

Tips for better results

Give the exact run UUID, the time window and the service name. The skill asks for the absolute UTC interval and recommends widening the default seven-day window for older runs. Say which boundary you want to improve, such as time to committed reply or time to browser paint, because the skill distinguishes these and measures to the boundary you choose.

Ask for the smallest useful next experiment if you want a plan rather than a full report.

• Provide the UTC time window for the run
• State the boundary you care about (commit, publish, or paint)
• Ask for diagnosis only if you do not want changes made