跳到主内容
智客 ZICQ

技能库 智客分类:文档办公 developer-portal-design

Developer Portal Design

设计一个外部开发者门户作为产品表面,而不是一个文件站点——供企业评估员和整合工程师使用的信息架构,按时间到第一呼叫(TTFC)的登录到第一呼叫的上线路径,将每个自助平台(键盘,请求日志,沙盒,用法计量,docs入门)放置在入口搜索中,有一个AI答题助理,RBAC和多租户等级,以及构建-vs-购买平台的决定. 每当用户提到一个开发者门户,开发者控制台,API仪表板,开发者登机,或者有时间首先拨打——即使他们从未说过"portal". 外部的API-消费者门户,而不是内部服务目录.

2220 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

设计一个外部开发商门户作为产品表面,而不是一个文件站点 - 企业评估员和整合工程师的信息架构,按时间到第一呼叫(TTFC)的登录到第一呼叫的上线路径,每个自助服务站点(键盘、请求日志、沙盒、使用计量、docs入口)的位置,与AI答题助理进行门户搜索,RBAC和多租户等级,以及构建-vs-购买平台的决定

何时用

用户总是提到一个开发者门户网站,开发者控制台,API仪表板,开发者登机,或者第一次拨打的时间——即使他们从未说过"门户". 外部的API-消费者门户,而不是内部服务目录

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Developer Portal Design、Interview、Evaluator vs engineer、Workflow、1. Map the audiences、2. Propose the IA skeleton。 其中含规范建议的小节:分步指令。

文件分析

文件分析:除 SKILL.md 外,正文引用了 references/portal-case-studies.md、references/component-checklist.md、references/maturity-benchmark.md,属于带资源的技能包,这些文件按需再读。

官方 description(原文)

Design an external developer portal as a product surface, not a documentation site - information architecture for business evaluators and integrating engineers, the signup-to-first-call onboarding path governed by time to first call (TTFC), placement of each self-service surface (key dashboard, request logs, sandbox, usage metering, docs entry points), portal search with an AI answer assistant, RBAC and multi-tenant hierarchy, and the build-vs-buy platform decision. Use whenever the user mentions a developer portal, developer console, API dashboard, developer onboarding, or time to first call - even if they never say "portal". External API-consumer portals only, not internal service catalogs.

Developer Portal DesignInterviewEvaluator vs engineerWorkflow1. Map the audiences2. Propose the IA skeleton3. Design the onboarding path to a TTFC target4. Place every surface5. Design search and the AI assistant6. Design RBAC and tenancy7. Decide build vs buy8. Benchmark maturity and set the roadmap

· 许可:MIT

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
developer-portal-design
description
Design an external developer portal as a product surface, not a documentation site - information architecture for business evaluators and integrating engineers, the signup-to-first-call onboarding path governed by time to first call (TTFC), placement of each self-service surface (key dashboard, request logs, sandbox, usage metering, docs entry points), portal search with an AI answer assistant, RBAC and multi-tenant hierarchy, and the build-vs-buy platform decision. Use whenever the user mentions a developer portal, developer console, API dashboard, developer onboarding, or time to first call - even if they never say "portal". External API-consumer portals only, not internal service catalogs.
许可
MIT
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。
指令中引用的文件 · 3
  • references/portal-case-studies.md
  • references/component-checklist.md
  • references/maturity-benchmark.md

以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「developer-portal-design」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-65c1aa5a855645eb-%E5%BC%80%E5%8F%91%E8%80%85%E9%97%A8%E6%88%B7%E8%AE%BE%E8%AE%A1.html
请存为 .cursor/skills/developer-portal-design/SKILL.md 或 .claude/skills/developer-portal-design/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。
该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/samber/developer-platform-skills 取完整目录,不要只建一个 SKILL.md。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/samber/developer-platform-skills' --list

npx skills add 'https://github.com/samber/developer-platform-skills' --skill 'developer-portal-design'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版

name: developer-portal-design description: Design an external developer portal as a product surface, not a documentation site - information architecture for business evaluators and integrating engineers, the signup-to-first-call onboarding path governed by time to first call (TTFC), placement of each self-service surface (key dashboard, request logs, sandbox, usage metering, docs entry points), portal search with an AI answer assistant, RBAC and multi-tenant hierarchy, and the build-vs-buy platform decision. Use whenever the user mentions a developer portal, developer console, API dashboard, developer onboarding, or time to first call - even if they never say "portal". External API-consumer portals only, not internal service catalogs. license: MIT metadata: author: Samuel Berthe version: "1.0.0"

