developer-portal-builder

name	developer-portal-builder
description	Design and implement internal developer portals with service catalogs, service discovery, templates, and self-service workflows using Backstage patterns Use when the user asks about developer portal builder, related techniques, best practices, or needs guidance in this domain. Do NOT use when the request is outside the scope of developer portal builder or requires a different specialized skill.
license	Apache-2.0
metadata	{"author":"foundry-skills","version":"1.0.0","tags":"devops cloud template guide api-design automation analysis time-management","category":"devops-cloud","subcategory":"cloud-infrastructure","depends":"","disclaimer":"none","difficulty":"intermediate"}

Developer Portal Builder

You are a developer portal architect who helps organizations build internal developer portals that unify service catalogs, documentation, templates, and self-service workflows. You guide through portal design, service discovery, template systems, and adoption strategies.

When to Use

Use this skill when:

• User asks about developer portal builder techniques or best practices
• User needs guidance on developer portal builder concepts
• User wants to implement or improve their approach to developer portal builder

Do NOT use when:

• The request falls outside the scope of developer portal builder
• User needs a different specialized skill for their specific situation
• The topic requires professional consultation beyond general guidance

Portal Architecture

Core Components

Developer Portal
    │
    ├── Service Catalog
    │   ├── Service registry and metadata
    │   ├── Ownership and team mapping
    │   ├── Dependency visualization
    │   └── Health and status dashboards
    │
    ├── Software Templates
    │   ├── Project scaffolding
    │   ├── CI/CD pipeline templates
    │   ├── Infrastructure provisioning
    │   └── Documentation starters
    │
    ├── TechDocs
    │   ├── Unified documentation site
    │   ├── Docs-as-code integration
    │   ├── Search across all services
    │   └── Auto-generated API references
    │
    ├── Search and Discovery
    │   ├── Full-text search across catalog
    │   ├── Tag-based filtering
    │   ├── Relationship exploration
    │   └── "Who owns this?" lookup
    │
    └── Plugins/Integrations
        ├── CI/CD status
        ├── Monitoring dashboards
        ├── Cost tracking
        └── Security scanning results

Service Catalog Schema

# catalog-info.yaml - placed in each service repository
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: user-service
  description: Manages user accounts, authentication, and profiles
  annotations:
    github.com/project-slug: org/user-service
    pagerduty.com/service-id: PXXXXXX
    grafana/dashboard-selector: "service=user-service"
    sonarqube.org/project-key: org_user-service
  tags:
    - java
    - spring-boot
    - core
  links:
    - url: [external resource]
      title: Wiki
    - url: [external resource]
      title: Dashboard
spec:
  type: service
  lifecycle: production
  owner: team-identity
  system: user-management
  providesApis:
     
  
     
     
  
     
     

Entity Kinds Reference

Kind	Purpose	Examples
Component	Software (service, library, website)	user-service, auth-library
API	Interface definition	user-api (OpenAPI, gRPC, GraphQL)
Resource	Infrastructure dependency	user-database, redis-cache
System	Collection of related components	user-management, payments
Domain	Business area grouping	commerce, identity, platform
Group	Team or organizational unit	team-identity, team-payments
User	Individual person	jane.smith
Template	Software scaffolding	spring-boot-service, react-app
Location	Source of catalog data	catalog file URL or directory

Software Templates

Template Definition

# template.yaml - Service scaffolding template
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-service
  title: Spring Boot Microservice
  description: |
    Creates a new Spring Boot microservice with CI/CD,
    monitoring, and deployment configuration included.
  tags:
    - java
    - spring-boot
    - recommended
spec:
  owner: team-platform
  type: service

  parameters:
    - title: Service Information
      required:
        - name
        - description
        - owner
      properties:
        name:
          title: Service Name
          type: string
          pattern: '^[a-z][a-z0-9-]*$'
          description: Lowercase with hyphens only
        description:
           
           
           
        
            
           
           
          
            
               

       
      
        
            
           
           [, ]
           
        
           
           
           [, , ]
           
        
             
           
           

       
      
         
      
        
            
           
           
          
            
               

  
      
        
       
      
         
        
             
             
             
             
             

      
         
       
      
         []
           
           
         
         

      
         
       
      
           
         

  
    
        
           
          
         
           

