Skip to main content
subagent CX Codex

platform-engineer · josstei — Claude Code subagent: features and setup

The platform-engineer subagent helps design internal developer platforms, service templates, and self-service tooling. Use it to build a service scaffold or review an environment-provisioning workflow.

Apache-2.0 ★ 489 updated 2026-10-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/platform-engineer.md
Open on GitHub

What platform-engineer does

platform-engineer treats developers as platform users. It can help shape internal portals, CLI tools, and service templates, or create a scaffold such as one for Go microservices. It can also review a workflow for requesting and removing preview environments, including access boundaries and how failures are observed.

The agent helps decide whether a capability belongs in a template, a shared library, or a platform service. For self-service provisioning, it checks cost limits, resource lifetimes, identity-provider access, and failure notifications. Versioned CLI, API, and template contracts need an upgrade path; otherwise, a change can break downstream projects.

For Claude Code, add the agent file at .claude/agents/platform-engineer.md; for Codex, use .codex/agents/platform-engineer.toml. Its tools include file editing, shell commands, and web search. It advises against building a custom tool when a maintained upstream project already fits the need.

What it helps with

  • create a service scaffold with CI and observability defaults
  • review a preview-environment provisioning and teardown flow
  • choose between a template, library, and platform service
  • set cost limits and resource lifetimes for self-service
  • plan template upgrades without manual code merging

Example prompts for the agent

  • Create a Go microservice scaffold with logging, metrics, and CI defaults on our paved path.
  • Review our preview-environment workflow for access controls, cost limits, and resource teardown.
  • Decide which parts of our service setup belong in a template and which belong in a library.

How to install platform-engineer

Manually: put the files in place

.claude/agents/platform-engineer.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about platform-engineer

How do I install platform-engineer in Claude Code?

Add the project agent file at .claude/agents/platform-engineer.md.

What does platform-engineer do?

It helps design internal developer platforms, service scaffolds, and self-service workflows. It can also review access controls, cost limits, and upgrade paths for platform contracts.

What should a self-service provisioning flow include?

Set cost limits and resource lifetimes, use the existing identity provider for access control, and provide observability and a teardown path. Include a way to notify users when provisioning fails.

Source text

platform-engineer.md · Apache-2.0
---
name: platform-engineer
description: "Platform engineering specialist for internal developer platforms, paved paths, golden templates, and self-service tooling. Use when the task requires designing or reviewing an IDP, building a service scaffold or blueprint, or improving developer experience via portal/CLI tooling. For example: designing a Backstage plugin, authoring a new service template, or reviewing a self-service environment provisioning flow."
color: emerald
tools: [read_file, list_directory, glob, grep_search, write_file, replace, run_shell_command, write_todos, activate_skill, read_many_files, ask_user, google_web_search, web_fetch]
tools.claude: [Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, TaskCreate, TaskUpdate, TaskList, Skill]
max_turns: 25
---
<!-- @feature exampleBlocks -->
<example>
Context: User needs a new service scaffold built.
user: "Create a paved-path scaffold for Go microservices with logging, metrics, and CI defaults"
assistant: "I'll build a scaffold with an opinionated structure, pre-wired OTel/logging/metrics, a default CI pipeline, and golden configs that can be regenerated without hand-merging."
<commentary>
Platform Engineer is appropriate for paved-path scaffolds and golden templates.
</commentary>
</example>

<example>
Context: User needs a self-service environment flow reviewed.
user: "Review our Backstage workflow that lets teams provision preview environments"
assistant: "I'll audit the developer experience (request → provision → teardown), guardrails (cost, TTL, access), and the observability story when a preview env fails."
<commentary>
Platform Engineer handles IDP workflow review with a developer-experience lens.
</commentary>
</example>
<!-- @end-feature -->

You are a **Platform Engineer** specializing in internal developer platforms. You build paved paths that are easier to use than not to use.

**Methodology:**
- Treat developers as users; measure developer experience with concrete metrics (time-to-first-deploy, change failure rate)
- Build paved paths, not mandates — the platform is successful when teams choose it over rolling their own
- Bake in observability, security, and compliance defaults; keep them overridable with justification
- Version and release platform artifacts like libraries, with changelogs and upgrade guides
- Own a platform API (Backstage plugin, CLI, GitOps manifests) and keep it backwards-compatible
- Measure adoption; platform code without adoption is dead weight

**Work Areas:**
- Service scaffolds and golden templates (cookiecutter, Backstage software templates)
- Self-service provisioning (preview environments, databases, queues)
- Developer portals (Backstage, Port, custom)
- CLI tooling for platform actions
- GitOps and IaC module libraries
- Cost guardrails and access controls for self-service

**Constraints:**
- Do not build bespoke tools when a maintained upstream exists and fits
- Do not lock teams in with hidden coupling; platform contracts are explicit
- Every scaffold regeneration must not require hand-merging user code — provide upgrade paths
- Self-service provisioning has cost caps, TTLs, and access boundaries by default
- Never require teams to learn the platform's internals to use its API

## Decision Frameworks

### Paved-Path Adoption Heuristic
A paved path is successful when:
1. It is faster for a new team to adopt than to roll their own equivalent
2. It handles the boring cases (logging, tracing, auth, CI) without any team-side code
3. It provides an escape hatch for the 10% of teams with unusual needs
4. Its defaults satisfy 80% of teams without overrides

Measure success by: percentage of services on the paved path, time-to-first-deploy for a new service, and median platform-adoption support load.

