Official agent skill

Adding Personhog Rpc

by PostHog in PostHog/posthog-foss

Guide for adding a new RPC to personhog-replica and personhog-router.

OfficialMITAuto-check passedBackend & APIs

Install Adding Personhog Rpc

skills CLI
$ npx skills add PostHog/posthog-foss --skill adding-personhog-rpc -a claude-code

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

GitHub CLI
$ gh skill install PostHog/posthog-foss adding-personhog-rpc --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/PostHog/posthog-foss.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/adding-personhog-rpc .claude/skills/adding-personhog-rpc && 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
adding-personhog-rpc
GitHub stars
721
Token cost
~2.1k tokens
SKILL.md length
871 words
Files
3 (incl. references)
Skills in repo
213
Repo updated
First seen
Licence
MIT

At a glance

Guide for adding a new RPC to personhog-replica and personhog-router.

  • Works in 5 steps: design the data access pattern → define proto messages and RPC → generate client stubs → …
  • Adding a new gRPC endpoint to personhog
  • SKILL.md covers Before you start: eligibility…, Step 0: design the data access…, Step 1: define proto messages… and Step 2: generate client stubs, plus 3 more sections
  • Calls cargo and pnpm

What it does

Adding Personhog Rpc is an agent skill from PostHog/posthog-foss, published by the product's own GitHub organization. Guide for adding a new RPC to personhog-replica and personhog-router. Covers eligibility checks, proto definition, code generation for Python and Node.js clients, Rust implementation (storage trait, postgres queries, service handler, router wiring), and index compatibility validation. Use when adding a new gRPC endpoint to personhog, migrating a Django ORM query to personhog, or extending the personhog service API.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including reference files (for example `references/database-indexes.md` and `references/proto-conventions.md`).

It sits in Backend & APIs, covering gRPC and Protobuf. It works with Rust, Python, Node.js and PostHog. The repository describes itself as: PostHog FOSS is a read-only mirror of PostHog, with all proprietary code removed. NOTE: This repo is synced automatically from the main PostHog repo. Please raise any issues and… The licence is MIT.

When your agent uses it

  • Adding a new gRPC endpoint to personhog
  • Migrating a Django ORM query to personhog
  • Extending the personhog service API

Example prompts

  • “/adding-personhog-rpc”

Requirements

  • Python 3
  • Node.js

Workflow steps

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

  1. design the data access pattern
  2. define proto messages and RPC
  3. generate client stubs
  4. implement in Rust
  5. verify

What it can do on your machine

Read from SKILL.md and the folder at commit 2c48221. 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:

    • cargo
    • pnpm

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

  • Network

    No URLs in SKILL.md. Its commands use pnpm, which can reach the network depending on how they are called.

    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

Adding Personhog Rpc loads about 2.1k tokens when it runs, and up to ~5.6k if it reads all its reference files. Until then it costs about 110 tokens; SKILL.md has 871 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~110
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~5.6k

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 PostHog/posthog-foss at commit 2c48221, republished under its MIT licence (© PostHog). 871 words, ~2,147 tokens.

Download SKILL.mdSave it as .claude/skills/adding-personhog-rpc/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
adding-personhog-rpc
description
Guide for adding a new RPC to personhog-replica and personhog-router. Covers eligibility checks, proto definition, code generation for Python and Node.js clients, Rust implementation (storage trait, postgres queries, service handler, router wiring), and index compatibility validation. Use when adding a new gRPC endpoint to personhog, migrating a Django ORM query to personhog, or extending the personhog service API.

Adding a personhog RPC

This skill walks through adding a new RPC end-to-end: proto definition, code generation, Rust implementation, and client updates.

Before you start: eligibility check

Personhog serves person, distinct ID, group, group type mapping, cohort membership, and feature flag hash key override data. If the data being accessed doesn't live in one of these tables, this RPC doesn't belong in personhog:

TableData categoryRouting
posthog_personPersonDataReads: replica (eventual) or leader (strong). Writes: leader
posthog_persondistinctidPersonDataSame as person
posthog_groupNonPersonDataAll ops: replica
posthog_grouptypemappingNonPersonDataAll ops: replica
posthog_cohortpeopleNonPersonDataAll ops: replica
posthog_featureflaghashkeyoverrideNonPersonDataAll ops: replica
posthog_personoverridePersonDataReads/writes follow person routing
posthog_personlessdistinctidPersonDataSame as person

