personio-common

Common skills and conventions shared across all PTech functions — engineers, product managers, designers, and more. Installed by default for everyone in PTech.

Installation

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

What does this plugin do?

This plugin provides skills and guidance that apply to everyone in PTech, regardless of role or tech stack. It covers shared conventions, standards, and best practices used across the organisation.

backstage Skill

Look up any entity in the Personio Developer Portal (Backstage catalog) — components, teams, people, systems, resources, and APIs.

What you need:

• Network access to the Developer Portal (VPN connection)
• curl and jq available in your terminal

Quick Start:

/backstage who owns payment-service
/backstage slack channel for team tm
/backstage members of team data-registry
/backstage find user martin-lechner

Example:

$ /backstage who owns release-bot

# Claude queries the Backstage catalog API
# Finds the component and resolves the owning team
# Returns:

Component: release-bot (tool, production)

| Field         | Value              |
|---------------|--------------------|
| Owner Team    | dt                 |
| Slack Channel | #cir_tech_dt       |
| Manager       | some-manager       |
| GitHub Repo   | Personio-Internal/release-bot |

Why would you want this?

• Find who owns a service and how to contact them
• Look up a team's Slack channel, manager, or Jira project
• Find all services owned by a team
• Look up a person's team membership, position, or contact info
• Explore systems, resources, and APIs in the catalog

claude-md Skill

Create and maintain high quality CLAUDE.md files — the primary mechanism for onboarding Claude to codebases.

What you need:

• A codebase you want to set up Claude Code for (or an existing CLAUDE.md to improve)

Quick Start:

# Create a new CLAUDE.md
"Create a CLAUDE.md for my project"

# Improve an existing one
"Review my CLAUDE.md and suggest improvements"

# Audit for anti-patterns
"My CLAUDE.md is 400 lines, help me trim it down"

Example:

When you ask "Create a CLAUDE.md for my project", the skill will:

1. Explore the codebase to understand the stack, structure, and workflows
2. Create a lean CLAUDE.md (~60 lines) covering WHAT/WHY/HOW
3. Use file:line pointers instead of embedding code
4. Suggest an agent_docs/ structure for detailed documentation

Why would you want this?

• Get Claude Code working effectively in your repo from day one
• Avoid common anti-patterns (code style rules, command dumps, bloated files)
• Keep your CLAUDE.md focused — under 60 lines ideal, under 150 acceptable
• Use progressive disclosure to balance context quality with detail

code-expert-finder Agent

Identify the most knowledgeable contributors for a specific file, function, or code section by performing git archaeology. The agent traces code history through renames and moves, classifies contributions as substantial or superficial, and looks up associated PRs for design context.

What you need:

• GitHub CLI (gh) installed and authenticated
• Git repository with history

Quick Start:

# Ask Claude who knows about a specific file
"Who should I ask about src/auth/middleware.ts?"

# Find experts for code you're about to refactor
"I need to refactor the caching layer — who has the deepest knowledge of src/cache/redis-manager.ts?"

# Understand the history behind an implementation
"Who wrote the payment processing logic in this function?"

Example:

When you ask "Who should I talk to about the authentication middleware?", the agent will:

1. Run git blame to identify all contributors
2. Examine each commit to classify changes as substantial (feature work, bug fixes) vs superficial (formatting, renames)
3. Look up associated PRs for design context and discussion
4. Return a ranked list of up to 3 experts with evidence (PR links, commit SHAs, timeframe)

Why would you want this?

• Onboarding: Quickly find who to ask about unfamiliar code
• Cross-team work: Identify domain experts before making changes in another team's area
• Code reviews: Find the right reviewers based on actual code knowledge, not just team ownership
• Complements find-owner: While find-owner gives org-chart ownership, this gives git-history expertise

acli Skill

Reference guide for the Atlassian CLI (acli) covering Jira and Confluence operations. Claude will prefer the Atlassian MCP when available and fall back to acli commands.

What you need:

• Atlassian CLI (acli) installed and authenticated — see the setup guide

Quick Start:

# Search Jira tickets
"Find my open tickets in project TEAM"

# View a specific ticket
"Show me the details of TEAM-123"

# Transition a ticket
"Move TEAM-123 to Done"

# View a Confluence page
"Show me the Confluence page with ID 12345"

atlas-projects Skill

Read project data from Atlas, Personio's product portfolio in Airtable, via the Airtable MCP connector. Pairs projects with JIRA ticket progress when the Atlassian MCP is available, surfaces hygiene flags for PM/EM/Designer roles, and drafts updates for the user to paste back into Atlas (the connector is read-only).

