Agent skill

YugabyteDB ASH Instrumentation

by yugabyte in yugabyte/yugabyte-db

Procedure for adding or changing YugabyteDB Active Session History wait states in TServer and DocDB C++ code, including the macro to use for sync and async paths.

Custom licenceAuto-check passedDevelopment

Install YugabyteDB ASH Instrumentation

skills CLI
$ npx skills add yugabyte/yugabyte-db --skill ash-instrumentation -a claude-code

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

GitHub CLI
$ gh skill install yugabyte/yugabyte-db ash-instrumentation --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/yugabyte/yugabyte-db.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/ash-instrumentation .claude/skills/ash-instrumentation && 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/

Facts

Skill name
ash-instrumentation
GitHub stars
11k
Token cost
~4.5k tokens
SKILL.md length
2,045 words
Files
2
Skills in repo
7
Repo updated
First seen
Licence
Custom licence

At a glance

Procedure for adding or changing YugabyteDB Active Session History wait states in TServer and DocDB C++ code, including the macro to use for sync and async paths.

  • Works in 2 steps: Wait state is entered — wait_states-itest → Query id is correct — pg_ash-test…
  • Adding a new WaitStateCode to YugabyteDB
  • SKILL.md covers Mental model, Decision tree: which macro?, Add a new wait state (checklist) and Set the tablet id wherever…, plus 7 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Active Session History samples the wait state of every running RPC or task, meaning the resource it is blocked on. The skill covers TServer and DocDB C++ code under `src/yb` only, not PostgreSQL backend code, which has its own wait-event mechanism. Wait states are coarse on purpose: no spinlocks or mutexes, only condition variables, callbacks, IO, outgoing RPCs and row or transaction locks. Each `WaitStateCode` is tagged with a coarse `WaitStateType` such as `kCpu`, `kDiskIO`, `kRPCWait`, `kWaitOnCondition` or `kLock`, chosen by where it spends most time.

A decision table picks the macro from `src/yb/ash/wait_state.h`: `SCOPED_WAIT_STATUS` for synchronous waits that revert at scope end, `SET_WAIT_STATUS` or `SET_WAIT_STATUS_TO` for immediate settings, and `SCOPED_WAIT_STATUS_FOR_QUERY_ID` to choose between two events. Work handed to another thread or a callback must not use the scoped form, because the revert would clear the state too early. Codes are passed without the `k` prefix. The description adds registering background trackers, plumbing ASH metadata through RPCs and testing with `wait_states-itest`, and `reference.md` holds the code map.

When your agent uses it

  • Adding a new WaitStateCode to YugabyteDB
  • Instrumenting a blocking code path under src/yb for ASH
  • Handling a wait that completes in a callback or on another thread
  • Testing wait-state changes with wait_states-itest

Example prompts

  • “Add an ASH wait state for the flush wait in the tablet server and pick the right macro.”
  • “This callback-based RPC path loses its ASH state. Show me the correct async pattern.”
  • “Which WaitStateType should a new disk read wait use?”
  • “Write a wait_states-itest case for the new wait state.”

Requirements

  • A YugabyteDB source checkout with the C++ build environment

Workflow steps

2 steps, taken from the step headings in SKILL.md.

  1. Wait state is entered — wait_states-itest
  2. Query id is correct — pg_ash-test (REQUIRED for every new path)

What it can do on your machine

Read from SKILL.md and the folder at commit 4a1e3de. 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

    No scripts in the folder and no shell commands in SKILL.md (its code samples are cpp, bash and sql).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    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

YugabyteDB ASH Instrumentation loads about 4.5k tokens when it runs. Until then it costs about 97 tokens; SKILL.md has 2,045 words of instructions outside code blocks.

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

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

Its licence (Custom licence) doesn't allow us to republish the file, so here is its outline and opening line. It has 2,045 words (~4,547 tokens).

“Active Session History (ASH) samples, for every running RPC/task, the wait state it is currently in: what resource it is blocked on. This skill is the current, code-accurate procedure for adding or instrumenting wait states.”

