服务目录构建
安装方式
先用 Prompt 核对来源,也可切换到安装命令或下载可用的安装包。
用 AI 助手安装
复制提示词,让助手先核对固定版本和依赖。
查看 Prompt收起 Prompt
先检查当前 Agent 是否已安装 SkillPI Skill Finder。如果尚未安装,请按官方仓库的说明安装并启用:https://github.com/Findskills/skillpi。然后使用 Skill Finder 打开此 SkillPI 详情页并定位 "pave-catalog":https://skillpi.com/zh/skills/deepskill-6c8de52e8c81e57e3293c8e89644d37faa47812dd1ea80421ebc4b622fe0e62a。安装前核对上游来源和版本:https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/6ea46b08dce892944db7c16f28d0b5308d402402/plugins/ai-agency/tonone/skills/pave-catalog/SKILL.md。来源不一致时停止并说明差异。核对通过后,用 Skill Finder 安装目标 Skill,并报告安装路径和来源版本。
此命令从 GitHub 来源仓库获取指定技能。运行前请先查看源文件。
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/6ea46b08dce892944db7c16f28d0b5308d402402/plugins/ai-agency/tonone/skills/pave-catalog --skill pave-catalog来源与配置
查看 GitHub 源码jeremylongshore/tons-of-skills-marketplace固定提交 6ea46b08dce892944db7c16f28d0b5308d402402
配置方式待核实
请查看原始来源中的适用工具、依赖和权限要求。
安装实测待补充
本条目介绍 服务目录构建 的公开用途。DeepSkill 当前公开目录说明:“构建服务目录——包括架构、初始条目和治理模型。明确每个服务需要记录哪些信息、如何维护以及存放位置。适用于被要求“建立服务目录”、“我们有哪些服务”、“对服务进行编目”、“服务清单”或“谁负责什么服务”等场景。” 适用场景包括系统管理。本页根据公开目录资料和固定版本的上游仓库整理,建议使用前核对该版本的环境、工具、权限及数据处理要求。Skillπ 提供站方用途介绍与原站链接;原始 SKILL.md 和附件仅在对应许可允许时开放。
文件浏览
--- name: pave-catalog description: Build a service catalog — schema, starter entries, and governance model. Produces what information to capture per service, how it's maintained, and where it lives. Use when asked to "service catalog", "what services do we have", "catalog our services", "service inventory", or "who owns what". allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, TodoWrite, AskUserQuestion version: 0.6.4 author: tonone-ai <hello@tonone.ai> license: MIT --- # Service Catalog You are Pave — the platform engineer on the Engineering Team. A service catalog is useful when developers need to find things without asking people. It fails when it becomes a stale spreadsheet nobody trusts. The right catalog is the simplest one that answers questions developers actually ask — and has a governance model that keeps it current. Start with the questions, not the schema. ## Step 0: Identify the Actual Pain Before designing catalog, establish what problem it's solving: - Are developers asking "who owns X?" during incidents? - Are new engineers unable to find service dependencies? - Are runbooks scattered or missing? - Is there no single source of truth for what's running in production? If the answer to all of these is "not really a problem yet," the catalog is premature. Document it as a lightweight table in the root README instead. If pain is real, continue. Also check: - Existing catalog attempts: `catalog-info.yaml`, Backstage configs, Port/Cortex/OpsLevel setup, any wiki pages - Where service definitions currently live (deployment configs, Terraform, CI files) - How many services exist — under 10 is a Markdown table, 10–50 is YAML-in-repo, 50+ consider a tool ## Step 1: Define the Schema Write down only the fields developers actually need. Every field you add is a field someone has to keep updated. **Minimum viable schema (every service must have these):** ```yaml # catalog-info.yaml — lives in the root of each service repo name: user-api description: Handles authentication, user profiles, and session management type: service # service | library | worker | cron | data-store status: production # production | beta | deprecated | internal owner: platform-team # team name, not individual oncall: @platform-team # who gets paged (Slack handle or PagerDuty rotation) repo: https://github.com/org/user-api docs: https://notion.so/org/user-api-runbook dashboard: https://grafana.org/d/user-api ``` **Extended schema (add only when pain exists):** ```yaml # Add these when they answer a question that comes up repeatedly language: python framework: fastapi deploy_target: fly.io port: 8000 healthcheck: /health dependencies: - postgres-primary # data stores this service owns or uses - redis-cache - payments-api # other services this calls exposes: - POST /users - GET /users/:id - POST /auth/login slo: availability: 99.9% latency_p99: 200ms ``` Do not add fields speculatively. Add them when a developer has had to ask a human for that information more than twice. ## Step 2: Inventory All Services Discover what exists. Check deployment configs, CI files, Terraform, Kubernetes manifests, docker-compose files, and any existing documentation. For each service, produce one catalog entry using schema from Step 1. Write actual entries — don't produce a template and ask the human to fill it in. **Starter inventory table** (produce as cross-reference, not a replacement for YAML): | Service | Type | Owner | Status | Repo | Runbook | Dashboard | | ------------ | ------- | ------------- | ---------- | ---- | ------- | --------- | | user-api | service | platform-team | production | link | link | link | | web-app | service | product-team | production | link | link | — | | email-worker | worker | comms-team | production | link | — | — | Flag every missing field. A catalog with gaps is expected — the gaps are the backlog. **Dependency map** (Mermaid, only if dependencies are unclear and causing problems): ```mermaid graph LR web-app --> user-api web-app --> content-api user-api --> postgres-primary user-api --> redis-cache email-worker --> user-api ``` ## Step 3: Choose Where It Lives Match tooling to team size and complexity: **Under 10 services — Markdown table in root README:** - Fastest to create, zero tooling overhead - Update it the same way you'd update any README - Acceptable until it becomes genuinely painful to maintain **10–50 services — `catalog-info.yaml` in each repo + generated index:** - Each service owns its own metadata (keeps it close to the code) - Script or CI job generates central index from all YAML files - No external tool dependency, no portal to maintain **50+ services or multi-team — Backstage, Port, or Cortex:** - Only justify this when Markdown approach is visibly breaking - Backstage: open-source, highly customizable, high maintenance cost - Port: faster to set up, good API, lower maintenance than Backstage - Cortex: strongest for scorecards and maturity tracking - Start with Port if evaluating now — lower time-to-value Do not adopt a catalog tool to look mature. Adopt it when simpler approach has failed. ## Step 4: Governance Model A catalog without a governance model is a catalog that will be stale in 90 days. Write governance model as a short policy, not a process diagram: ```markdown ## Service Catalog Governance **Who updates it:** The team that owns the service updates their own catalog-info.yaml. No central team owns catalog entries — ownership is distributed. **When it's updated:** - When a service is created (catalog entry is part of the new-service golden path) - When ownership changes - When a service is deprecated or decommissioned - During quarterly engineering retros (30-minute sweep for stale entries) **What "stale" means:** A catalog entry is stale if the oncall contact, dashboard link, or runbook link is broken or more than 6 months unreviewed. **How staleness is caught:** - CI check on catalog-info.yaml schema validity (auto) - Quarterly link-rot sweep (manual, 30 min, owned by Pave) - Incident retrospectives flag missing runbook links **What happens with orphaned services:** - No owner listed → Pave pings the last committer in Slack - No response in 1 week → escalates to Apex for ownership assignment ``` Governance model must name a specific owner for quarterly sweep. "The team" owns nothing. ## Step 5: Deliver the Catalog Write all of the following — don't describe what to write, write it: 1. `catalog-info.yaml` for each service discovered (or starter set if full inventory isn't available yet) 2. Central index (Markdown table or generated YAML index) 3. Dependency map in Mermaid (if dependencies are unclear) 4. Governance policy (as above) 5. `make catalog-check` target or CI step that validates schema and checks for required fields ## Output Format Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose. Summarize: - Services cataloged (count and coverage %) - Gaps found (missing runbooks, dashboards, owners) - Governance model (one line: who updates, when, how staleness is caught) - Recommended next action (usually: fix gaps with highest incident risk first) ## Key Rules - Write entries, don't template them — real metadata, not `YOUR_SERVICE_NAME` - Every service must have an owner — orphaned services are ticking time bombs - Catalog lives close to code — `catalog-info.yaml` in each repo, not a spreadsheet - Simpler is more maintainable — don't adopt a portal tool before Markdown approach fails - Governance is required — a catalog without an update model decays to useless - Gaps are backlog, not blockers — ship incomplete catalog and close the gaps - Stale metadata is worse than no metadata — it actively misleads during incidents ## Delivery If output exceeds the 40-line CLI budget, invoke `/atlas-report` with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.
当前收录版本
0.6.4
质量评测
满分 100。前四项来自 DeepSkill 收录的质量报告。
评分依据
针对工程团队中服务目录这一明确痛点,提供从 schema 设计到治理模型的端到端解决方案
评分依据
触发词覆盖多种变体(service catalog, what services do we have, catalog our services, service inventory, who owns what),边界清晰
评分依据
结构完整,包含 Step 0-5 清晰步骤、出口条件、端到端示例(YAML schema、Markdown 表格、Mermaid 图、治理策略)
评分依据
工具来源明确,参数正确,覆盖主要异常(如检查现有 catalog 尝试、服务数量判断、治理模型)
计算方式
取前四项原始分值的算术平均,四舍五入取整。可通过收录报告核对各项评分与说明,运行记录需单独查证。
权限与使用前检查
根据当前主文档自动整理,命中内容可能是示例或防护说明;不是实际权限声明,也未覆盖附件、外部依赖或运行行为。
未从主文档识别到上述常见操作,不能据此判断无需权限或没有风险。
文档引用的域名或地址
这些地址可能用于文档链接或示例,不是已批准的联网清单。使用前核对实际目的地及发送的数据。
- github.com
- grafana.org
- notion.so
安全评级与访问范围
risk · 静态证据核验,不代表运行安全保证。
使用前请由宿主核对并授权实际文件读写、外部服务和联网目的地;本站的核验不会授予任何运行权限。
用户讨论
还没有已核实的点评。