What you need:

• Airtable MCP connector authenticated in Claude (Atlas base appvjwnRXUoNbcrKx)
• Optional: Atlassian MCP for JIRA pairing

Quick Start:

# Status / roadmap / hygiene lookups
"What's the status of [project]?"
"What's my team working on?"
"What does Atlas say about EUJ X?"
"Give me the weekly digest for [project]"
"What's stale on our roadmap?"

# JIRA pairing (after the skill has captured the mapping)
"Pair [project] with the XYZ JIRA project"
"How's [project] tracking against its JIRA tickets?"

Example:

$ "What's the status of Project Lighthouse?"

**Project Lighthouse** — Build | RAG: Amber | GA: 2026-09-15 (Confirmed)

Status: Two backend tracks parallelising; design review extended by a week.

Commitments: Q3 2026 · Open Beta 2026-08-12 · GA 2026-09-15
— Delivery Status: Confirmed

⚠️ Hygiene flags:
🕐 No status update in 60+ days — please add a project history entry

Why would you want this?

• Pull live Atlas data without leaving Claude — phase, RAG, GA, Delivery Status
• Co-surface Delivery Status with any date or quarter so customer-facing roles don't accidentally overpromise
• Get hygiene flags surfaced verbatim when you're the project owner (PM/EM/Designer)
• Cross-reference Atlas RAG with JIRA blocked tickets to catch optimistic statuses
• Generate draft Project History entries you can paste back into Atlas

catalog Skill

Create and edit .catalog.yml files for the Personio service catalog. The skill fetches the live JSON schema at runtime so it always reflects the current field definitions, valid types, and enum values.

What you need:

• Network access to the service catalog API — falls back to embedded reference if unavailable

Quick Start:

/catalog create a new catalog file for my microservice
/catalog add the pii and critical tags
/catalog change lifecycle to production
/catalog add a worker component to the catalog file
/catalog add kafka consumer config for topic ece.v1.order.placed

Example:

$ /catalog create a catalog file for a new microservice called order-processor owned by team payments

# Claude fetches the latest schema, checks for an existing .catalog.yml
# Creates the file:

# yaml-language-server: $schema=https://service-catalog.tools.personio-internal.de/api/v1/jsonschema
---
version: '1'
type: microservice
component:
  name: order-processor
  service: order-platform
  team: PAYMENTS
  description: Processes customer orders
  lifecycle: production

Why would you want this?

• Create a valid .catalog.yml from scratch without manually reading the schema docs
• Add or update tags, lifecycle, team ownership, or Kafka config with confidence
• Add multiple components (API + worker + cronjob) to a single catalog file using multi-document YAML
• Stay current with schema changes — the skill always fetches the latest schema at runtime
• Avoid accidentally using deprecated fields (usesPII, isPublic, etc.) that should be replaced with tags

dx-feedback Skill

Send feedback about Claude Code to the DX Tools team as a Jira ticket in the DX project. Covers frustrations with Claude, ideas for new plugins or skills, and general feedback on Claude Code workflows.

What you need:

• Atlassian MCP authenticated (preferred) — or acli installed and authenticated as a fallback
• Git configured with your Personio email (git config user.email) so you can be set as the reporter

Quick Start:

# Explicit invocation — skips the confirmation step
/dx-feedback the backstage skill is slow when looking up teams

# Natural language — Claude will confirm before filing
"I wish Claude could generate release notes from merged PRs"
"Claude keeps suggesting git add -A even after I tell it not to — send this to DX"

Example:

$ /dx-feedback the pr-workflow plugin picks the wrong reviewers about half the time

# Claude preflights the Jira connection (MCP first, acli fallback)
# Drafts the ticket and shows you the title, description, and labels
# Asks for approval
# Files it as a Task in the DX project with labels:
#   dx-ai-tooling, dx-user-feedback, dx-feedback-frustration
# Returns the ticket URL:

Filed as DX-1234 — thanks, the DX Tools team will see it in their backlog.

Why would you want this?

• Turn in-the-moment frustrations into actionable backlog items without leaving Claude
• Suggest new plugins, skills, or agents while the idea is fresh
• Keep the DX Tools team in the loop on what's working and what isn't — every ticket lands in one board they triage
• Reporter is set to you automatically so the DX team can follow up

find-firefighter Skill

Find the current on-call firefighter(s) for a Personio team — given a team code (e.g. kdx), a repo path with a .catalog.yml, or a component name (resolved to its owning team via the backstage skill). The skill calls the get_team_on_call tool on the personio-mcp-server MCP server, reasons over the team's full schedule list (firefighter / shadow / OOH / sub-area / per-engineer), and reports the right person(s) with their GitHub handles.