— opening of SKILL.md by yugabyte, Custom licence
name
ash-instrumentation

Read the full SKILL.md on GitHub

Files

SKILL.md and 1 other file in .claude/skills/ash-instrumentation of yugabyte/yugabyte-db.

  • SKILL.md
  • reference.md

Open the folder on GitHubat commit 4a1e3de

Compare with similar skills

YugabyteDB ASH Instrumentation 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.

YugabyteDB ASH Instrumentation compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
YugabyteDB ASH Instrumentation this skillyugabyte/yugabyte-db11k—~4.5kAutomated safety check: PassCustom licence
Boost Asio Prosickn33/agentic-awesome-skills47k1 repos~3kAutomated safety check: PassMIT
Boost Asio Proalirezarezvani/claude-skills28k—~2.6kAutomated safety check: PassMIT
Rust Debuggingmohitmishra786/low-level-dev-skills252—~1.6kAutomated safety check: PassMIT
Replay Oriented InstrumentationArabelaTso/Skills-4-SE253—~2.5kAutomated safety check: PassApache-2.0
Python Script Integrationczyt1988/data-workbench102—~5.5kAutomated safety check: PassLGPL-3.0

Similar skills

  • Boost Asio Pro

    sickn33/agentic-awesome-skills

    A skill your agent uses when writing asynchronous C++ networking code with Boost.Asio or standalone Asio — TCP/UDP servers and clients, SSL/TLS, timers, strands, composed async ops.

    47k GitHub starsUsed in 1 repo~3k tokens
    DevelopmentAuto-check passed
  • Boost Asio Pro

    alirezarezvani/claude-skills

    A skill your agent uses when writing or reviewing asynchronous C++ networking code with Boost.Asio or standalone Asio — TCP/UDP servers and clients, SSL/TLS, timers, strands, iocontext, cospawn…

    28k GitHub stars~2.6k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Rust Debugging

    mohitmishra786/low-level-dev-skills

    Rust debugging skill for systems programming. An agent skill from mohitmishra786/low-level-dev-skills.

    252 GitHub stars~1.6k tokensUpdated 3 mo ago
    DevelopmentAuto-check passed
  • Replay Oriented Instrumentation

    ArabelaTso/Skills-4-SE

    Instruments programs to record execution information for deterministic replay debugging.

    253 GitHub stars~2.5k tokensUpdated 1 mo ago
    DevelopmentAuto-check passed
  • Python Script Integration

    czyt1988/data-workbench

    A skill your agent uses when integrating Python scripts with C++ in a DAWorkbench plugin — calling Python from C++, Python multithreading without UI conflicts, Python-to-C++ data exchange, Python UI…

    102 GitHub stars~5.5k tokensUpdated 28 days ago
    Data & AnalyticsAuto-check passed
  • Dt Obs Services

    Dynatrace/dynatrace-for-ai

    Service performance monitoring with RED metrics (Rate, Errors, Duration) and runtime-specific telemetry for Java, .NET, Node.js, Python, PHP, and Go.

    163 GitHub stars~3.3k tokensUpdated 9 days ago
    DevOps & CloudAuto-check passed

