Service Catalog Entry

Service Catalog Entry Skill

Produce a complete service catalog entry for a microservice or internal platform service — giving any engineer at the company the context they need to understand what the service does, how to depend on it, what its reliability characteristics are, and where to go when something goes wrong. A well-written catalog entry eliminates "who owns this?" and "is this safe to use?" questions that slow down teams depending on shared services.

Required Inputs

Ask for these if not already provided:

• Service name — the canonical identifier used in code, monitoring, and deployments
• Team and owner — team name, tech lead name, and on-call contact
• Architecture overview — what the service does, what calls it, and what it calls
• SLA requirements — availability target, latency SLO, support tier, and maintenance window
• Key APIs — the most important endpoints other teams use (method, path, brief description)
• Data handled — what data the service stores or processes, sensitivity classification, retention

Output Format

Service Catalog: [Service Name]

[One sentence — what this service does for consumers, in plain language]

e.g. "The Payments Service processes charge, refund, and subscription billing events for all Acme products."

Identity

What It Does

[Two to three paragraphs in plain language — no jargon or acronyms without explanation.]

[Paragraph 1: The business problem this service solves. What would break or be missing if this service did not exist?]

[Paragraph 2: How it works at a high level — the main processing model (e.g. request/response API, event-driven consumer, batch processor), what triggers it, and what it produces.]

[Paragraph 3: What this service is NOT responsible for — the explicit boundaries. This prevents other teams from building incorrect assumptions about scope.]

Architecture Context

System Diagram

[Upstream callers]          [This Service]             [Downstream dependencies]
                                                        
  [Web App]  ──────────→                          ──→  [Primary Database — PostgreSQL]
  [Mobile API]  ────────→  [Service Name]         ──→  [Cache — Redis]
  [Partner API] ────────→  (Port 8080/gRPC)       ──→  [Message Queue — Kafka/SQS]
                                                   ──→  [External Service / API]
                           ↓ emits events to
                        [Event Bus / SNS]
                           ↓ consumed by
                  [Downstream Service A]
                  [Downstream Service B]

Who Depends on This Service

What This Service Depends On

Service Level Agreement

Availability and Latency

SLO dashboard: [Link to monitoring dashboard] Current error budget remaining: [Link to SLO dashboard or inline value]

Support Tiers

To raise an incident: Page via [PagerDuty service link] or post in #incidents. To raise a feature request or bug: File a ticket in [JIRA project / GitHub repo Issues].

Maintenance Windows

• Planned downtime: [e.g. "Sundays 02:00–04:00 UTC — advance notice posted to #[team-channel] 48h before"]
• Deployment window: [e.g. "Weekdays 10:00–16:00 UTC — no deploys on Fridays or the day before a public holiday"]
• Breaking changes notice: [e.g. "Minimum 30 days notice for breaking API changes — see versioning policy below"]

API Contract

Authentication

All API calls require: [e.g. "Bearer token via Authorization header. Tokens are issued by the Auth Service (/api/v1/token)"]

Authorization: Bearer [jwt-token]
Content-Type: application/json

Base URL

Key Endpoints

Full API documentation: [OpenAPI/Swagger spec URL] | [Postman collection URL]

Versioning Policy

• API version is in the URL path (/api/v1/, /api/v2/)
• Minor additions (new optional fields, new endpoints) are non-breaking — no version bump
• Breaking changes (removed fields, changed types, authentication changes) require a new major version
• Deprecated versions are supported for [90 days] after the successor reaches GA
• Deprecation notices are posted to #[team-channel] and emailed to registered consumers

Error Response Format

{
  "error": {
    "code": "[ERROR_CODE]",
    "message": "[Human-readable description]",
    "request_id": "[UUID — include in support tickets]",
    "details": {}
  }
}

Common error codes:

Events Published (if event-driven)