| 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
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
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
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
spec:
dependsOn:
- component:auth-service
- resource:postgres-primary
- component:shared-library
providesApis:
- user-rest-api
- user-grpc-api
consumesApis:
- notification-api
- 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
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
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
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
- Gather information. Ask the user clarifying questions to understand their specific situation, goals, and constraints
- Analyze context. Review the information provided and identify key factors relevant to developer portal builder
- Develop recommendations. Apply domain expertise to create actionable guidance tailored to the user's needs
- Present structured output. Deliver findings in the output format below with clear next steps
- 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:
- Assessment: Evaluate your current state and identify key areas for improvement
- Strategy: Develop a targeted plan based on best practices
- Implementation: Execute the plan with specific, measurable steps
- Review: Monitor progress and adjust as needed