This skill is strictly informational. For "find a firefighter and add them to a PR's review", use the separate assign-firefighter-reviewers skill, which composes this one and adds CODEOWNERS-aware reviewer assignment.

What you need:

• The personio-mcp-server MCP server connected (auto-registered by this plugin's .mcp.json)
• Network access to the Developer Portal (VPN required)
• curl and jq for the optional component-name lookup mode

Quick Start:

# By team code
/find-firefighter kdx

# By repo path (reads .catalog.yml)
/find-firefighter ~/dev/data-registry

# By component name (resolves owner team via Backstage)
"Who should I ping about the payment-service component right now?"

# Natural language
"Who's on call for the EO team?"
"Find the current WAC firefighter"

Example:

$ /find-firefighter kdx

Current firefighter for team kdx (PTECH_FDNS_DX_KDX):
  - Alice Example (alice.example@personio.de) — GitHub: @alice-example_personio
    Schedule: KDX Schedule

$ "Find the firefighter for the EO team"

Multiple firefighters on rotation for team eo right now:
  - Bob Example   — @bob-example_personio   (Schedule: EO Attributes Firefighter)
  - Carol Example — @carol-example_personio (Schedule: EO EMP Firefighter)
  - Dave Example  — @dave-example_personio  (Schedule: EO ORG Firefighter)

Which sub-area is your question about? (Attributes / EMP / ORG)

Why would you want this?

• Need to escalate something and want the right person, not whoever you saw last week
• Working in a repo and want to know who currently owns the on-call without leaving the terminal
• About to open a cross-team PR and want to start with "who's on call for these teams?" before dealing with reviewer assignment (which is what assign-firefighter-reviewers is for)
• The skill returns the full schedule list so you can see why a particular person was picked — auditable, not magic

manage-github-team-member Skill

Add or remove a person from a Personio GitHub team by opening a PR to the software-catalog-registry. GitHub team membership at Personio is managed as code — this skill handles finding the right group file, updating the member list, and opening the PR for you.

What you need:

• gh CLI installed and authenticated with access to Personio-Internal
• The GitHub team name or URL and the member's Personio username or email

Quick Start:

Add wen.qinglim@personio.de to the AI GitHub team https://github.com/orgs/Personio-Internal/teams/ai
Remove bob.jones from the payments team

Example:

User: Add john.doe to the payments team on GitHub

# Claude finds registry/groups/ptech_payments.yaml in software-catalog-registry
# Checks john.doe is not already a member or manager
# Creates branch add-john.doe-to-payments
# Adds john.doe to the members list
# Opens PR: https://github.com/Personio-Internal/software-catalog-registry/pull/...

Why would you want this?

• Onboard a new hire to their team's GitHub access without remembering which repo and file to edit
• Offboard a leaver cleanly via a PR rather than a direct API call
• Avoid accidentally bypassing the code-as-config workflow by using the GitHub API directly
• Get a PR that is automatically validated by the registry pipeline before any membership change takes effect
• Works for any Personio GitHub team — not just engineering teams

Automatic Marketplace Refresh

This plugin includes a SessionStart hook that automatically refreshes the Personio plugin marketplace once per day. This ensures you always have the latest plugin versions without manual intervention.

• Runs in the background (async) — never blocks your session startup
• Checks a local timestamp and skips if less than 24 hours have passed
• Failures are silently ignored so they never disrupt your workflow

No configuration needed — it works automatically once the plugin is installed.

Usage Telemetry

This plugin sends anonymous-ish usage events to PlatformX (getDX) so the DX team can measure adoption. Events carry your git config user.email and are only sent for @personio.de addresses. All telemetry hooks run async, fail open, and never block your session.

Skill events from repo-local or personal skills have skill_source: local and no plugin fields — that is expected, not a data bug.

Every send or drop is logged to ~/.claude/personio-skill-track.log (auto-trimmed) so undercounting is diagnosable per machine. Known gap: tool calls made inside subagents don't fire hooks, so skills invoked by subagents are not counted (the subagent run itself is).

Safety Hooks

This plugin includes safety hooks that automatically guard against common mistakes when Claude Code runs git commands, and provide recovery guidance when MCP tools fail. All hooks fail open — if something goes wrong (e.g., jq is missing), they allow the command rather than blocking your workflow.

Block direct commits to main/master

Prevents git commit when the target branch is main or master (Personio-Internal repos only). All changes should go through feature branches and pull requests.

The check evaluates the repo the commit will actually target — it reads git's own location options (-C <dir>, --git-dir, --work-tree) out of the command rather than assuming the session's working directory, so it stays correct in multi-repo sessions. Detection also tolerates flags between git and commit (e.g. git -C dir commit, git -c k=v commit), so it can't be slipped by inserting an option.

Residual gap: because a PreToolUse hook only sees the command string, paths built from $(...)/variables or quoted paths containing spaces aren't resolved. The companion cd-guard below removes the most common ambiguity (cd + git).

Steer cd <dir> && git to git -C <dir>

Blocks commands that cd into a directory and then run git (chained with && or ;), asking Claude to use git -C <dir> ... instead. A cd makes the target directory implicit, which hides which repo a git command hits and undermines the other git guardrails; requiring git -C keeps the target explicit so those guards evaluate the right repository.

Guard merged PRs

Blocks git push, git commit, git rebase, git reset, and gh pr edit when the current branch already has a merged PR on GitHub. Once a PR is merged, modifying its branch causes confusion and breaks history.

When blocked, Claude is told to create a new branch from main/master and open a new PR instead.

Merged status is cached per repo+branch in /tmp, so repeated checks for the same merged branch avoid extra gh calls. The hook uses a pure Bash fast path to skip jq/gh on unrelated Bash commands.

Block cross-remote pushes

Prevents git push to a remote that points to a different GitHub repository than origin. This catches cases where Claude pushes to the wrong remote in repos with multiple remotes configured.

MCP failure recovery

Automatic detection and recovery guidance when MCP servers disconnect or fail. Covers Atlassian, Personio TechDocs, Playwright, and Figma MCP servers.

When an MCP tool call fails due to a server-level issue (authentication, connectivity, timeout, or disconnection), Claude automatically receives recovery guidance specific to that server — including the exact command to reconnect and a fallback approach.

Additionally, at the start of each prompt, Claude checks for recent MCP failures and warns you proactively before you hit the same error again.

Failure types detected:

Server-specific fallbacks:

Normal tool errors (e.g., "issue not found") are ignored — no false positives.

MCP: TechDocs (personio-mcp-server)

This plugin includes an MCP server that provides access to Personio's internal TechDocs documentation. When connected, Claude can search, browse, and read TechDocs pages directly without needing any additional tools.

install-personio-mcp-desktop Skill

Install the Personio Backstage MCP (personio-backstage-mcp) into the Claude Desktop app config file. Claude reads your existing claude_desktop_config.json, merges in the new server entry while preserving everything else, and writes the result back. Idempotent — safe to re-run.

Claude Desktop only accepts stdio MCP configs, so the skill wires the HTTP server through mcp-remote run with npx.

Not for Claude Code — that already has the server configured at project scope via .mcp.json, and user-scope installs should use claude mcp add.

What you need:

• Claude Desktop installed on your machine
• Either Claude Desktop's built-in Node enabled (isUsingBuiltInNodeForMcp: true — the skill flips this on by default) or Node 18+ available on your system
• Write access to ~/Library/Application Support/Claude/ (macOS default)

Node version gotcha: mcp-remote needs Node 18+. If Claude Desktop spawns npx under a nvm-provided Node 16, you'll see ReferenceError: ReadableStream is not defined in ~/Library/Logs/Claude/mcp-server-personio-backstage-mcp.log. The skill sets isUsingBuiltInNodeForMcp: true to route MCP servers through Claude Desktop's bundled Node 20+.

Quick Start:

"install personio mcp in claude desktop"
"add personio-backstage-mcp to my claude desktop config"
"merge personio mcp into claude_desktop_config.json"

Example:

$ install personio mcp in claude desktop

# Claude reads your existing ~/Library/Application Support/Claude/claude_desktop_config.json
# Detects that `personio-backstage-mcp` is not present
# Merges an mcp-remote stdio bridge entry while preserving other mcpServers and top-level keys
# Validates the resulting JSON
# Returns:

Installed personio-backstage-mcp into Claude Desktop config.
Fully quit Claude Desktop (Cmd+Q) and reopen it to activate.

Running the skill a second time reports personio-backstage-mcp already configured and does not touch the file.

Why would you want this?

• Get Personio TechDocs / Backstage search available inside the Claude Desktop app without hand-editing JSON
• Avoid breaking the config file with malformed JSON — the skill aborts safely if the existing file is not valid
• Preserve every other MCP server you already have configured
• Stay idempotent so it's safe to wire into setup scripts