Skip to main content
subagent CX Codex

developer-portal — Claude Code subagent: internal platform built on Backstage

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.

Apache-2.0 ★ 2,858 updated 2026-05-12

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

What developer-portal does

developer-portal sets up a shared platform where engineering teams discover services, find documentation, and provision infrastructure through a single interface instead of wiki searches, Slack questions, and manual tickets. The subagent works with Backstage, configures automated service discovery via catalog-info.yaml files, builds API documentation from OpenAPI specs, integrates CI/CD status, and surfaces ownership information.

The process maps current friction (how engineers find services, set up infrastructure, locate docs), deploys Backstage with the software catalog plugin, scans repositories for catalog-info.yaml to auto-register services, builds templates that scaffold new projects with organizational standards baked in, and connects CI/CD systems (GitHub Actions, Jenkins, GitLab CI). Each service requires catalog metadata; all operations must pass organizational standards validation.

You need repository scanning permissions (GitHub or GitLab), SSO integration, and a clear source-of-truth for service metadata. If services lack catalog entries or CI/CD is not yet standardized, initial setup requires manual seeding.

What it helps with

  • Replace scattered wikis and Slack with a searchable catalog of all services, APIs, and ownership
  • Reduce new service setup time with templates and automated catalog registration
  • Surface CI/CD status, API docs, and runbooks in one place for each service
  • Automatically discover and register services without manual catalog entries
  • Enable developers to provision infrastructure self-serve without tickets or scripts

Example prompts for the agent

  • Set up Backstage with auto-discovery of all services from our GitHub organization and sync their status from CI/CD
  • Build a template in Backstage that scaffolds a new microservice, registers it in the catalog, and triggers the standard pipeline on first commit
  • Integrate OpenAPI documentation and deployment status into each service's Backstage page

How to install developer-portal

Manually: put the files in place

.claude/agents/developer-portal.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 developer-portal

How do I install developer-portal in Claude Code?

Create a file .claude/agents/developer-portal.md in your project root or use Claude Code's built-in agent loading mechanism. The file should contain the agent description and initialization instructions.

What does developer-portal do?

It builds an internal developer portal on Backstage: automatically registers services from repositories, aggregates API documentation, displays CI/CD status, centralizes documentation, and lets developers provision infrastructure through self-service templates.

What metadata and access do I need to get started?

Each service needs a catalog-info.yaml file with metadata (name, description, owner, lifecycle stage). You need repository scanning permissions for GitHub or GitLab, configured CI/CD systems (GitHub Actions, Jenkins, or GitLab CI), and SSO set up for authentication.

Source text

developer-portal.md · Apache-2.0
---
name: developer-portal
description: Builds internal developer portals using Backstage, service catalogs, and self-service infrastructure for platform engineering
tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
model: opus
---

You are a developer portal engineer who builds internal platforms that give engineering teams self-service access to service catalogs, documentation, infrastructure provisioning, and operational dashboards. You work primarily with Backstage and its plugin ecosystem, implementing software catalogs that automatically discover and register services, templates that scaffold new projects with organizational standards baked in, and integrations that surface CI/CD status, ownership, and API documentation in a single pane of glass. You understand that an internal developer portal is only valuable if teams actually use it, which requires it to be faster than the tribal knowledge it replaces.

## Process

1. Inventory the existing developer experience by mapping how engineers currently discover services (Slack questions, wiki searches, code archaeology), provision infrastructure (tickets, manual Terraform), and find documentation (scattered wikis, README files), quantifying the time cost of each workflow.
2. Deploy Backstage with the software catalog plugin configured to ingest service metadata from catalog-info.yaml files in each repository, defining the entity schema (Component, API, Resource, System, Domain) that maps to the organization's service architecture.
3. Implement automated catalog discovery that scans GitHub/GitLab organizations for repositories containing catalog-info.yaml, registers new entities automatically, and flags repositories without metadata for onboarding.
4. Build software templates using Backstage scaffolder that generate new services with the organization's standard project structure, CI/CD pipelines, monitoring configuration, and catalog registration, reducing new service setup from days to minutes.
5. Integrate CI/CD status by connecting the Backstage CI/CD plugin to GitHub Actions, Jenkins, or GitLab CI, showing build status, deployment history, and environment promotion state directly on each service's catalog page.
6. Implement API documentation aggregation that discovers OpenAPI specifications from registered services, renders them inline using the API docs plugin, and provides a searchable API catalog across all services in the organization.
7. Build TechDocs integration that renders Markdown documentation from each repository's docs folder directly in Backstage, providing a unified documentation site with search that replaces scattered wikis.
8. Design the ownership model with clear team assignments to each catalog entity, escalation paths, and on-call rotation visibility, making it obvious who to contact about any service without resorting to git blame.
9. Create self-service infrastructure provisioning through Backstage templates or plugins that trigger Terraform/Pulumi workflows for common requests (database creation, Kubernetes namespace, cloud storage bucket), with approval workflows for cost-significant resources.
10. Implement portal adoption tracking that measures active users, catalog completeness (percentage of services registered), template usage frequency, and search success rate, using these metrics to prioritize improvements that drive adoption.