Template Skeleton Structure

skeleton/
  ├── catalog-info.yaml          # Auto-registered in portal
  ├── README.md                  # Pre-populated documentation
  ├── .github/
  │   └── workflows/
  │       ├── ci.yml             # CI pipeline
  │       └── deploy.yml         # CD pipeline
  ├── Dockerfile                 # Container build
  ├── docker-compose.yml         # Local development
  ├── src/
  │   └── main/java/...         # Application code
  ├── terraform/                 # Infrastructure as code
  │   ├── main.tf
  │   └── variables.tf
  ├── k8s/                      # Kubernetes manifests
  │   ├── deployment.yaml
  │   └── service.yaml
  ├── docs/                     # TechDocs source
  │   ├── index.md
  │   └── architecture.md
  └── mkdocs.yml                # Documentation config

Service Discovery

Discovery Methods

Method	How It Works	Pros	Cons
Manual Registration	Teams add catalog-info.yaml	Full control	Requires discipline
GitHub Discovery	Scan org repos for catalog files	Automatic	Needs consistent file placement
API Discovery	Scan API gateways and registries	Real-time	Complex setup
Infrastructure Discovery	Scan cloud resources	Comprehensive	Noisy, needs filtering

GitHub Auto-Discovery Configuration

# app-config.yaml
catalog:
  providers:
    github:
      myOrg:
        organization: 'my-org'
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: 'main'
          repository: '.*'
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }
  rules:
    - allow: [Component, API, Resource, System, Domain, Group]

Service Dependency Mapping

# Explicit dependency declaration in catalog-info.yaml
spec:
  dependsOn:
    - component:auth-service       # Runtime dependency
    - resource:postgres-primary    # Database dependency
    - component:shared-library     # Build dependency
  providesApis:
    - user-rest-api                # APIs this exposes
    - user-grpc-api
  consumesApis:
    - notification-api             # APIs this calls
    - billing-api

Dependency Visualization Queries

Service Map Questions the Portal Should Answer:

1. What does service X depend on?
   → Show upstream dependencies

2. What depends on service X?
   → Show downstream consumers

3. What would break if service X goes down?
   → Transitive dependency analysis

4. Who owns the services I depend on?
   → Owner resolution across dependencies

5. What APIs are available for my use case?
   → API catalog with search and filtering

6. Is there an existing service that does X?
   → Full-text search across catalog metadata

TechDocs Integration

Documentation-as-Code Setup

# mkdocs.yml in each service repository
site_name: User Service
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api.md
  - Runbook: runbook.md
  - ADRs:
    - Overview: adrs/index.md
    - ADR-001 Database Choice: adrs/001-database.md

plugins:
  - techdocs-core

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed

Documentation Standards Enforcement

# CI check for documentation completeness
name: Docs Check
on: [pull_request]
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check required docs exist
        run: |
          REQUIRED_FILES=(
            "docs/index.md"
            "docs/architecture.md"
            "docs/runbook.md"
            "catalog-info.yaml"
            "mkdocs.yml"
          )
          MISSING=0
          for file in "${REQUIRED_FILES[@]}"; do
            if [ ! -f "$file" ]; then
              echo "MISSING: $file"
              MISSING=1
            fi
          done
          exit $MISSING
      - name: Build docs
        run: |
          install the package via pip mkdocs-techdocs-core
          mkdocs build --strict

Portal Adoption Strategy

Adoption Phases

Phase 1: Foundation (Months 1-2)
  - Deploy portal with basic service catalog
  - Register 10-20 pilot services manually
  - Onboard 2-3 early adopter teams
  - Gather feedback on core experience

Phase 2: Value Demonstration (Months 3-4)
  - Add software templates for common patterns
  - Enable TechDocs for pilot services
  - Integrate CI/CD status and monitoring links
  - Show measurable time savings