More from yugabyte/yugabyte-db

  • YugabyteDB Phorge Diff Creator

    yugabyte/yugabyte-db

    Creates a Phorge code review diff for the current branch with arc diff, while applying public-repo confidentiality rules since Phorge content later lands verbatim on the public GitHub repo.

    11k GitHub stars~3.1k tokensUpdated today
    Auto-check passed
  • YugabyteDB Issue Creator

    yugabyte/yugabyte-db

    Creates a GitHub issue or JIRA ticket for a YugabyteDB change or bug, after scrubbing customer data, secrets and unreleased details from anything public.

    11k GitHub stars~2k tokensUpdated today
    Auto-check passed
  • YugabyteDB Backport Review

    yugabyte/yugabyte-db

    Checks a YugabyteDB backport revision on Phorge against the original diff it was ported from and flags differences, tracing unexplained code back to master.

    11k GitHub stars~2.5k tokensUpdated today
    Auto-check passed
  • YBA Read-Only Query CLI

    yugabyte/yugabyte-db

    Runs read-only lookups - list, describe, get - against a live YugabyteDB Anywhere control plane using the yba CLI, with mutating commands explicitly off-limits.

    11k GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Create Fork Pull Request

    yugabyte/yugabyte-db

    Pushes the current branch to your fork and opens a cross-repository GitHub pull request, with a strict check against leaking customer data into public text.

    11k GitHub stars~5.6k tokensUpdated today
    Auto-check passed
  • cargo-pgrx Commands and Tests

    yugabyte/yugabyte-db

    Helps choose and run cargo-pgrx commands and decide whether a Rust test is a plain test or a pg_test, so code never crosses the Postgres boundary the wrong way.

    11k GitHub stars~1.9k tokensUpdated today
    Auto-check passed

Works with

Questions about YugabyteDB ASH Instrumentation

What does YugabyteDB ASH Instrumentation do?

Procedure for adding or changing YugabyteDB Active Session History wait states in TServer and DocDB C++ code, including the macro to use for sync and async paths. Active Session History samples the wait state of every running RPC or task, meaning the resource it is blocked on. The skill covers TServer and DocDB C++ code under `src/yb` only, not PostgreSQL backend code, which has its own wait-event mechanism.

When should I use YugabyteDB ASH Instrumentation?

YugabyteDB ASH Instrumentation fits situations like: adding a new WaitStateCode to YugabyteDB; instrumenting a blocking code path under src/yb for ASH; handling a wait that completes in a callback or on another thread; testing wait-state changes with wait_states-itest.

How do I install YugabyteDB ASH Instrumentation in Claude Code?

Run `npx skills add yugabyte/yugabyte-db --skill ash-instrumentation -a claude-code`. Or copy the skill folder (.claude/skills/ash-instrumentation in yugabyte/yugabyte-db) into .claude/skills/ash-instrumentation in your project. Claude Code loads it when a task matches its description.

How do I install YugabyteDB ASH Instrumentation in Codex?

Run `npx skills add yugabyte/yugabyte-db --skill ash-instrumentation -a codex`. Or copy the skill folder (.claude/skills/ash-instrumentation in yugabyte/yugabyte-db) into .agents/skills/ash-instrumentation in your project. Codex loads it when a task matches its description.

Can I use YugabyteDB ASH Instrumentation 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 yugabyte/yugabyte-db --skill ash-instrumentation -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/ash-instrumentation, .gemini/skills/ash-instrumentation, .github/skills/ash-instrumentation and .opencode/skills/ash-instrumentation in your project.

What does YugabyteDB ASH Instrumentation need to run?

SKILL.md names no scripts, command-line tools or credentials: YugabyteDB ASH Instrumentation is instructions for the agent only. Our summary lists: A YugabyteDB source checkout with the C++ build environment.

Does YugabyteDB ASH Instrumentation access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is YugabyteDB ASH Instrumentation 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 YugabyteDB ASH Instrumentation use?

YugabyteDB ASH Instrumentation has a licence file (the repository's licence) that doesn't match a standard licence. Read it on GitHub before reusing the skill.

How many tokens does YugabyteDB ASH Instrumentation use?

About 4.5k tokens (SKILL.md is roughly 18k 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 YugabyteDB ASH Instrumentation?

Skills that share tags, products or a category with YugabyteDB ASH Instrumentation: Boost Asio Pro (sickn33/agentic-awesome-skills, 47k stars), Boost Asio Pro (alirezarezvani/claude-skills, 28k stars), Rust Debugging (mohitmishra786/low-level-dev-skills, 252 stars) and Replay Oriented Instrumentation (ArabelaTso/Skills-4-SE, 253 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains YugabyteDB ASH Instrumentation?

yugabyte (a GitHub organization) maintains it in yugabyte/yugabyte-db, which has 10,586 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on October 10, 2026.

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