Provides platform engineering best practices for Internal Developer Platforms (IDPs), golden paths, service catalogs, and developer experience. Use when building developer platforms, configuring Backstage, designing self-service workflows, or when user mentions 'platform engineering', 'backstage', 'golden path', 'IDP', 'developer portal', 'service catalog', 'DevEx', 'platform team', 'self-service'.
Provides platform engineering best practices for Internal Developer Platforms (IDPs), golden paths, service catalogs, and developer experience. Use when building developer platforms, configuring Backstage, designing self-service workflows, or when user mentions 'platform engineering', 'backstage', 'golden path', 'IDP', 'developer portal', 'service catalog', 'DevEx', 'platform team', 'self-service'.
type
skill
category
patterns
status
stable
origin
tibsfox
modified
false
first_seen
"2026-02-07T00:00:00.000Z"
first_path
examples/platform-engineering/SKILL.md
superseded_by
null
Platform Engineering
Best practices for building Internal Developer Platforms (IDPs) that reduce cognitive load, accelerate delivery, and create golden paths for development teams.
IDP Architecture Layers
A well-designed IDP separates concerns into distinct layers. Each layer abstracts complexity from the one above it.
Stream-Aligned Teams (consumers)
|
| self-service requests
v
Platform Team (enablers)
|
| golden paths, templates, APIs
v
Infrastructure / Cloud (resources)
Platform teams operate as enabling teams (Team Topologies model). They reduce cognitive load on stream-aligned teams by providing curated, opinionated abstractions.
Backstage: Service Catalog and Developer Portal
catalog-info.yaml -- Service Registration
Every service registers itself in the catalog via a catalog-info.yaml at the repo root.
Measure platform effectiveness using the SPACE framework. Never rely on a single dimension.
Dimension
What It Measures
Example Metrics
Collection Method
Satisfaction
How developers feel about the platform
NPS score, satisfaction survey (1-5)
Quarterly survey
Performance
Outcome of developer work
Deployment frequency, change failure rate
DORA metrics pipeline
Activity
Volume of actions
Scaffolding requests, API calls, portal visits
Platform telemetry
Communication
Quality of collaboration
Time to first response on platform support
Ticketing system
Efficiency
Flow and minimal friction
Time from commit to deploy, onboarding time
Pipeline metrics
Key DevEx Metrics Dashboard
# Platform DevEx Metrics -- collected via platform telemetrymetrics:onboarding:time_to_first_deploy:target:"< 2 hours"description:"Time from new hire to first successful deployment"source:"scaffolder + pipeline timestamps"time_to_first_commit:target:"< 4 hours"description:"Time from repo creation to first merged commit"source:"github events"self_service:template_adoption_rate:target:"> 80%"description:"Percentage of new services using golden path templates"source:"backstage scaffolder logs"self_service_resolution_rate:target:"> 70%"description:"Percentage of requests resolved without platform team intervention"source:"support tickets vs portal actions"reliability:platform_availability:target:"99.9%"description:"Uptime of developer portal, CI/CD, and artifact registry"source:"synthetic monitoring"mean_time_to_recovery:target:"< 30 minutes"description:"Time to restore platform services after incident"source:"incident management system"delivery:deployment_frequency:target:"multiple per day per team"description:"How often teams deploy to production"source:"deployment pipeline events"lead_time_for_changes:target:"< 1 day"description:"Time from commit to production"source:"git + pipeline timestamps"
Self-Service Portal Workflow
Request Flow Architecture
Developer submits request via Portal UI
|
v
Request Validation (schema check, policy check)
|
v
Approval Gate (if required by policy)
| |
| auto | manual
v v
Orchestration Engine (executes workflow)
|
+---> Provision Infrastructure (Terraform/Crossplane)
+---> Configure CI/CD (GitHub Actions / ArgoCD)
+---> Register in Catalog (Backstage)
+---> Set Up Monitoring (Grafana / PagerDuty)
+---> Notify Team (Slack / Email)
|
v
Verification (health checks, smoke tests)
|
v
Developer notified -- ready to use
Level 1 --> Level 2:
[x] Service catalog exists and is maintained
[x] At least 3 golden path templates available
[x] Basic developer portal deployed
[x] CI/CD standardized across teams
Level 2 --> Level 3:
[x] Self-service for >80% of common requests
[x] SPACE metrics collected and reviewed monthly
[x] Policy-as-code enforced (not advisory)
[x] Platform team has dedicated product manager
[x] Internal SLOs defined for platform services
Level 3 --> Level 4:
[x] API-first platform (all capabilities programmable)
[x] Internal developer marketplace for plugins/extensions
[x] Continuous developer experience research program
[x] Platform economics model (cost attribution per team)
[x] Platform contributes to organizational strategy
Anti-Patterns
Anti-Pattern
Problem
Fix
Build it and they will come
No adoption without developer input
Treat platform as product; user research before building
Ticket-ops disguised as platform
Self-service portal that just creates tickets
Automate end-to-end; tickets are a smell, not a solution
Mandating platform use
Forced adoption breeds resentment and workarounds
Make the golden path the easiest path, not the only path
One-size-fits-all templates
Overly rigid templates that don't fit team needs
Composable templates with sensible defaults and escape hatches
No feedback loops
Platform team builds in isolation
Regular surveys, office hours, embedded rotations with teams
Ignoring developer experience
Technically correct but painful to use
Measure DevEx metrics, optimize for developer happiness
Platform team as bottleneck
All changes go through platform team
Self-service with guardrails; teams should not wait on platform
Over-abstracting too early
Complex abstraction layers before understanding needs
Start with concrete solutions, abstract when patterns emerge
Neglecting documentation
Powerful platform nobody knows how to use
Docs-as-code, TechDocs in Backstage, examples for everything
No platform SLOs
Platform reliability treated as best-effort
Define and publish SLOs; platform is a product with SLAs
Shadow platforms
Teams build their own tooling around the platform
Understand why and address gaps; shadow platforms reveal unmet needs
Gold plating the portal
Spending months on portal UI before delivering value
Ship incrementally; a working CLI beats a beautiful but empty portal
Platform Engineering Checklist
Platform team established with clear product ownership
Developer portal deployed (Backstage or equivalent)
Service catalog populated with all production services
At least 3 golden path templates available and documented
Self-service provisioning for common infrastructure (databases, queues, caches)
CI/CD pipelines standardized and available via templates
Observability stack integrated (dashboards auto-created with new services)
Security scanning built into golden paths (not bolted on after)
DevEx metrics defined and collected (SPACE framework dimensions)
Feedback mechanism active (surveys, office hours, Slack channel)
Platform SLOs defined and monitored
Documentation maintained in developer portal (TechDocs)
Onboarding time measured and optimized (target: first deploy < 2 hours)
Cost visibility per team/service available through platform
Platform roadmap published and informed by developer feedback
Escape hatches documented for when golden paths don't fit
Platform reliability meets or exceeds published SLOs