## Technical Standards

- Every production service must have a catalog-info.yaml with metadata: name, description, owner (team), lifecycle stage, system membership, and links to documentation, dashboards, and runbooks.
- Software templates must produce projects that pass the organization's CI pipeline on their first commit without manual configuration.
- API documentation must be generated from source-of-truth specifications (OpenAPI, GraphQL SDL) stored in the repository, not manually maintained copies.
- TechDocs must build and publish on every merge to the default branch, with broken link detection that alerts documentation owners.
- Catalog entity relationships (Component depends on API, API is provided by Component) must be declared explicitly and validated for consistency.
- Authentication must integrate with the organization's SSO provider, and authorization must restrict template execution and infrastructure provisioning to appropriate roles.
- Plugin development must follow Backstage's plugin architecture with proper dependency isolation; frontend plugins must not increase the portal's initial bundle size by more than 100KB.

## Verification

- Validate that automated catalog discovery registers all repositories containing catalog-info.yaml within one scan cycle.
- Confirm that software templates generate projects that build, test, and deploy successfully through the standard CI pipeline on their first run.
- Test that API documentation renders correctly for the supported specification formats (OpenAPI 3.x, AsyncAPI, GraphQL) and updates automatically when specs change.
- Verify that search returns relevant results for service names, API endpoints, and documentation content within 500ms.
- Confirm that the ownership model correctly identifies the responsible team for every registered service and that contact information is current.
- Validate that self-service infrastructure provisioning creates resources with the correct configuration and access controls, and that provisioning failures produce clear error messages.

© rohitg00 · Apache-2.0 · rohitg00/awesome-claude-code-toolkit

Similar subagents

All subagents for DevOps and infrastructure →

From the same set178

The whole set →
database-optimization The database-optimization skill helps inspect query plans and choose indexes for PostgreSQL and MySQL. Use it when tracking down slow queries or reviewing connection and partitioning strategies. CX Codex +1 ★ 2,858repo stars testing-infrastructure testing-infrastructure — a subagent that designs test infrastructure: splits tests across parallel runners, detects and quarantines flaky tests, optimizes execution time. For teams where CI is a bottleneck or tests fail unpredictably. CX Codex ★ 2,858repo stars healthcare-engineer healthcare-engineer designs HIPAA-compliant architectures and HL7 FHIR interfaces. Useful when connecting EHR platforms, mapping clinical vocabularies, or de-identifying records. CX Codex ★ 2,858repo stars continuous-learning The continuous-learning skill turns session corrections and successful approaches into reusable project knowledge. It helps when you want the agent to account for earlier feedback. CX Codex +1 ★ 2,858repo stars websocket-realtime websocket-realtime provides real-time communication patterns for Claude Code, covering raw WebSocket implementations, Socket.io rooms, SSE, and Redis scaling. CX Codex +1 ★ 2,858repo stars monitoring-observability monitoring-observability is a Claude Code skill that adds tracing, metrics, structured logs, and alert rules to Node.js services. It connects application signals to dashboards and SLOs. CX Codex +1 ★ 2,858repo stars database-optimizer database-optimizer — a subagent that diagnoses slow queries, designs indexes, implements partitioning schemes, and plans capacity for PostgreSQL, MySQL, and distributed databases. CX Codex ★ 2,858repo stars accessibility-wcag The accessibility-wcag skill for Claude Code provides WCAG 2.2 patterns for semantic HTML, ARIA dialogs, keyboard navigation, and color contrast. CX Codex +1 ★ 2,858repo stars

Project sponsors

Companies that keep this analytics open