personio-eng-common

Engineering-focused skills shared across Personio engineering teams.

Installation

claude plugin install personio-eng-common@personio-claude-code-marketplace

What does this plugin do?

Provides engineering skills shared across all Personio engineering teams — cross-stack workflows that apply regardless of whether you work in Kotlin, monolith, or frontend. Covers customer data access via the data-access CLI, observability and troubleshooting (Datadog via MCP with pup fallback, SOPS.md runbooks), EDM workflows in the Data Registry, and sharing snippets as internal gists (pgist).

Skills

`edm-create-entity`

Guide for adding a new .proto schema file to the Personio Data Registry, formally registering a business concept as a tracked EDM (Entity Data Model) type. Covers greenfield proto definitions and migrating existing service models to EDM. Fetches the canonical creation guide from the internal developer portal at runtime so the guidance stays in sync with the live docs.

What you need:

Checkout of the data-registry repo
make check and make jvm-code available locally

Quick Start:

In Claude Code, describe what you want to model:

"Create a new EDM entity for absence management"

Claude will ask a few clarifying questions (domain, entity name, new vs migration, follow-up plans), fetch the authoritative creation guide from the developer portal, and walk you through writing and validating the proto files.

Why would you want this?

Stay in sync with the canonical EDM docs without tab-switching
Skip the guesswork on directory layout, stability annotations, and linting rules
Get a single handoff path for follow-ups (gRPC services, ECST events, sealed GraphQL operations) once the entity exists

`edm-create-sealed-operation`

Guides you through authoring a new sealed GraphQL operation (query or mutation) — or a new version of an existing one — in the Personio Data Registry, so it can be generated into hooks and consumed by personio-web via Gofer. Asks which EDM entities and fields the operation should cover and crafts the operation from that intent; pasting an operation drafted in GraphiQL is also accepted. Fetches the canonical how-to, style guide, and directives docs from the developer portal at runtime.

What you need:

Checkout of the data-registry repo
The target product area name as it exists in personio-web

Quick Start:

"I need a sealed query that fetches pending time-off requests from the absence service"

Claude will fetch the sealed-operations docs, ask which fields to include, draft the operation, compute the versioned name, and write the .query or .mutation file to the correct location under src/graphql/.

Why would you want this?

Keep the naming convention and file layout right without memorising them
Get directive usage (caching, timeout, filterOutWhenNullOrEmpty, fetchAll) only when the operation actually needs it, grounded in the live directives doc
Preserve the immutability rule — changes to an existing operation are new versioned files, not in-place edits

`edm-adopt-state-transfer-events`

Guides through adopting EDM State Transfer Events — legacy name ECST (event-carried state transfer) — for an existing EDM entity, so the entity's create/update/delete changes are emitted as Kafka events that derived stores (Analytics/Reporting, IDS, Global Search, the data warehouse) can consume. Spans both the data-registry side and the Kotlin service side. Fetches the canonical adoption how-to and events reference docs from the developer portal at runtime.

What you need:

An EDM entity already modelled in data-registry (use edm-create-entity first otherwise)
A Kotlin service — adoption relies on the Personio Framework's JVM-only edm-event-producer library

Quick Start:

"Enable ECST events for the Book entity in the book-service"

(Or, using the canonical name: "Adopt EDM State Transfer Events for the Book entity".)

Claude will check the prerequisites, fetch the canonical adoption doc, help authoring the metadata in the proto, generate the connector manifests, then walk through the Kotlin service-side integration.

Why would you want this?

Skip the tab-dance between the adoption how-to, events reference, and backfill docs
Avoid agents coming up with their own interpretation of the pattern

`find-data-registry-protos`

Points Claude at the canonical source for every Personio .proto schema and gRPC service definition — the data-registry repo — so it stops reverse-engineering schemas via curl/tar or web search. Checks $DATA_REGISTRY_HOME, $DATA_REGISTRY_DIR, ~/dev/data-registry, and the current directory tree for a local checkout; falls back to gh api fetches (with user consent) when no clone is present.

What you need:

gh authenticated against personio-internal/data-registry (for the fallback path)
Ideally, a local checkout at ~/dev/data-registry (the skill will offer to clone if missing)

Quick Start:

"Where is the proto definition for Employee?"

Claude will locate the local data-registry checkout (or prompt to clone one), navigate src/personio/proto/<domain>/, and surface the file directly.