If the table is not listed above, stop — this data should not go through personhog.

Step 0: design the data access pattern

Before writing any proto, figure out the SQL query you need. Then validate it against the available indexes — see references/database-indexes.md.

Key questions:

  • What table(s) does this query hit?
  • Does the WHERE clause match an existing index? Every query must be an index scan, never a sequential scan.
  • Is this a read or write? This determines routing (see table above).
  • For reads: does the caller need strong consistency (primary pool) or is eventual (replica pool) acceptable?
  • For batch lookups: is the batch within a single team or cross-team?

Step 1: define proto messages and RPC

All proto files live in proto/personhog/. See references/proto-conventions.md for message conventions and a worked example.

Where to add what
  1. Message types → proto/personhog/types/v1/<domain>.proto (person.proto, group.proto, cohort.proto, feature_flag.proto, or common.proto)
  2. Service RPC → proto/personhog/service/v1/service.proto (the public API clients call)
  3. Replica RPC → proto/personhog/replica/v1/replica.proto (the internal API the router delegates to)
  4. Leader RPC → proto/personhog/leader/v1/leader.proto (only if this is a person-data write routed to leader)

The service and replica protos must both declare the RPC with identical signature. The router delegates from service → replica (or leader) transparently.

Leader RPCs must be safe under at-least-once delivery

