Index of every page on this site: llms.txt
All skills
posthog avatar

/establishing-code-ownership

@028173b official
by posthogposthog/posthog41k stars
3,718
Run it yourself

Determine which PostHog team owns a file, directory, or code path, or enumerate all code a team owns (via distributed `owners.yaml`, `products/*/product.yaml`, and `.github/CODEOWNERS`). Use when assigning a reviewer, attributing a bug or slow query to a team, routing work, scoping a team-wide audit, or answering "who owns X" / "what does team Y own".

Use this Skill: https://skilld.dev/gh/posthog/posthog/establishing-code-ownership

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈96 tokens for metadata: the name and description. ≈1.5k when used: this file.

Description uses 4.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈383 characters, or 4.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Establishing code ownership

Ownership is resolved by one tool — hogli owners:* — over distributed owners.yaml files. Don't re-parse the ownership files by hand; the resolver owns the semantics and is what CI enforces.

Fast path: hogli owners:*

Dev machines have flox/hogli, so shell straight to the resolver.

hogli owners:who posthog/hogql/printer.py    # who owns this path (+ the file that decided it)
hogli owners:resolve --json posthog/api/survey.py products/surveys/backend/api.py   # batch, JSON keyed by path
hogli owners:unowned                          # every tracked file with no owner (append a prefix to scope: `owners:unowned products/`)

owners:who prints the resolved owners, the status, the Slack channel, and source — the owners.yaml/product.yaml file that decided the answer. The channel comes from the root teams: registry entry for the primary owner, else a derived #<slug>; a path whose primary owner is an @handle has no channel. owners:resolve takes paths as arguments or newline-delimited on stdin, so you can pipe a file list: git ls-files posthog/hogql | hogli owners:resolve --json. No hogli/flox available? The dependency-light fallback needs only pyyaml: git ls-files posthog/hogql | PYTHONPATH=packages/owners-yaml python -m owners_yaml (stdin paths → the same JSON).

Resolution algorithm (what the resolver does)

For a path, it walks from the repo root down to the path collecting ownership files, then merges them nearest-file-wins:

  1. owners.yaml — the canonical, distributed source. Each directory can carry one. Fields (owners, status, inherit, per-path rules) fall through to the nearest ancestor unless overridden. inherit: false cuts the walk (Gerrit's set noparent) — nothing above it contributes. Within a file, every matching rule applies in order, and each replaces only the fields it sets. owners: null means unowned by design (exempt from the coverage check), distinct from a directory with no file at all (genuinely unowned). additions: names the owners of additions below a directory rather than the owners of the files in it (the consumer decides what counts as an addition); it never changes owners, and it adds up across the walk so a nested file cannot drop an ancestor's entry. sensitive: true marks paths where a small change matters (a CI baseline, an exemption list), so the reviewer assigner requests their owners for every change, whatever its size; it is nearest-wins like status, a product.yaml can set it too, and it never makes a review required.
  2. products/<name>/product.yaml — an accepted alias. The root owners.yaml enables this with alias_files: [product.yaml]. When a product dir has no owners.yaml, its product.yaml owners: list is read as the ownership for products/<name>/**, and its sensitive: flag applies to that tree too (every other product.yaml field is ignored). A dir with both files is a lint error; owners.yaml wins.
  3. .github/CODEOWNERS — blocking approvals, never part of the walk. It keeps GitHub-native semantics, stays hand-maintained (mostly infra, e.g. team-security), and is enforced by GitHub itself. The resolver does not read it — when you need to know whether a blocking approval is additionally required, consult the file directly. It never changes the resolved owners, and nothing here writes to it. A tool that can only read CODEOWNERS gets a generated projection of the map instead, from hogli owners:codeowners (see packages/owners-yaml/README.md); that projection covers test files and is never .github/CODEOWNERS.

Owners are a mixed list of team slugs (team-devex, conversations, logs — the GitHub team handle minus @PostHog/) and @handles for individuals; the first entry is the primary owner.

team → code (what does this team own?)

There's no single "team → files" command; resolve the tree and filter by slug:

git ls-files | hogli owners:resolve --json | jq -r 'to_entries[] | select(.value.owners | index("team-surveys")) | .key'

Also grep products/*/product.yaml for the slug — each hit is all of that products/<name>/**; one team often owns several, so don't stop at the first. Owned paths span backend and frontend/src/...; cover both, or say up front you're doing one side.

Generated files

A generated artifact often resolves to a broad parent owner or nobody. Trace it to the input it's generated from and report that team as the logical owner (e.g. services/mcp/src/tools/generated/<x>.ts comes from products/<name>/mcp/tools.yaml). Distinguish the logical owner (the team owning the source — the answer to report) from the literal resolver result on the generated path, and flag the gap so the operator can decide whether to pin it with a rules: entry.

Last resort: feature-ownership handbook, then Slack

If neither the resolver nor product.yaml resolves it, consult the feature-ownership handbook — coarse-grained (broad areas, not files) and hand-maintained, so prefer the repo files and flag any handbook-sourced answer as possibly stale. If even that fails and the Slack MCP is available, search Slack — least authoritative (opinions, stale threads), so verify against the repo files and flag the answer as Slack-sourced.

Slug vs handle

  • Handle (CODEOWNERS): @PostHog/<slug>, e.g. @PostHog/team-replay.
  • Slug (owners.yaml / product.yaml): handle minus @PostHog/, e.g. team-replay.
  • Not uniform: some carry team- (team-self-driving), some don't (conversations, logs). If a name doesn't resolve, try both forms.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill facilitates identifying code ownership within a repository using project-specific tools (hogli) and standard configuration files. It uses command-line operations for repository introspection, which align with its primary purpose.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at 028173b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month

README badge

README badge for posthog/posthog/establishing-code-ownership