Why would you want this?

Stop wasting cycles on curl/tar/web-search when the repo is the source of truth
Standardise the lookup path across the team — everyone's agent checks the same locations
Keep the repo's README.md, CLAUDE.md, and docs/ tree as the primary navigation for deeper questions

`enable-data-registry-ssi`

Set up, repair, or troubleshoot the data-registry local sourceset integration (SSI) in a Kotlin service. SSI lets you compile proto code directly from a local data-registry clone instead of fetching published artifacts — so edits to .proto files show up on the next ./gradlew compileKotlin without waiting for a release. The skill is idempotent: it checks current state at each step and skips what's already correct, making it equally useful for first-time setup and for debugging a broken SSI environment.

What you need:

A local clone of data-registry at ../data-registry relative to the project root (the default), or set dataRegistryDir in ~/.gradle/gradle.properties to point to your clone
Colima / Docker running locally
personio-framework ≥ 24.2.0+2026-06-09 in gradle/libs.versions.toml

Quick Start:

"Enable SSI for this repository"

"My compileKotlin fails with GC overhead limit exceeded after enabling SSI"

"I edited a proto in data-registry but my service isn't picking up the changes"

Claude will assess the current state (fresh setup, partial setup, or broken environment), output a plan tailored to what actually needs doing, and walk through each fix — version pin, BOM scope, convention call, include-path generation, and memory settings if needed.

Why would you want this?

Iterate on .proto changes locally without publishing a snapshot or bumping a version pin
Avoid the common SSI pitfalls (stale version pin, missing api BOM scope, OOM, stale data-registry-includes.conf) that otherwise take hours to diagnose
Get consistent setup across the team

`data-access`

Explore schemas and access customer data using the data-access CLI across SQL, gRPC, REST APIs, S3, and Kafka. Claude discovers the right tables, columns, services, and endpoints, then constructs the appropriate queries or service calls — using unlimited exploration commands before consuming your daily quota.

What you need:

data-access CLI installed and authenticated
A Jira ticket number (for most quota-consuming operations)

Quick Start:

# Just describe what you need - Claude figures out how to get it
"Show me the schema for the employees table"
"Find all employees for company ID 12345"
"What gRPC methods does user-service expose?"

Why would you want this?

Schema discovery: explore production database schemas without guessing table/column names
API exploration: discover available gRPC services, REST endpoints, and their parameters
Multi-protocol: works across SQL databases, gRPC, REST APIs, S3, and Kafka
Quota-efficient: uses unlimited exploration commands first, and knows which operations need a Jira ticket

`debug-postgres-database`

Diagnose and inspect any PostgreSQL database cluster — Aurora or standalone RDS. Gathers AWS RDS instance metadata, parameter group settings, and CloudWatch metrics, then runs live SQL diagnostics via the data-access CLI. All operations are read-only.

What you need:

Firefighter access (required to use the data-access CLI for production queries)
data-access CLI installed and authenticated
AWS CLI configured with appropriate profile access (defaults to prod)
A Jira ticket reference for the audit trail

Quick Start:

# In Claude Code, describe the issue and provide the required arguments
"Investigate slow queries on the attendance service. Cluster: time-money-attendance, DB: attendance, ticket: ENG-1234"

Example:

Your service is returning 500 errors in production. Ask Claude:

"The attendance-service is timing out. Investigate cluster time-money-attendance, database attendance. Jira: ENG-5001."

Claude will check CloudWatch metrics for CPU/connection spikes, surface blocking locks and long-running queries, inspect table health and autovacuum backlog, and produce a compact structured diagnosis with up to 3 actionable next steps.

Why would you want this?

Covers 8 diagnostic phases (instance config, CloudWatch metrics, active sessions, query performance, table health, index health, connections, sequences) in one pass
Read-only — safe to run in production without risk of accidental changes
Structured output keeps findings under 30 lines so they're easy to share in #help-dba
Works for both Aurora clusters and standalone RDS PostgreSQL instances

`datadog`

Investigate application issues by correlating logs, traces, metrics, monitors, incidents, and SLOs via the claude.ai Datadog MCP server. Read-only.

What you need:

claude.ai Datadog MCP server connected — add it under /mcp, then Authenticate
Access to Personio's Datadog org

Need the pup CLI flow? Use the datadog-pup skill instead.

Quick Start:

# In Claude Code, describe the issue and Claude will use the Datadog MCP to investigate
"The payment-service is returning 500 errors in production. What's going on?"

Example:

You notice elevated error rates in your service. Ask Claude:

"Investigate the latency spike in auth-service over the last hour"

Claude will load the relevant MCP skill guides, search logs and traces, query metrics, and correlate across signal types to pinpoint the root cause — no CLI setup required.

Why would you want this?

Diagnose production issues without switching between browser tabs or installing CLIs
MCP skill discovery (list_datadog_skills) loads domain-specific tool guidance before querying
Structured tool outputs — no JSON parsing or flag memorization
Read-only — safe to run without risk of accidental changes

`troubleshoot-alarm`

Troubleshoot a triggered Datadog alarm or monitor alert for a service in the current repository, guided by the repo's SOPS.md runbooks. Slash-command only — invoke explicitly via /troubleshoot-alarm. Finds the matching SOPS playbook (glob + grep by service tag), presents the alarm meaning, runs the diagnostic queries via the Datadog MCP, walks the decision tree, and updates the SOPS with verified learnings at the end.

What you need:

claude.ai Datadog MCP server connected — add it under /mcp, then Authenticate (without it the skill still walks the playbook manually, with ready-to-paste queries)
The service's repository as your current working directory, ideally with SOPS.md runbooks next to the service code

Quick Start:

/troubleshoot-alarm https://app.datadoghq.eu/monitors/12345
/troubleshoot-alarm AlarmErrors on automerge

Why would you want this?

Starts from the SOPS playbook — institutional knowledge first, ad-hoc digging second
Translates pup-format queries from existing SOPS files into Datadog MCP calls automatically
Every investigation improves the runbook: missing decision-tree branches, useful queries, and corrected thresholds flow back into the SOPS (offered as a draft PR)
Hands off to bootstrap-sops when no playbook exists yet

`bootstrap-sops`

Generate SOPS.md runbooks for a service: service metadata, one alarm playbook per Datadog monitor, and draft decision trees. SOPS.md-next-to-code is the convention this plugin promotes — bootstrap-sops seeds it, troubleshoot-alarm consumes and verifies it incident by incident.

A SOPS.md contains a Service Metadata table (Datadog service tag, environments, ready-made log queries), an Overview, a Quick Reference links table, per-monitor Alarm Playbooks (Alarm / Meaning / Diagnose / Decision tree), and Service-Specific Procedures. See the bundled templates/sops-template.md for the canonical structure.

What you need:

claude.ai Datadog MCP server connected (monitor enumeration; without it you only get a skeleton scaffold)
The service's repository as your current working directory

Quick Start:

# In Claude Code, name the service to bootstrap
"Create a SOPS file for the automerge service"
"Add alarm playbooks for my Lambda service"

Why would you want this?

Full monitor coverage in one pass — every Datadog monitor of the service gets a playbook stub
Honest about uncertainty: speculative decision-tree branches are marked (DRAFT — unverified) until a real incident confirms them
Queries are written tool-agnostic (plain Datadog query syntax) so they work in the UI, the MCP, and pup

`datadog-pup`

Troubleshoot Datadog issues via the pup CLI. Fallback for when the claude.ai Datadog MCP server is not installed in your session, or when you explicitly want the CLI path. Generic Datadog investigations should use the datadog skill (MCP-based) instead.

What you need:

pup CLI installed and authenticated (pup auth status)
Access to Personio's Datadog org

Quick Start:

# Explicitly ask for pup, or use this skill when the Datadog MCP server is not connected
"Use pup to check Datadog logs for OOM errors in the auth-service"

Example:

The Datadog MCP server isn't available in your session. Ask Claude:

"Use pup to show me alerting monitors and any open incidents"

Claude will check DD_SITE, verify pup auth status, then run pup monitors search and pup incidents list to give you a health overview.

Why would you want this?

Works without the Datadog MCP server — just pup installed and authenticated
Same investigation workflow as the MCP path, via CLI commands
Read-only — safe to run without risk of accidental changes

`dev-auth`

Mints Personio dev-environment JWTs for hitting service APIs (REST via curl, gRPC via grpcurl) — both user-scoped (web) and service-to-service (s2s). Includes curl/grpcurl invocation recipes for both the dev cluster (*.dev.personio-internal.de) and locally running services (e.g. under mirrord).

What you need:

curl, jq, grpcurl
Dev VPN / network access to *.dev.personio-internal.de

Quick Start:

"Mint a user-scoped dev token for company 12345 / employee 67 and call GET /api/v1/employees/67 on payroll-data-import-service in dev."

Claude will run mint-token.sh web --company-id 12345 --employee-id 67, capture the token, and emit a curl command with the right Authorization and X-Company-Id headers. For gRPC, the same token slots into a grpcurl invocation against grpc-<service>.dev.personio-internal.de:443 (or localhost:9090 with -plaintext for a local mirrord-stolen service).

Why would you want this?

One command for both s2s and web token shapes — no hunting through TechDocs for the right IDP URL or grant type
Pre-baked curl + grpcurl recipes with the right header conventions (X-Company-Id for REST, lowercase authorization metadata for gRPC)
Works hand-in-hand with personio-eng-kotlin:debug-with-mirrord, but useful standalone any time you need to poke a Personio dev API

`rest-api-edm-migration`

Guides the full journey of migrating an existing REST API to EDM-compliant gRPC while keeping the existing REST API live. Orchestrates across entity creation, gRPC service definition, feature flag gating and parallel path implementation.

What you need:

An existing REST API (OpenAPI spec file or REST controller code)
The data-registry repo checked out locally (see find-data-registry-protos)

Quick Start:

"I have this OpenAPI spec for my employee REST API — migrate it to EDM without breaking existing clients."

"Migrate my PayrollEntry REST controllers to EDM gRPC"

Why would you want this?

The REST→EDM migration touches multiple repos, requires non-breaking backward compatibility, and involves several coordinated steps. This skill ensures nothing is missed and developer is guided through the multistep process.

`pgist`

Create and retrieve Personio internal gists using the pgist CLI. Turns a snippet, file, query, or clipboard contents into a shareable internal Personio URL, and fetches the contents of an existing gist from a UUID or URL. Personio's internal gist service only — not public GitHub gists.

What you need:

pgist CLI installed and authenticated
Network access to the Personio developer portal

Quick Start:

"Create a gist from this SQL query so I can share it with my team"

"What's in this gist? https://developer-portal.tools.personio-internal.de/gists/gist/<uuid>"

Claude defaults to creating a draft (pgist create -q -b -d) and returns the draft URL for you to review and publish yourself. It infers a filename for syntax highlighting, derives a title, and scans for obvious secrets before creating — prompting you if anything looks sensitive.

Why would you want this?

One step from a snippet (or your clipboard) to a shareable internal link
Safe by default — drafts you publish yourself, plus a sensitive-content guardrail
Retrieves existing gists straight from a pasted URL or UUID

`write-tdd`

Draft, refine, or review a Personio Technical Design Doc using the canonical TDD template — fetched live from Google Drive so it never goes stale. Runs a three-phase flow: discovery interview, draft generation, then section-by-section review. Any unsourced figures or factual claims are flagged inline with [needs evidence].

What you need:

claude.ai Google Drive MCP connected (for the canonical template)
Optional: personio-common-experimental plugin — its mermaid-converter skill renders Mermaid diagrams inline and its find-information skill powers prior-art research. The skill degrades gracefully if absent.

Quick Start:

"/write-tdd path/to/draft-spec.md"

"Help me write a TDD for the new payroll export service"

`docs-diataxis`

Guides you through writing a polished tutorial, how-to guide, reference, or explanation document following the Diataxis framework. Interviews you on the document's subject matter, then drafts and saves a Markdown file.

What you need:

Nothing extra — works out of the box

Quick Start:

"Help me write a how-to guide for rotating our service's API keys"

"I need a reference doc for our CLI's flags"

Why would you want this?

Guardrails you into the right Diataxis document type instead of a generic, unstructured writeup
Interviews you for the subject-matter details rather than guessing at them
For auditing or grading existing docs against Diataxis, use docs-diataxis-audit instead

EDM Roadmap

Additional EDM skills are planned:

edm-breaking-changes — self-certification and suppression process for proto breaking changes
edm-stability-lifecycle — EXPERIMENTAL annotation, graduation to STABLE, v1alpha migration
edm-grpc-service — gRPC service definition for EDM entities
edm-deprecate-entity — retiring and cleaning up EDM entities
edm-local-dev — JVM and Gofer local dev workflows

Questions or feedback: #cir-dx-edm