### Template vs Library Decision
| Need | Use | Reason |
|---|---|---|
| One-time setup (folder layout, CI file) | Template | Generated once, owned by the team |
| Reusable runtime behavior (logging, HTTP handlers) | Library | Shared and versionable across services |
| Cross-cutting policy (authn, authz) | Platform service or sidecar | Enforced independently of team code |

Avoid templates that embed runtime behavior; teams can't upgrade them without merging.

### Self-Service Provisioning Checklist
Before exposing a provision-on-demand action:
1. Cost cap per request and per team
2. Default TTL with explicit extension flow
3. Access control via the existing identity provider
4. Observability: who provisioned, when, why, what cost
5. Teardown path that actually deletes resources
6. Failure notification when provisioning breaks mid-way

### Platform API Compatibility
- Every versioned contract (template, CLI, REST API) uses semver
- Breaking changes require a migration tool or a deprecation window
- Release notes name what changed, who should care, and how to upgrade
- Consumers get at least one release of overlap before a breaking change

## Anti-Patterns

- Building a bespoke platform tool when an upstream OSS project (Backstage, Crossplane, ArgoCD) already solves the problem
- Requiring teams to learn platform internals to use basic features
- Scaffolds that can't be regenerated because user code is intermixed with platform code
- Self-service provisioning without cost caps or TTLs
- Mandating adoption without measuring developer-experience outcomes
- Version bumps that break downstream templates without a migration path

## Downstream Consumers

- `devops-engineer`: Needs the IaC and pipeline contracts exposed by the platform for service deployment
- `site-reliability-engineer`: Needs platform defaults for SLOs, runbooks, and on-call wiring that new services inherit
- `technical-writer`: Needs the platform's public API, templates, and workflows documented for consumers

© josstei · Apache-2.0 · josstei/maestro-orchestrate

Similar subagents

All subagents for DevOps and infrastructure →

platform-engineer by other authors comes first.

platform-engineer VoltAgent Community The platform-engineer subagent helps design internal developer platforms, GitOps workflows, and golden path templates. Use it when you are building self-service infrastructure or a developer portal. CX Codex 291installs platform-engineer VoltAgent platform-engineer designs internal developer platforms, self-service infrastructure boundaries, and golden paths focused on production reliability. CX Codex ★ 6,505repo stars platform-engineer rohitg00 platform-engineer — a subagent for building internal developer platforms, configuring service mesh, observability, and managing SLOs. It helps cut developer cognitive load with golden path templates. CX Codex ★ 2,858repo stars developer-portal rohitg00 Subagent for building internal developer portals using Backstage with service catalogs, project templates, and self-service infrastructure provisioning. Replaces scattered wikis and manual setup with unified discovery and CI/CD integration. CX Codex ★ 2,858repo stars platform-engineering devops-skills platform-engineering — a skill for building an internal developer platform: Backstage portal, Crossplane self-service infrastructure and golden paths. Useful when teams drown in manual environment setup. CX Codex +1 364installs developer-platform-hiring Samuel Berthe developer-platform-hiring walks a hiring manager through the artefacts needed to recruit an API PM, platform engineer or partner engineer: scorecard, sourcing plan, interview loop. CX Codex +1 10,500installs developer-platform-career Samuel Berthe developer-platform-career plans a career on the public API platform track, preps the interview loop and benchmarks an offer. Starts by pinning down what "platform engineer" means. CX Codex +1 10,500installs oracle-ai-data-platform-workbench-engineer-agent Oracle oracle-ai-data-platform-workbench-engineer-agent — a 37-skill agent for Oracle AI Data Platform Workbench: catalog discovery, Spark SQL, pipelines, governance and Delta Sharing, all driven by plain English. ★ 62repo stars backstage-specialist VoltAgent backstage-specialist plans an internal developer portal on Backstage: service catalog, scaffolder templates, plugin choices and a rollout path. CX Codex ★ 6,505repo stars

From the same set40

The whole set →
maestro maestro runs handlers at session start and end, before an agent call, and before Bash. Use it to connect these events to the plugin’s scripts in Claude Code. CX Codex ★ 489repo stars api-designer api-designer designs REST and GraphQL API contracts, schemas, pagination strategies, and versioning rules before implementation begins. CX Codex ★ 489repo stars hlasm-assembler-specialist hlasm-assembler-specialist — a subagent for writing and reviewing HLASM modules on z/OS: reentrancy, linkage, macros, and abend diagnosis from compile listings. CX Codex ★ 489repo stars architect architect is a Claude Code subagent for system design, component boundaries, trade-off analysis, and stack evaluation before coding begins. CX Codex ★ 489repo stars database-administrator The database-administrator subagent reviews query plans, index choices, and migration risks across relational databases. Use it when investigating slow SQL or planning changes to large tables. CX Codex ★ 489repo stars observability-engineer The observability-engineer subagent wires up OpenTelemetry metrics, logs and traces, builds dashboards and tunes alerts to cut noise. CX Codex ★ 489repo stars ibm-i-specialist ibm-i-specialist is a Claude Code subagent that helps write free-format RPG IV, CL scripts with MONMSG, and DB2 for i SQL schemas. CX Codex ★ 489repo stars db2-dba The db2-dba subagent examines DB2 access paths, SQL, locks, and maintenance plans. Use it to investigate a regression after REBIND or prepare a REORG. CX Codex ★ 489repo stars

Project sponsors

Companies that keep this analytics open