Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Design and implement internal developer portals with service catalogs, service discovery, templates, and self-service workflows using Backstage patterns.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
571 lines · 2,019 words
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.
Use this skill when:
User asks about developer portal builder techniques or best practices
Design and implement internal developer portals with service catalogs, service discovery, templates, and self-service workflows using Backstage patterns.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Developer Portal Builder skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
The principle
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.
What it covers
When to Use
Portal Architecture
Software Templates
Service Discovery
TechDocs Integration
Portal Adoption Strategy
Plugin Development
Process
Output Format
Edge Cases
Example
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
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# 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:
- user-api
consumesApis:
- email-api
- notification-api
dependsOn:
- resource:user-database
- component:auth-library| 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 |
# 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:
title: Description
type: string
maxLength: 200
owner:
title: Owner Team
type: string
ui:field: OwnerPicker
ui:options:
catalogFilter:
kind: Group
- title: Technical Options
properties:
javaVersion:
title: Java Version
type: string
enum: ['17', '21']
default: '21'
database:
title: Database
type: string
enum: ['postgresql', 'mysql', 'none']
default: 'postgresql'
includeKafka:
title: Include Kafka Integration
type: boolean
default: false
- title: Repository Settings
required:
- repoUrl
properties:
repoUrl:
title: Repository Location
type: string
ui:field: RepoUrlPicker
ui:options:
allowedHosts:
- github.com
steps:
- id: retrieve
name: Retrieve Template
action: retrieve:template
input:
url: ./skeleton
values:
name: ${{ parameters.name }}
description: ${{ parameters.description }}
owner: ${{ parameters.owner }}
javaVersion: ${{ parameters.javaVersion }}
database: ${{ parameters.database }}
- id: publish
name: Publish to GitHub
action: publish:github
input:
allowedHosts: ['github.com']
repoUrl: ${{ parameters.repoUrl }}
description: ${{ parameters.description }}
defaultBranch: main
protectDefaultBranch: true
- id: register
name: Register in Catalog
action: catalog:register
input:
repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
catalogInfoPath: /catalog-info.yaml
output:
links:
- title: Repository
url: ${{ steps.publish.output.remoteUrl }}
- title: Open in Catalog
icon: catalog
entityRef: ${{ steps.register.output.entityRef }}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| 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 |
# 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]# 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-apiService 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# 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# 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 --strictPhase 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| 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 |
| 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 |
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)# 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: 20
- id: has-alerting
name: Has alerting configured
query: metadata.annotations['pagerduty.com/service-id'] exists
weight: 20
- id: has-ci
name: Has CI pipeline
query: .github/workflows/ci.yml exists
weight: 15
- id: recent-deploy
name: Deployed in last 30 days
query: last_deploy_date > now - 30d
weight: 15
grades:
- grade: A
range: [90, 100]
- grade: B
range: [75, 89]
- grade: C
range: [60, 74]
- grade: D
range: [0, 59]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
## 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]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
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
SKILL.md
571 lines · 2,019 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Developer Portal Builder bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for