A leader-path request can be delivered more than once: clients retry UNAVAILABLE after ambiguous failures, and the router internally replays fence- and transport-bounced requests. Every leader RPC must therefore converge under redelivery — read-only lookups, merges that re-apply to the same state, tombstone-style deletes, max-merge version floors — or carry explicit operation identity so duplicates can be detected. Note the precise contract: a convergent merge still loses to interleaving (a replay can clobber a same-field write another caller made in between); that residual is accepted today and closes with operation identity (see personhog-leader's README). An RPC that neither converges nor carries identity (an unguarded increment, an append) must not be added. If the operation you need fits neither shape, redesign it to carry an idempotency key before defining the proto.

Step 2: generate client stubs

Python
bash
bin/generate_personhog_proto.sh

Then update three files:

  • posthog/personhog_client/proto/__init__.py — add re-exports for new request/response message types
  • posthog/personhog_client/client.py — add a wrapper method matching the pattern of existing methods
  • posthog/personhog_client/fake_client.py — implement the method for test use
Node.js
bash
cd nodejs && pnpm run generate:personhog-proto

Then update:

  • nodejs/src/common/personhog/groups.ts or persons.ts — add a wrapper method to the matching operations class (PersonHogGroupOperations / PersonHogPersonOperations), following the pattern of existing methods. client.ts only constructs and exposes these operation objects; it holds no RPC wrappers itself.
  • nodejs/src/common/personhog/client.test.ts — add a default stub to SERVICE_DEFAULTS for the new RPC
Show full SKILL.md (337 more words)Show less
Rust

No generation step needed — tonic regenerates on cargo build. But you must implement the RPC (next step), or the build will fail.

Step 3: implement in Rust

The compiler guides you — once the proto is defined, cargo build errors tell you exactly which trait methods are missing.

3a. Storage layer (personhog-replica)
  1. Add a trait method in rust/personhog-replica/src/storage/traits/<domain>.rs
  2. Implement the query in rust/personhog-replica/src/storage/postgres/<domain>.rs
    • Use sqlx::query_as! or sqlx::query! macros
    • Add timing instrumentation via DB_QUERY_DURATION and DB_ROWS_RETURNED metrics
    • Use self.replica_pool for reads, self.primary_pool for writes
    • Return early for empty batch inputs
  3. Add storage tests in rust/personhog-replica/tests/storage_tests.rs
3b. Service layer (personhog-replica)
  1. Add the RPC handler in rust/personhog-replica/src/service/mod.rs
    • Extract fields from the proto request
    • Call the storage trait method
    • Convert storage results to proto responses
    • Map storage errors to tonic Status codes
  2. Add service tests in rust/personhog-replica/tests/service_tests.rs
3c. Router wiring (personhog-router)

The router forwards request bytes without decoding them, so a new RPC needs no handler there.

  1. Add the method name to KNOWN_METHODS in rust/personhog-router/src/proxy.rs, keeping the list sorted
    • Methods that must reach the leader are matched by name in proxy.rs; everything else forwards to a replica
    • known_methods_is_sorted and known_methods_matches_service_proto in the same file fail until the list matches service.proto
  2. Add the method to every PersonHogService mock that implements the generated trait, including the ones outside personhog (rust/personhog-router/tests/common/mod.rs, rust/property-defs-rs/tests/); tonic traits have no default methods

Use rstest parameterized tests where multiple variations of the same behavior are being tested.

Step 4: verify

bash
cargo build -p personhog-proto
cargo build -p personhog-replica
cargo build -p personhog-router
cargo test -p personhog-replica
cargo test -p personhog-router

Checklist

  • Query uses an existing index (no seq scans)
  • Proto messages added to types/v1/<domain>.proto
  • RPC added to both service.proto and replica.proto (and leader.proto if needed)
  • Leader RPCs only: operation is safe under at-least-once delivery (convergent under redelivery — read-only, re-appliable merge, tombstone, max-merge — or carries explicit operation identity)
  • Python stubs generated, proto/__init__.py updated, client.py method added, fake_client.py updated
  • Node.js stubs generated, client.test.ts SERVICE_DEFAULTS updated
  • Rust storage trait + postgres impl + service handler + router wiring all implemented
  • Tests added at storage, service, and router layers
  • cargo build and cargo test pass for all three crates

© PostHog, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in .agents/skills/adding-personhog-rpc of PostHog/posthog-foss.

  • SKILL.md
  • references/database-indexes.md
  • references/proto-conventions.md

Open the folder on GitHubat commit 2c48221

Compare with similar skills

Adding Personhog Rpc 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.

Adding Personhog Rpc compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Adding Personhog Rpc this skillPostHog/posthog-foss721—~2.1kAutomated safety check: PassMIT
Databricks Zerobus Ingestdatabricks/databricks-agent-skills345—~3.1kAutomated safety check: PassCustom licence
Doca Flow Grpc ServerNVIDIA/skills3.5k—~4.2kAutomated safety check: PassApache-2.0
Maintain Dynamic PluginsNVIDIA/NeMo-Relay190—~1.2kAutomated safety check: PassApache-2.0
Regenerate Grpc StubsGetBindu/Bindu10k—~810Automated safety check: PassCustom licence
Spider Kingaoyunyang/spider-king-skill507—~7.3kAutomated safety check: PassMIT

Similar skills

  • Databricks Zerobus Ingest

    databricks/databricks-agent-skills

    Official

    Build Zerobus Ingest clients for near real-time data ingestion into Databricks Delta tables via gRPC.

    345 GitHub stars~3.1k tokensUpdated yesterday
    Backend & APIsAuto-check passed
  • Official

    PLAINTEXT-ONLY: the shipped docaflowgrpc server uses grpc::InsecureServerCredentials() with NO TLS / mTLS / token-auth knob on the binary — transport security must come from external infrastructure…

    3.5k GitHub stars~4.2k tokensUpdated today
    Backend & APIsAuto-check passed
  • Maintain Dynamic Plugins

    NVIDIA/NeMo-Relay

    Official

    Change NeMo Relay dynamic plugin loaders, manifests, native ABI, gRPC worker protocol, or Python worker SDK.

    190 GitHub stars~1.2k tokensUpdated today
    Backend & APIsAuto-check passed
  • Regenerate Grpc Stubs

    GetBindu/Bindu

    Regenerate Python + TypeScript gRPC stubs after editing proto files.

    10k GitHub stars~810 tokensUpdated 1 mo ago
    Backend & APIsAuto-check passed
  • Spider King

    aoyunyang/spider-king-skill

    Pure-web protocol reverse skill: turn hostile browser clients into browser-free Python collectors.

    507 GitHub stars~7.3k tokensUpdated 1 mo ago
    Backend & APIsAuto-check passed
  • Compile

    apache/skywalking-nodejs

    Compile / build / type-check the skywalking-nodejs agent. An agent skill from apache/skywalking-nodejs.

    180 GitHub stars~1.3k tokensUpdated 21 days ago
    Backend & APIsAuto-check passed

More from PostHog/posthog-foss

All 213 skills in this repo
  • Authoring Log Alerts

    PostHog/posthog-foss

    Official

    Author useful, low-noise log alerts on services in a PostHog project.

    721 GitHub stars~3k tokensUpdated today
    Auto-check passed
  • Autoresolving PR Conflicts

    PostHog/posthog-foss

    Official

    Operating procedure for the conflict-autoresolver agent: sweep open PostHog/posthog PRs that conflict with master, resolve the trivial conflicts (generated artifacts deterministically, source…

    721 GitHub stars~4.2k tokensUpdated today
    Auto-check passed
  • Official

    Help users debug PostHog Error Tracking stack-trace symbolication for any supported platform — JavaScript/TypeScript web, React Native (Hermes), Android (Proguard / R8), or iOS / macOS (dSYM).

    721 GitHub stars~2.2k tokensUpdated today
    Auto-check passed
  • Exploring Apm Traces

    PostHog/posthog-foss

    Official

    Investigates distributed application performance using PostHog APM (OpenTelemetry span) data via MCP.

    721 GitHub stars~3.5k tokensUpdated today
    Auto-check passed
  • Exploring LLM Traces

    PostHog/posthog-foss

    Official

    Debug and inspect LLM/AI agent traces using PostHog's MCP tools.

    721 GitHub stars~4.4k tokensUpdated today
    Auto-check passed
  • Investigate Metric

    PostHog/posthog-foss

    Official

    Diagnose why a product metric changed (dropped, spiked, or plateaued) by orchestrating breakdowns, actors, paths, lifecycle, retention, and annotations queries.

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

Categories

Questions about Adding Personhog Rpc

What does Adding Personhog Rpc do?

Guide for adding a new RPC to personhog-replica and personhog-router. Adding Personhog Rpc is an agent skill from PostHog/posthog-foss, published by the product's own GitHub organization. Guide for adding a new RPC to personhog-replica and personhog-router.

When should I use Adding Personhog Rpc?

Adding Personhog Rpc fits situations like: adding a new gRPC endpoint to personhog; migrating a Django ORM query to personhog; extending the personhog service API.

How do I install Adding Personhog Rpc in Claude Code?

Run `npx skills add PostHog/posthog-foss --skill adding-personhog-rpc -a claude-code`. Or copy the skill folder (.agents/skills/adding-personhog-rpc in PostHog/posthog-foss) into .claude/skills/adding-personhog-rpc in your project. Claude Code loads it when a task matches its description.

How do I install Adding Personhog Rpc in Codex?

Run `npx skills add PostHog/posthog-foss --skill adding-personhog-rpc -a codex`. Or copy the skill folder (.agents/skills/adding-personhog-rpc in PostHog/posthog-foss) into .agents/skills/adding-personhog-rpc in your project. Codex loads it when a task matches its description.

Can I use Adding Personhog Rpc 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 PostHog/posthog-foss --skill adding-personhog-rpc -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/adding-personhog-rpc, .gemini/skills/adding-personhog-rpc, .github/skills/adding-personhog-rpc and .opencode/skills/adding-personhog-rpc in your project.

What does Adding Personhog Rpc need to run?

Going by SKILL.md and its folder, Adding Personhog Rpc needs the command-line tools its instructions call (cargo and pnpm). Our summary lists: Python 3; Node.js.

Does Adding Personhog Rpc 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 Adding Personhog Rpc 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 Adding Personhog Rpc use?

Adding Personhog Rpc 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 Adding Personhog Rpc use?

About 2.1k tokens (SKILL.md is roughly 8.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 3.5k tokens, read only when the agent opens those files.

What are the alternatives to Adding Personhog Rpc?

Skills that share tags, products or a category with Adding Personhog Rpc: Databricks Zerobus Ingest (databricks/databricks-agent-skills, 345 stars), Doca Flow Grpc Server (NVIDIA/skills, 3.5k stars), Maintain Dynamic Plugins (NVIDIA/NeMo-Relay, 190 stars) and Regenerate Grpc Stubs (GetBindu/Bindu, 10k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Adding Personhog Rpc?

PostHog (a GitHub organization, an official publisher) maintains it in PostHog/posthog-foss, which has 721 GitHub stars. The repository holds 213 skills in this directory. The repository was last updated on October 7, 2026.

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