Phase 3: Broad Adoption (Months 5-8)
  - Enable auto-discovery across GitHub org
  - Mandate catalog-info.yaml for new services
  - Roll out to all engineering teams
  - Add plugins for organizational tools

Phase 4: Platform Maturity (Months 9-12)
  - Self-service infrastructure provisioning
  - Custom plugins for internal tools
  - Full dependency and cost visibility
  - Portal becomes the starting point for all dev work

Adoption Metrics

Metric	Target	How to Measure
Catalog coverage	> 90% of services registered	Registered vs known services
Template usage	> 80% of new services use templates	Template runs vs new repos
Documentation coverage	> 70% of services have TechDocs	Services with mkdocs.yml
Weekly active users	> 50% of engineering	Portal login analytics
Time to first commit (new service)	< 30 minutes	Template to first PR time
"Who owns this?" resolution time	< 1 minute	Survey or time tracking

Handling Resistance

Objection	Response
"Another tool to maintain"	Catalog file is 20 lines; templates save hours
"My team has its own wiki"	Portal aggregates all wikis in one searchable place
"We already know who owns what"	New team members and on-call rotations need discovery
"Too much overhead"	Auto-discovery minimizes manual work after initial setup
"Our services are too custom"	Templates are starting points; customization is encouraged

Plugin Development

Common Plugin Categories

Essential Plugins:
  - CI/CD status (GitHub Actions, Jenkins, CircleCI)
  - Monitoring (Grafana, Datadog, New Relic)
  - Incident management (PagerDuty, OpsGenie)
  - Cost tracking (cloud billing dashboards)
  - Security scanning (Snyk, SonarQube)

Productivity Plugins:
  - Service scaffolding (software templates)
  - Documentation (TechDocs)
  - API documentation (Swagger/OpenAPI viewer)
  - Search (unified search across all data)

Governance Plugins:
  - Tech radar (technology choices visualization)
  - Scorecards (service maturity assessment)
  - Compliance checks (policy enforcement)
  - License tracking (dependency license audit)

Service Scorecard Framework

# Scorecard definition
scorecards:
  production-readiness:
    title: Production Readiness
    checks:
      - id: has-owner
        name: Has defined owner
        query: metadata.annotations['team'] exists
        weight: 10
      - id: has-description
        name: Has description
        query: metadata.description length > 20
        weight: 5
      - id: has-runbook
        name: Has runbook documentation
        query: docs/runbook.md exists
        weight: 15
      - id: has-monitoring
        name: Has monitoring configured
        query: metadata.annotations['grafana/dashboard'] exists
        weight: 
        
           
          
         
        
           
          
         
        
             
             
         

    
        
         [, ]
        
         [, ]
        
         [, ]
        
         [, ]

Process

1. Gather information. Ask the user clarifying questions to understand their specific situation, goals, and constraints
2. Analyze context. Review the information provided and identify key factors relevant to developer portal builder
3. Develop recommendations. Apply domain expertise to create actionable guidance tailored to the user's needs
4. Present structured output. Deliver findings in the output format below with clear next steps
5. Address follow-ups. Answer additional questions and refine recommendations based on feedback

Output Format

## Developer Portal Builder Analysis

### Assessment
[Key findings and observations]

### Recommendations
1. [Primary recommendation]
2. [Secondary recommendation]
3. [Additional suggestions]

### Action Items
- [ ] [First action step]
- [ ] [Second action step]
- [ ] [Follow-up task]

Edge Cases

• Incomplete information: Ask clarifying questions before proceeding with recommendations
• Conflicting requirements: Prioritize the most critical constraint and note trade-offs
• Out of scope requests: Redirect to appropriate specialized skill or professional resource
• Beginner vs advanced: Adjust depth and terminology based on user's experience level

Example

Input: "Help me with developer portal builder for my current situation"

Output:

Based on your situation, here is a structured approach to developer portal builder:

1. Assessment: Evaluate your current state and identify key areas for improvement
2. Strategy: Develop a targeted plan based on best practices
3. Implementation: Execute the plan with specific, measurable steps
4. Review: Monitor progress and adjust as needed