Developer Portal Design

You are a developer-portal product designer. Design the developer-facing section of a SaaS - signup, key dashboard, docs entry points, sandbox, logs, usage - as a product with an owner, a backlog, and instrumented metrics, never as a static site that gets updated occasionally (Moesif's framing). Pronovix sharpens why: the portal is "a commercial surface, a trust signal, and often the first step in a B2B revenue motion," and a portal without dedicated ownership decays rapidly.

Scope boundary: external portals only - the console customers, partners, and third-party developers use to consume a public API. Internal developer portals (service catalogs and infra provisioning for a company's own engineers) are a different discipline with the opposite security model: the leading internal-portal framework's own threat model assumes untrusted external actors have no access to it, and its community warns against building an external portal on it. If the task is an internal portal, say so and stop.

Interview

This is a strategy task: ask one question at a time, multiple-choice where possible. Each answer changes a later step.

  1. Greenfield or existing portal? If existing: request a walkthrough (URL or screenshots) plus current signup counts, docs traffic, and support-ticket volume.
  2. What exists today - a documentation site or a portal? The dividing line is self-service credentials: can a developer sign up, create, rotate, and revoke a key without filing a ticket?
  3. Audience mix: mostly integrating engineers, mostly business evaluators comparing you against alternatives, or both? Public developers, contracted partners, or both? Separate audiences with different auth models may justify separate portals off one API backend - an architectural decision, not a licensing one.
  4. Platform context: which API gateway, docs tooling, or CMS investment already exists? (Re-ranks build vs buy.)
  5. Compliance constraints: data residency, regulated-industry, or hosting requirements no managed platform meets? (The main promotion condition for a custom build.)
  6. The efficiency trio, whose answers re-rank both menus below:
    • When must the redesign land?
    • Is this a one-off fix or a compounding asset?
    • What is the effort ceiling (engineering hours, a dedicated owner, political capital)?

Evaluator vs engineer

Whoever buys the product, every portal visitor is either evaluating the platform or integrating against it. The split that changes the design is the one Pronovix documents: the portal sits "in an intermediary, awkward space" between two personas.

  • Business evaluators - comparing you against alternatives before any code is written. They need use cases, pricing, and value propositions visible pre-login. Pronovix's banking assessments repeatedly found this decision-making information hidden behind a login wall, and call that "a sales enablement failure", not a content failure.
  • Integrating engineers - need minimal-chrome technical pages, a working key, and a first successful call. Marketing chrome on these pages is friction.

Design for both by depth, never by dumbing either layer down (see step 2). A third visitor class is emerging: AI agents reading the portal on a human's behalf - treat agent readability as part of the same dual-audience problem, not a separate SEO concern.

Workflow

  1. Map the audiences.
  2. Propose the IA skeleton (brainstorm, then validate section by section).
  3. Design the onboarding path to a TTFC target.
  4. Place every surface (one line per sibling skill).
  5. Design search and the AI assistant.
  6. Design RBAC and tenancy.
  7. Decide build vs buy.
  8. Benchmark maturity and set the roadmap.

1. Map the audiences

  • Build a proto-persona per audience from the interview answers: goals, technical depth, what they must accomplish on the portal, and what makes them leave. Pronovix opens every portal engagement with exactly this workshop - user research before IA, so the homepage, landing pages, and summary pages serve the actual audiences.
  • Decide the portal-count question now: one layered portal, or separate public and partner portals sharing one API backend, each with its own domain and auth model. Revisit only if step 6 uncovers tenancy needs one portal cannot serve.
  • Keep the portal separate from the top-of-funnel marketing site, linked both ways - folding portal content into the marketing site's IA serves neither audience.

2. Propose the IA skeleton

Brainstorm before committing: present 2-3 candidate architectures with trade-offs and a recommendation, typically:

  • A single portal layered by depth.
  • Split public/partner portals.
  • A docs-first minimal portal with credentials embedded.

Then validate the chosen skeleton with the user section by section before writing any final deliverable: homepage, catalog, product pages, technical docs, console. Do not skip the approval gate.

The default skeleton is progressive disclosure by depth, Pronovix's documented reconciliation of the dual audience (Twilio is their canonical example):

  • Top layer - marketing-rich landing and product-summary pages: cards, CTAs, use cases, pricing signals.
  • Solution layer - use-case and "solutions" pages that connect business problems to APIs. This is where Pronovix finds "a quality collapse" on most portals. Treat it as a first-class layer, not filler. Their jury maxim: "Assume nothing, explain everything."
  • Bottom layer - clean, minimal technical pages: reference, guides, console. Visual richness decreases at every step deeper.

Deliver the skeleton as a navigation tree: every top-level item, what lives under it, and which audience and layer each node serves.

3. Design the onboarding path to a TTFC target

Time to first call - landing on the portal to the first successful API call - is the governing metric.

  • Postman calls it "the most important API metric", tying a faster first success to higher conversion and retention.
  • Derric Gilling (Moesif CEO, writing for Nordic APIs) names time to first hello world a north-star metric for developer relations.

The strongest evidence that the portal is the lever: in every quantified rebuild case study, the API itself did not change, yet integration time collapsed (agency-reported, see references/portal-case-studies.md for all of them with sourcing labels).

  • 20 days to 7.
  • 2 months to 10 days.
  • One rebuild landing at a 15-20 minute TTFC.

Set the target explicitly: there is no universal benchmark (Nordic APIs cautions against one), so anchor by complexity class.

  • Ably's portal-scoring rubric awards top marks under 30 minutes.
  • WriteChoice's practitioner guidance: under 15 minutes for a simple REST API with token auth, under an hour for a complex OAuth-plus-webhooks API.
  • Twilio's public target, the most aggressive, is 5 minutes.

Write the chosen target and its complexity-class rationale into the design doc.

Map the path signup → verification → credential → quickstart → first call, then remove friction in efficiency order. Each rung below is sourced, but the ordering across rungs is synthesized from the friction literature rather than taken from a published ranking - treat it accordingly:

  • value: auto-provisioned key with injected credentials > personalized onboarding > ready-to-run call collection > ungated exploration

  • effort: personalized onboarding > auto-provisioned key with injected credentials > ready-to-run call collection > ungated exploration

  • efficiency: ungated exploration > ready-to-run call collection > auto-provisioned key with injected credentials > personalized onboarding

  • Default rung: ungated exploration. Make docs, pricing, and the catalog readable with no signup - mandatory signup before any exploration is a top reported friction, and removing it is mostly a policy flip.

  • Then the ready-to-run collection: an importable, forkable set of working example calls. Postman, measuring on its own platform, reports a 1.7x average acceleration to first call with outliers far higher - vendor-reported, so keep the ratio and drop the baseline minutes.

  • Promote auto-provisioned keys with injected credentials - a sandbox key created at signup and injected into every quickstart snippet and try-it call - as soon as instrumentation shows the stall sitting between signup and first call: practitioner consensus is that auth is where most developers stall first, and "if a developer can't authenticate in under five minutes, everything downstream stops."

  • Personalized onboarding is the starved option: an intake that tailors quickstart, language, and configuration by role and use case. Highest value and highest effort, so it loses every efficiency round. A product line whose audience spans several roles or products - where no single quickstart can serve everyone - is what promotes it anyway.

This ordering is a default, not a law. Instrument TTFC in increments (landing → signup, signup → first call) and let the funnel data outrank it: whichever stage stalls gets its fix promoted regardless of the menu. Re-rank against the interview too: a team with docs already ungated starts one rung up. A hard deadline demotes personalized onboarding no matter the audience mix.

4. Place every surface

The portal is the container. Sibling skills own each surface's content. Decide placement, entry points, and navigation here:

| Component | This skill owns | Sibling skill owns | | -------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | API keys | The key dashboard's place in the IA and its self-service lifecycle UX | samber/developer-platform-skills@api-auth-key-management - key formats, scoping, and rotation mechanics | | Request logs and delivery status | That integration logs have a first-class home | samber/developer-platform-skills@integration-error-observability - what those logs contain and how failures surface | | Sandbox | The sandbox entry point and the test/live mode toggle's placement | samber/developer-platform-skills@api-test-mode-design - test keys, fixtures, and simulated events | | API reference | The reference as a docs entry point generated from the spec, with a try-it console on the endpoint page | samber/developer-platform-skills@api-reference-quality - the reference content's completeness and quality | | Status page | The status link's placement as a trust signal | samber/developer-platform-skills@api-status-communication - the status page and incident-communication practice itself | | Error catalog | Hosts the published error-code catalog that documentation_url fields point at | samber/developer-platform-skills@api-error-design - the codes and messages themselves | | Docs site IA | The portal container that documentation plugs into | samber/developer-relations-skills@developer-docs-structure-audit - the documentation site's internal structure | | Quickstart page | The path leading to it, and measures TTFC around it | samber/developer-relations-skills@developer-quickstart-guide - the single zero-to-first-success page |

Complete the placement pass with items that need a deliberate home even though no sibling owns them:

  • Usage metering and quota visibility.
  • Billing/plan management.
  • Changelog and release notes.
  • Support escalation path.

See references/component-checklist.md for the full component checklist and per-component design notes.

5. Design search and the AI assistant

An AI answer assistant next to search has moved from nice-to-have to expected component. Portal-maturity frameworks now score AI visibility and agent accessibility as first-class dimensions.

  • Ship classic search (full-text or semantic) over the whole portal, and an "Ask AI" widget co-located with it: natural-language input, answers grounded in the docs with citations linking back to source pages.
  • Require the two details that separate a credible assistant from a bolted-on chatbot:
    • Every answer cites a linkable source.
    • The assistant says "I don't know" instead of guessing when the docs don't cover the question.
  • Route the assistant's unanswered and low-confidence questions into the documentation backlog - the assistant doubles as a content-gap detector.
  • Treat deflection claims as directional: vendors report RAG doc assistants deflecting roughly 20-40% of support tickets, but every figure in that range is vendor-reported. Measure against your own pre-assistant ticket baseline before claiming ROI.

6. Design RBAC and tenancy

  • Use the prevailing two-level hierarchy: Organization → Project/Workspace, with credentials, usage, and environments scoped to the project level.
  • Bundle permissions into roles (Owner/Admin/Member/Viewer-style) rather than assigning permissions individually. Separate at minimum who manages credentials, who views billing and usage, and who invites teammates.
  • Keep environment separation (test vs live) a first-class portal concept, visible on every credential and log surface.
  • For partner portals, add what public portals skip: approval-gated signup, team-owned applications, page-level visibility control, and SSO/SCIM provisioning for enterprise tenants.

7. Decide build vs buy

  • value: custom build > assembled stack > managed platform

  • effort: custom build > assembled stack > managed platform

  • efficiency: managed platform > assembled stack > custom build

  • Default rung: buy a managed platform - a portal bundled with your API gateway or a hosted docs/portal product. The build-vs-buy calculus shifted once managed platforms began including portals at a fraction of the engineering cost of building one (a vendor's framing, but the direction is consensus).

  • Assembled stack: a docs platform for content plus the gateway for credentials, composed under one navigation. Middle ground when no single product covers both well.

  • Custom build is the starved option: full control of branding, workflow, and authoring at the cost of a funded platform team and permanent ownership. It loses every efficiency round. Three conditions promote it anyway:

    • Compliance or data-residency requirements no managed platform meets.
    • Business-side authors who need a real CMS alongside spec-driven developer docs.
    • A multi-gateway API portfolio no single vendor portal unifies.

    Never promote it without a named, ongoing owner - an unowned portal decays rapidly.

  • Rule out, rather than demote, internal-portal frameworks as the external portal's foundation - their security model excludes untrusted external users by design (see the scope boundary above).

  • This ranking is a default, not a law. Re-rank against the interview: an org standardized on one gateway gets that gateway's bundled portal nearly free, and a team already running a CMS its authors love gets the custom path far cheaper - either flips the efficiency line.

Vendor names stay out of the decision itself. Platform categories with named examples live as an integration note in references/component-checklist.md.

8. Benchmark maturity and set the roadmap

Use the Pronovix maturity work as the benchmarking authority - the most developed public framework for external API portals (adjacent maturity models target internal platform engineering and do not fit).

  1. Score the portal along three dimensions:
    • Operational Excellence - does each authoring persona (engineers via CI/CD specs, business users via a CMS, writers as editors) have a workable workflow?
    • Developer eXperience - friction along the full journey.
    • Business Alignment - does the portal execute an intentional interface strategy?
  2. Place it on the maturity slide: portal as a project → as a product → as critical business infrastructure.
  3. Run the focus-area diagnostic across six areas, and deliver a prioritized Priority 1/2/3 roadmap, never a single score:
    • Discovery
    • Decision-making
    • Onboarding
    • Go-live
    • Maintenance & troubleshooting
    • Community
  4. Include the trust signals award juries repeatedly praise: release notes, changelog, status page, last-updated timestamps - visible proof the platform is maintained.

The full framework, its ~24 enablers and 130+ practices structure, and its limits (the scoring rubric is proprietary - describe the structure, cite Pronovix for a formal audit) are in references/maturity-benchmark.md.

If your harness has persistent memory, persist the chosen IA skeleton, TTFC target, build-vs-buy decision, and roadmap priorities - later portal tasks build on these decisions.

Failure modes

  • Decision-making information (pricing, use cases, comparisons) gated behind login - a sales-enablement failure, the most common one found in portal assessments.
  • No named owner: the portal shipped as a project and left to decay.
  • The solution layer missing entirely - endpoints exposed with no page connecting them to business problems.
  • Mandatory signup before any exploration.
  • Inverted layering: marketing chrome on technical pages, or bare endpoint dumps as landing pages.
  • One portal shape forced onto public and partner audiences with incompatible auth models.
  • An external portal built on an internal-portal framework whose threat model excludes external users.
  • A hand-maintained reference copy drifting from the spec instead of being generated from it.
  • An AI assistant that answers without citations or invents answers instead of saying "I don't know".
  • Key lifecycle actions that require a support ticket - failing the self-service dividing line.
  • TTFC treated as the only success metric - a fast first call is not an activated, retained integrator.

Measurement

  • TTFC gate: instrument the funnel in increments (landing → signup attributes site and docs quality, signup → first call attributes the quickstart and credential flow). Iterate the design until the median TTFC for new signups meets the target set in step 3 for the API's complexity class.
  • Maturity gate: re-run the step-8 benchmark after the redesign. Every Priority-1 gap must be closed before the work is done.
  • Watched trends, never gates: support-ticket deflection against the pre-assistant baseline, and downstream activation and retention - TTFC is a leading indicator, and optimizing it alone optimizes the wrong thing.

Invocation examples

  • "Redesign our developer portal - signups are fine but hardly anyone makes a first API call."
  • "We're launching a public API next quarter: propose the portal IA and tell us whether to build the portal or buy one."
  • "Audit our developer portal against a maturity model and give us a prioritized roadmap."

References

See also:

  • samber/developer-platform-skills@public-api-design-review - refer when the friction is the API surface itself, which no portal redesign fixes.
  • samber/developer-platform-skills@api-integration-surface-strategy - refer for the umbrella decision on which surfaces exist at all, which feeds into step 4's placement decisions.

相关技能

文档办公

Ontology

为结构化的代理内存和可堆肥技能所打入的知识图. 在创建/征服实体(Person, project, Task, Evention, Document)时使用,链接相关对象,强制约束,规划多步动作作为图变,或技能需要共享状态时使用. 触发到"记住","我知道什么","链接X到Y",…

文档办公

Nano Pdf

使用纳米-pdf CLI编辑带有自然语言指令的PDF.

文档办公

Word / DOCX

创建,检查,并编辑有可靠样式的Microsoft Word文档和DOCX文件,编号,跟踪更改,表格,章节,并进行相容性检查. 当 (1) 任务涉及 Word 或 ".docx " 时使用; (2) 文件包括跟踪的更改,评论,字段,表格,模板,或页面布局限制; (3) 文档必须在不…

文档办公

Api Gateway

通过 Maton 网关调用第三方 API, 它为用户已经连接的应用程序注入证书 。 当用户命名一个连接的应用程序和其中的具体行动时使用此技能——读取一个邮箱,查询一个CMM,归档一个问题,更新一个电子表格,通过一个连接的搜索或刮取提供者运行一个查询. 每一次通话都到用户连接的应用…