samber/developer-platform-skills已通過檢查
SKILL DETAIL
developer-portal-design
samber/developer-platform-skills/developer-portal-design
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.
安裝量 · 331查看來源
Installation
npx skills add https://github.com/samber/developer-platform-skills --skill developer-portal-design
技能檔案
SKILL.md
最近同步 · 2026年10月23日
evals/evals.json›
{
"skill_name": "developer-portal-design",
"evals": [
{
"id": 1,
"prompt": "I run the platform team at Ledgerwell, we sell a bank reconciliation API. Last quarter we had 1,840 developer signups and only 212 of them ever made a successful API call. Our auth is OAuth2 and settlement events come back over webhooks, so an integration isn't trivial. Docs, the catalog and pricing are already fully public, no login needed. The board wants movement by the March 15 review, so about six weeks, and I can borrow two engineers part-time. What do we fix, and in what order?",
"expected_output": "A prioritized friction-removal plan governed by an explicit time-to-first-call target set for a complex OAuth-plus-webhooks API, with funnel instrumentation, the already-ungated rung skipped, and personalized onboarding demoted on deadline grounds.",
"files": [],
"expectations": [
"Names time to first call (TTFC) as the governing metric for this work and sets an explicit target figure for Ledgerwell.",
"Anchors that target to the API's complexity class - OAuth plus webhooks - landing near an hour rather than a sub-15-minute figure.",
"States that no universal TTFC benchmark exists, instead of presenting one number as an industry standard.",
"Recommends instrumenting TTFC in increments, at minimum landing-to-signup and signup-to-first-call, rather than as a single end-to-end number.",
"States that the funnel data, once instrumented, outranks the default ordering of fixes: whichever stage stalls gets its fix promoted.",
"Recognizes that docs, catalog and pricing are already ungated, so the ungated-exploration rung is already satisfied and the work starts further up the ladder.",
"Recommends shipping an importable, forkable, ready-to-run collection of working example calls.",
"Recommends auto-provisioned sandbox keys injected into quickstart snippets and try-it calls as the fix for a stall sitting between signup and first call.",
"Explicitly demotes or defers role-and-use-case personalized onboarding intake, tying that to the six-week deadline and the part-time engineering capacity.",
"Any first-call acceleration figure attributed to a ready-to-run collection is expressed as a ratio of roughly 1.7x, labeled vendor-reported, with no baseline minute count carried over.",
"Warns that TTFC is a leading indicator only, and names downstream activation or retention as a trend to watch alongside it."
]
},
{
"id": 2,
"prompt": "We already run Backstage internally - around 90 services in the catalog, our platform team maintains it and knows it well. Leadership now wants our 40 contracted integration partners to get self-serve API keys and technical docs, and the obvious move seems to be opening that same Backstage instance up to them with an external auth layer in front. Can you sketch the plugin architecture and the partner-facing navigation we'd need?",
"expected_output": "A refusal to design the requested external surface on the internal framework, with the threat-model reason, and a recommendation to stand up a separate external portal with partner-grade access controls.",
"files": [],
"expectations": [
"Declines to produce the requested plugin architecture and partner-facing navigation built on the internal service-catalog framework.",
"Gives the security reason: that framework's threat model assumes untrusted external actors have no access to it.",
"States that this option is ruled out entirely, not merely ranked lower, deferred, or made conditional on extra hardening.",
"Recommends running a separate external developer portal alongside the internal instance rather than converting or exposing the internal one.",
"Distinguishes an internal developer portal (service catalog, infrastructure provisioning for a company's own engineers) from an external API-consumer portal as different disciplines with different security models.",
"Identifies the self-service credential lifecycle - sign up, create, rotate and revoke keys without filing a ticket - as what the external partner surface must deliver.",
"Names partner-specific requirements the external portal needs, including at least two of: approval-gated signup, team-owned applications, page-level visibility control, SSO/SCIM provisioning.",
"Does not present exposing the internal instance as a viable path if the external auth layer is strong enough."
]
},
{
"id": 3,
"prompt": "Kestrel Freight is launching a public shipment-tracking API in Q3. Today developers get a PDF spec emailed to them. I need to know what the developer section of kestrelfreight.com should actually look like. Our buyers are logistics ops directors who compare us against two competitors before anyone technical is involved, and then either their in-house devs or an outside systems integrator does the build. Give me the page structure.",
"expected_output": "Proto-personas for both audiences, two or three candidate architectures with a recommendation and an explicit section-by-section validation gate, then a depth-layered navigation tree with a first-class solution layer and ungated decision-making content.",
"files": [],
"expectations": [
"Builds distinct proto-personas for the business evaluator (logistics ops director) and the integrating engineer or systems integrator, covering what each must accomplish on the portal.",
"Presents at least two candidate portal architectures with trade-offs rather than a single structure, and names one as the recommendation.",
"States that the chosen skeleton will be validated with the user section by section before any final deliverable, rather than treating the structure as settled.",
"Recommends a structure layered by depth, with visual and marketing richness decreasing as pages get more technical.",
"Includes a distinct solution or use-case layer connecting business problems to APIs, sitting between the marketing-rich pages and the technical reference.",
"Treats that solution layer as first-class rather than optional filler.",
"States that pricing, use cases and competitive/decision-making material must be readable before login.",
"Names gating decision-making information behind a login wall as a sales-enablement failure, not merely a content or UX shortcoming.",
"Keeps marketing chrome off the technical reference and console pages.",
"Keeps the portal distinct from the top-of-funnel marketing site while linking the two in both directions, rather than folding portal content into the marketing site's IA.",
"Delivers the structure as a navigation tree naming every top-level item and what sits beneath it.",
"Labels each node with the audience and/or the layer it serves."
]
},
{
"id": 4,
"prompt": "Our developer portal at Nimbus Telemetry has been live about three years. It has an OpenAPI reference, a key dashboard, a getting-started guide and a support email address. No changelog, no status page, and honestly nobody owns it - docs get updated when an engineer happens to notice something wrong. My VP wants to know 'where we stand' before she approves headcount for it. Score it and tell her what it would take to reach the next level.",
"expected_output": "A three-dimension assessment placed on the project/product/infrastructure progression, a six-focus-area diagnostic, and a Priority 1/2/3 roadmap that refuses to collapse into a single score, with the missing owner and trust signals as Priority 1 gaps.",
"files": [],
"expectations": [
"Scores the portal along three named dimensions covering authoring-workflow quality (operational excellence), journey friction (developer experience), and intentional interface strategy (business alignment).",
"Places the portal on a three-stage progression running portal-as-a-project, portal-as-a-product, portal-as-critical-business-infrastructure.",
"Refuses to reduce the assessment to a single maturity score or a fixed 1-to-5 level, and says why.",
"Delivers the output as a prioritized Priority 1 / Priority 2 / Priority 3 roadmap.",
"Runs a focus-area diagnostic spanning discovery, decision-making, onboarding, go-live, maintenance and troubleshooting, and community.",
"Flags the absent changelog or release notes and the absent status page as missing maintained-platform trust signals.",
"Recommends visible last-updated or last-change timestamps on portal content as a further trust signal.",
"Names the absent owner as a Priority 1 gap and ties an unowned portal to rapid decay.",
"Checks whether each authoring persona - engineers pushing specs through CI/CD, business-side authors, technical writers as editors - has a workable workflow, instead of assuming one authoring workflow serves all of them.",
"Describes the benchmarking framework's structure rather than inventing a numeric scoring formula or enabler weightings for it.",
"Does not substitute an internal-developer-platform or platform-engineering maturity model for the external-portal assessment."
]
},
{
"id": 5,
"prompt": "Halcyon Payroll. We're deciding how to stand up the API developer site for our public API. Our head of design is adamant we control every pixel and don't end up looking like a templated vendor site. Separately, our content marketing team lives in our existing CMS and wants to publish integration guides and customer stories without filing an engineering ticket every time. We run everything through a single API gateway across all four of our products. I have two contractors available for a 10-week window. Do we build it ourselves or buy something?",
"expected_output": "Managed platform as the stated default with the ranking made explicit, branding rejected as a promotion reason, CMS authoring accepted as one, the single-gateway fact weakening the custom case, and a named permanent owner demanded before any build is approved.",
"files": [],
"expectations": [
"States that the default recommendation is buying a managed platform - a gateway-bundled portal or a hosted docs/portal product - rather than building.",
"States the ranking across the options explicitly as a value, effort and efficiency ordering instead of leaving it implied by the order of discussion.",
"Rejects branding and pixel-level control on its own as a sufficient reason to promote a custom build.",
"Identifies the content team's CMS authoring need as a genuine promotion condition for the custom path.",
"Names the full set of custom-build promotion conditions: compliance or data-residency requirements no managed platform meets, business-side authors needing a real CMS alongside spec-driven docs, and a multi-gateway API portfolio no single vendor portal unifies.",
"Points out that Halcyon runs a single gateway across all products, so that gateway's bundled portal comes nearly free and the multi-gateway argument does not apply here.",
"Names the assembled-stack middle option: a docs platform for content composed with the gateway for credentials under one navigation.",
"Requires a named, ongoing owner as a precondition before any custom build is approved.",
"Flags that two contractors on a 10-week window do not constitute that permanent owner.",
"Warns that an unowned portal decays rapidly.",
"Frames the decision by platform category rather than resolving it to one specific named vendor product."
]
},
{
"id": 6,
"prompt": "Docs team at Verdanta Analytics. We take roughly 400 support tickets a month and my rough read is 60% are 'how do I' questions already answered somewhere in our docs. Leadership greenlit an AI chat widget for the docs site and asked me to put a number in the business case for how many tickets it removes. We have about 900 docs pages and a working search box already. What do I tell them, and how should we build the thing?",
"expected_output": "A refusal to forecast a deflection percentage, with the vendor-reported range framed as directional, a pre-assistant baseline captured first, and an assistant spec requiring citations, an explicit I-don't-know fallback, and a gap-detection loop.",
"files": [],
"expectations": [
"Declines to commit a specific deflection percentage as a forecast in the business case.",
"States that published deflection figures around the 20-40% range are vendor-reported and directional only.",
"Requires measuring against Verdanta's own pre-assistant ticket baseline before claiming ROI, and recommends capturing that baseline before launch.",
"Keeps the existing classic full-text or semantic search rather than replacing it with the assistant.",
"Co-locates the Ask AI widget with the search box.",
"Requires every assistant answer to cite a linkable source page.",
"Requires the assistant to say it does not know rather than guess when the docs do not cover a question.",
"Routes unanswered and low-confidence questions into the documentation backlog, using the assistant as a content-gap detector.",
"Treats support-ticket deflection as a watched trend rather than a gate the project passes or fails on."
]
},
{
"id": 7,
"prompt": "Sable Grid sells an energy-metering API. Two groups use it: about 2,000 self-serve developers who come through our public signup, and 35 contracted utility partners whose legal teams require SSO and whose access we have to approve before it's granted. Right now everyone gets one login with a role of either 'admin' or 'member', and one API key per account. Customers keep asking for separate test credentials, and for their finance people to be able to see spend without being able to see keys. Design the account model for us.",
"expected_output": "A two-level organization-to-project hierarchy with credentials and usage scoped to the project, bundled roles that split credential management from billing visibility, first-class test/live separation, partner-grade access controls, and the one-portal-versus-two question raised as an architectural decision.",
"files": [],
"expectations": [
"Proposes a two-level hierarchy of organization to project (or workspace).",
"Scopes credentials, usage and environments to the project or workspace level rather than to the account or organization level.",
"Bundles permissions into named roles rather than assigning permissions to users individually.",
"Separates at minimum who manages credentials, who views billing and usage, and who invites teammates - answering the finance-visibility request without granting key access.",
"Makes test-versus-live environment separation a first-class portal concept rather than a naming convention on keys.",
"Makes the environment marker visible on log and usage surfaces, not only on the credential list.",
"Adds approval-gated signup for the contracted utility partners.",
"Adds SSO and SCIM provisioning for the enterprise partner tenants.",
"Adds partner-side controls beyond the public tier, including at least one of: team-owned or team-shared applications, page-level visibility permissions, a viewer-versus-consumer role split.",
"Raises the one-portal-versus-two question explicitly for the public and partner audiences, noting separate portals can share one API backend.",
"Frames that separate-portal question as an architectural decision rather than a licensing or vendor-packaging one."
]
},
{
"id": 8,
"prompt": "Orrery Labs, transactional email API. Our docs live on one subdomain, the dashboard where you get a key is on a different one, and if a customer wants to know why a send failed they email support and someone on our side greps logs for them. We're consolidating all of it into one place over the next two quarters. Here's my list so far: reference docs, quickstart, key management, sandbox. What am I missing, and where does everything go?",
"expected_output": "A placement pass that gives integration logs a self-service home, adds the four unowned surfaces (usage/quota, billing, changelog, support escalation), places the status link, error catalog, sandbox toggle and try-it console, and keeps its scope at placement rather than per-surface content design.",
"files": [],
"expectations": [
"Gives request, event or delivery logs a first-class self-service home in the portal instead of leaving failure investigation to a support handoff.",
"Names usage metering and quota visibility as a surface needing a deliberate home.",
"Names billing or plan management as a surface needing a deliberate home.",
"Names a changelog or release-notes surface.",
"Names a support escalation path as a placed surface.",
"Places a status-page link in the portal and frames it as a trust signal.",
"Places the published error-code catalog in the portal as what error responses' documentation_url fields point at.",
"Places the sandbox entry point together with a visible test-versus-live mode toggle.",
"Puts the try-it console on the endpoint page itself rather than as a separate tool the developer leaves the docs to open, with the signed-in developer's own key injected into it and into the code snippets.",
"Requires the API reference to be generated from the spec rather than hand-maintained as a parallel copy that drifts.",
"Scopes its own answer to placement, entry points and navigation, deferring the internal content design of individual surfaces rather than specifying it here."
]
}
],
"trigger_queries": [
{
"query": "Our developer portal reads like a documentation site - help me redesign it",
"should_trigger": true
},
{
"query": "How should we lay out the developer console for our new public API?",
"should_trigger": true
},
{
"query": "Signups look healthy but almost nobody ever makes their first API call",
"should_trigger": true
},
{
"query": "What should time to first call be for a payments API with OAuth and webhooks?",
"should_trigger": true
},
{
"query": "Should we build our developer hub ourselves or buy one?",
"should_trigger": true
},
{
"query": "We want an Ask AI box next to search on our docs and console",
"should_trigger": true
},
{
"query": "Design the information architecture for the part of our site where customers get API keys",
"should_trigger": true
},
{
"query": "Audit our API developer experience against a maturity model and tell us where we stand",
"should_trigger": true
},
{
"query": "Our API pricing page sits behind the login wall - is that actually a problem?",
"should_trigger": true
},
{
"query": "Do we need one portal for public developers and a second one for contracted partners?",
"should_trigger": true
},
{
"query": "Where should request logs live for the people integrating with us?",
"should_trigger": true
},
{
"query": "Plan the journey from signup to first successful call",
"should_trigger": true
},
{
"query": "What's a realistic TTFC target for a simple REST API with token auth?",
"should_trigger": true
},
{
"query": "our developer experience site has no owner and no roadmap, what do I do",
"should_trigger": true
},
{
"query": "We're launching a public API next quarter - what pages do developers actually need?",
"should_trigger": true
},
{
"query": "How do I organize the self-serve area where devs create, rotate and revoke keys?",
"should_trigger": true
},
{
"query": "customers tell us they can't work out what our API even does before they sign up",
"should_trigger": true
},
{
"query": "give me a prioritized roadmap for our API developer site",
"should_trigger": true
},
{
"query": "What org and project hierarchy should our API console use?",
"should_trigger": true
},
{
"query": "Is Backstage a reasonable base for the site our external partners log into?",
"should_trigger": true
},
{
"query": "What belongs on the landing page for developers versus on the reference pages?",
"should_trigger": true
},
{
"query": "We want AI agents to be able to read and navigate our API docs and console on a customer's behalf",
"should_trigger": true
},
{
"query": "how do we shorten the gap between landing on our site and a working API call",
"should_trigger": true
},
{
"query": "Our API is solid but integrations still take customers three weeks",
"should_trigger": true
},
{
"query": "Should the sandbox and live toggle sit in the global nav or on each page?",
"should_trigger": true
},
{
"query": "Design the console our API customers log into",
"should_trigger": true
},
{
"query": "benchmark our developer hub against best-in-class and tell me the gaps",
"should_trigger": true
},
{
"query": "Where do we surface usage and quota information for API customers?",
"should_trigger": true
},
{
"query": "we keep getting support tickets from customers just asking for API keys",
"should_trigger": true
},
{
"query": "Map out the developer onboarding path for our new platform",
"should_trigger": true
},
{
"query": "what does a mature API developer site look like compared to ours",
"should_trigger": true
},
{
"query": "Restructure the developer-facing part of our SaaS product",
"should_trigger": true
},
{
"query": "our partners need us to approve them before they get access - how should that part of the site work?",
"should_trigger": true
},
{
"query": "what's a good time to first hello world metric for our API and who owns it",
"should_trigger": true
},
{
"query": "Developers land on our reference and bounce - what's missing in between?",
"should_trigger": true
},
{
"query": "help me argue internally that the developer-facing site is a product, not a one-off project",
"should_trigger": true
},
{
"query": "should we put a try-it button on every endpoint page and where does the key come from?",
"should_trigger": true
},
{
"query": "how do we structure a developer hub that serves both buyers and engineers",
"should_trigger": true
},
{
"query": "What key format should we use - prefix plus checksum, and hashed or encrypted storage?",
"should_trigger": false
},
{
"query": "Design our zero-downtime key rotation mechanics and least-privilege scoping rules",
"should_trigger": false
},
{
"query": "Write our error-code taxonomy using the RFC 9457 problem-details envelope",
"should_trigger": false
},
{
"query": "How should we signal which errors are retryable, and set Retry-After?",
"should_trigger": false
},
{
"query": "Design idempotency-key storage TTL and our replay window",
"should_trigger": false
},
{
"query": "Which integration surface should we build first, GraphQL or an MCP server?",
"should_trigger": false
},
{
"query": "Set our rate-limit tiers, burst allowance and the headers we publish",
"should_trigger": false
},
{
"query": "Audit every endpoint in our reference for missing response codes and snippet parity",
"should_trigger": false
},
{
"query": "How granular should the components on our status page be, and what does 'degraded' mean?",
"should_trigger": false
},
{
"query": "Design magic test values and simulated events for our sandbox",
"should_trigger": false
},
{
"query": "Should we use date-based account-pinned versioning or a URI path version?",
"should_trigger": false
},
{
"query": "Plan the founding launch cohort and partner embargoes for our app marketplace",
"should_trigger": false
},
{
"query": "Write the screenshot specs and description quality bar third-party listings must meet",
"should_trigger": false
},
{
"query": "What revenue share and program fees should our app marketplace charge?",
"should_trigger": false
},
{
"query": "Design the security review and approval pipeline for third-party apps on our marketplace",
"should_trigger": false
},
{
"query": "Parquet file drops on object storage or Delta Sharing for our bulk exports?",
"should_trigger": false
},
{
"query": "Should we build our own integration marketplace or just join other people's?",
"should_trigger": false
},
{
"query": "What does an API product manager earn and how do I move into that track?",
"should_trigger": false
},
{
"query": "Write the interview loop and scorecard for a partner integration engineer",
"should_trigger": false
},
{
"query": "Which language SDKs should we ship first, and generated or handwritten?",
"should_trigger": false
},
{
"query": "Design our outbound webhook signing scheme and dead-letter policy",
"should_trigger": false
},
{
"query": "Set up PKCE and refresh-token rotation on our OAuth authorization server",
"should_trigger": false
},
{
"query": "Design our JDBC endpoint with row-level security and per-tenant compute isolation",
"should_trigger": false
},
{
"query": "Curate the tool surface for our MCP server instead of mirroring every endpoint",
"should_trigger": false
},
{
"query": "Review our REST URI naming, status codes and pagination pattern",
"should_trigger": false
},
{
"query": "Set depth and complexity ceilings on our public GraphQL schema",
"should_trigger": false
},
{
"query": "Should our gRPC surface be public, or transcoded to JSON at the gateway?",
"should_trigger": false
},
{
"query": "Restructure the content hierarchy inside our documentation site - concepts, guides, reference",
"should_trigger": false
},
{
"query": "Write the zero-to-first-success quickstart page itself",
"should_trigger": false
},
{
"query": "Find and rank the keywords our developer blog should target",
"should_trigger": false
},
{
"query": "Map our developer journey from first awareness through to advocacy",
"should_trigger": false
},
{
"query": "How do we get our documentation pages ranking in search results?",
"should_trigger": false
},
{
"query": "Plan the launch of our developer Discord and its moderation rules",
"should_trigger": false
},
{
"query": "Write the troubleshooting docs for the ten integration errors we see most",
"should_trigger": false
},
{
"query": "Set up an internal service catalog so our own engineers can find and own services",
"should_trigger": false
},
{
"query": "Design golden paths and scaffolding templates for our platform engineering team",
"should_trigger": false
},
{
"query": "Improve the view-to-install conversion on our Salesforce AppExchange listing",
"should_trigger": false
},
{
"query": "Design per-partner failure alerting with cooldowns so we don't spam them",
"should_trigger": false
}
]
}
references/component-checklist.md›
# Portal component checklist and design notes
Vendor names below are citations and integration notes, never requirements - every pattern is achievable on whichever platform the team runs.
## Core component set
The consolidation payoff (DigitalAPI's framing): without a portal, teams stitch together a docs tool, a key-management spreadsheet, a sandbox, a ticket queue, and a finance handoff. The portal connects discovery, testing, access, subscriptions, and analytics in one surface.
- API catalog (with search - for multi-gateway orgs, a gateway-agnostic catalog auto-synced from each gateway's admin API avoids a fragmented per-gateway experience)
- Authentication and self-service key management
- Interactive documentation (reference generated from the spec, try-it console on the endpoint page)
- Sandbox / test-mode entry with a visible test-vs-live toggle
- Usage dashboards, quota visibility, and overage alerts per developer
- Governance controls: RBAC, approval flows, quotas
- Changelog / release notes, status-page link, support escalation path (the maintained-platform trust signals)
- Billing and plan management when the API is monetized
**The dividing line between a docs site and a portal is the self-service credential lifecycle**: sign up, create, rotate, and revoke keys without filing a ticket. Some documentation-focused products deliberately stop short of this - if the product being designed has no credential lifecycle, it is a documentation site, and this skill's portal-level advice applies only partially.
## Self-service credential lifecycle - UX patterns (lifecycle UX only, key mechanics belong to the auth sibling skill)
- **Scoping at creation**: let the creator pick restricted, least-privilege permissions when the key is created, not afterwards (Stripe's restricted keys are the reference implementation).
- **Test and live keys as parallel pairs** on one dashboard with a mode toggle, prefixed so environment is readable from the key itself.
- **Zero-downtime rotation via an overlap window**: old and new keys both work during a bounded transition (Stripe allows up to 7 days, practitioner guidance is a few hours), so migration is gradual. Immediate expiration is reserved for confirmed compromise. Key names persist across rotation.
- **Expiration chosen at creation** with org-level maximum-lifetime policies (GitHub's fine-grained tokens are the reference: expiration is mandatory at creation, admins can cap lifetimes, tokens unused for a year are auto-removed, and "never used" is surfaced as a deletion signal).
- **Audit hygiene**: show last-used timestamps. Flag or limit long-unused keys with a dashboard restore path.
- **Programmatic lifecycle events**: webhooks notifying integrating apps of rotation and expiration, where the platform supports it.
## Try-it console requirements
- Native integration on the endpoint page - never a separate tool the developer must leave the docs to open.
- Auto-populated auth: the signed-in developer's own key injected into the console and into every code snippet.
- Multi-language, copy-paste-and-run code samples generated from the spec.
- Docs kept in sync with the spec via automation. A hand-maintained parallel copy will drift.
- Realistic environment handling: the console targets the sandbox by default, with the mode toggle visible.
Integration note - the console tool landscape, roughly ascending in interactivity and cost:
- Spec-rendered consoles you host yourself: Swagger UI, Scalar (adds polish and multi-language snippet generation), Stoplight Elements (embeds in an existing shell).
- Read-only three-panel references: open-source Redoc, no live runner.
- Hosted developer hubs with credential-injected explorers and per-developer request logs: ReadMe, Mintlify.
- Collection-based interop: Postman collections as a de-facto import/export standard, forkable via public workspaces.
## RBAC and tenancy patterns
- Two-level hierarchy is the prevailing model: Organization → Project/Workspace (OpenAI, Kong Konnect). Keys, files, and usage scope to the project.
- Roles bundle permissions (Owner/Admin/Member/Viewer tiers). Groups of users can be synced from an identity provider via SCIM for enterprise tenants.
- Partner-portal specifics: approval-gated signup (configurable), team-owned and team-shared applications, viewer-vs-consumer role split (may view the catalog vs may register and hold credentials), page-level visibility permissions, one API publishable to several portals under centralized RBAC.
- Environment separation (dev/staging/prod or test/live) as a first-class concept on every credential, log, and usage surface.
## Search and AI assistant pattern
The recurring implementation across vendors:
- An "Ask AI" widget co-located with the search box.
- Natural-language input.
- Answers grounded in the docs with inline citations linking to source pages.
- An explicit "I don't know" fallback instead of guessing.
- Analytics surfacing unanswered and low-confidence questions as a documentation backlog.
A deflection maturity ladder (DevRev's framing - vendor-sourced, use for orientation only):
- Static FAQ and keyword search: roughly 10-20% of tickets.
- Rule-based bots: 30-50%.
- Conversational RAG assistants: higher still.
Third-party and vendor estimates place RAG doc-assistant deflection broadly at 20-40%. All of these are vendor-reported - validate against your own pre-assistant ticket baseline.
Integration note - assistant vendors in current use:
- Docs platforms with built-in assistants and `llms.txt`/MCP generation: Mintlify.
- Search-native generative layers: Algolia AskAI.
- Purpose-built RAG answer engines deployable as widget, in-app chat, community bot, or API: kapa.ai, Inkeep.
## Build-vs-buy platform categories
Integration note only - the decision logic lives in the SKILL.md workflow:
- **Gateway-bundled portals**: developer portals shipped as part of an API management platform. Best when the org already runs, or is choosing, that gateway.
- Kong Konnect Dev Portal.
- Google Apigee's integrated portal, with a CMS-based Drupal distribution as its customizable variant.
- Zuplo, which bundles a portal on every tier including free.
- **Hosted docs/developer-hub platforms**: ReadMe, Mintlify, Fern and peers - strong on docs, try-it, and AI assistance. Credential lifecycle depth varies, sometimes composed with the gateway.
- **CMS-based custom portals**: built on a CMS so business-side authors get real authoring workflows while engineers push specs via CI/CD (the pattern Pronovix builds on Drupal). This is the custom-build path - it requires a funded, permanent owner.
- **Internal-portal frameworks (excluded)**: Backstage-class frameworks are for internal service catalogs. Their threat model assumes no untrusted external access, standing one up takes months of platform-team work, and the community consensus is not to build an external portal on one. If the org uses one internally, pair it with a separate external portal rather than exposing it.
Third-party pricing figures for these platforms circulate widely but mostly originate from competing vendors. Treat any specific contract number as unofficial and re-verify with the vendor at decision time.
references/maturity-benchmark.md›
# Portal maturity benchmarking (Pronovix framework)
Pronovix - a consultancy describing itself as the only one fully dedicated to researching, designing, building, and auditing developer portals - publishes the most developed public benchmarking framework for external API portals. No competitor matches its public depth. Use it as the benchmarking authority. Its work spans three linked artifacts.
## The three-dimensional maturity model (Kristof Van Tomme, 2020, updated 2022)
Business value grows along three independent dimensions, not one linear scale:
1. **Operational Excellence** - how well the portal serves its _authoring_ personas: engineers pushing OpenAPI specs via CI/CD, business users authoring through a CMS, technical writers as editors. The named anti-pattern is forcing every author type through one workflow.
2. **Developer eXperience** - friction removal along the full API journey, plus the trust signals that inform integration-investment decisions.
3. **Business Alignment** - whether the portal executes an intentional interface strategy that drives revenue, adoption, and cross-team collaboration.
The dimensions map to a three-stage slide a portal moves along over time: **portal as a project → portal as a product → portal as critical business infrastructure**.
## The DevPortal Awards (since 2018) - trust signals from jury observations
A vendor-neutral awards program judged by an independent expert jury, with categories organized under the three dimensions (best onboarding, best findability, best use of analytics, best served API business model...). The jury's recurring observations double as a checklist: **release notes, status pages, changelogs, and last-change timestamps** are repeatedly praised as signals that the platform is well maintained. Include them in any portal audit even outside an awards context.
## The focus-area diagnostic (2025-2026, Pronovix's newest instrument)
A three-step methodology:
1. **Map** the user's goals across **6 focus areas**: Discovery, Decision-making, Onboarding, Go-live, Maintenance & troubleshooting, Community.
2. **Analyze** using roughly two dozen enablers (e.g. "visual harmony", with concrete practices like "consistent look and feel") and more than 130 practices in total. Scoring supports a bird's-eye spiderweb view across focus areas and drill-down to individual practice level.
3. **Benchmark** against a best-in-class standard or named competitors.
Pronovix explicitly rejects a simple 5-6 level maturity scale in favor of a continuum, packaged as a **prioritized Priority 1/2/3 roadmap - never a single maturity score**. Deliver your own benchmark output in the same shape.
Their 2026 banking-sector application added two lenses worth carrying into any audit:
- **Hybrid User Experience lens** - the same portal serves human visitors and AI-agent visitors.
- **AI Visibility Assessment** - of the pre-login journey.
The recurring finding across that work: portals show strong technical foundations but weaker commercial and user-trust functions, and gating decision-making information behind a login wall is "not a 'content' failure; it is a sales enablement failure."
## Limits of the framework
The exact enabler weightings and scoring rubric are proprietary. Public articles describe the structure (6 focus areas, ~24 enablers, 130+ practices) but not the scoring formula - describe and apply the structure, and cite Pronovix directly for a formal audit rather than attempting to reproduce their internal scoring.
## Adjacent frameworks (weaker fit - name only as alternatives)
- Postman's State of the API research: an industry-wide practitioner survey, not a portal-specific maturity model.
- The internal-developer-portal scorecard ecosystem (Backstage/Spotify and the platform-engineering maturity discourse): targets internal platform engineering, out of this skill's scope.
- Generic structured-decision methods (e.g. CMMI's Decision Analysis and Resolution with weighted scoring) have been borrowed for portal vendor selection - usable for the build-vs-buy step, but they are not portal maturity models.
references/portal-case-studies.md›
# Portal and TTFC case studies
Every figure below carries a sourcing label. Agency- and vendor-reported numbers are directional evidence that the portal is the lever, never numbers a client should expect to reproduce. The consistent theme across all of them: **the underlying API did not change in any of these cases - only the portal and documentation did** - yet TTFC, adoption, satisfaction, and support load all moved materially.
## Portal/documentation rebuilds (agency-reported - WriteChoice client retrospectives, not independently audited)
| Case | What changed | Reported outcome |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| PagBank | Portal restructured around the developer's actual journey (sign up → authenticate → first call → handle errors → production), tested multi-language examples | Integration time 20 days → 7 days; CSAT 29% → 89%; support tickets −50% |
| Tonder | Docs overhauled with a zero-to-first-transaction path, consistent terminology, self-serve sandbox | Integration time 2 months → 10 days; adoption doubled; support costs −80% |
| Yuno (payment orchestration) | Docs migrated between hosted platforms, getting-started flow restructured | TTFC of 15-20 minutes; adoption +50%; docs quality cited by enterprise customers during evaluation |
| Nayax | Fragmented docs consolidated into one unified portal | Reported 2x more integrations per year; support costs −80% |
| CarePortals | Portal rebuild | Reported 20+ developer hours saved per week |
## Ready-to-run collections (vendor-reported - Postman, measured on its own platform)
Shipping an importable, forkable collection of working example calls accelerated first calls **1.7x on average, with outliers as high as 56x** against a ~17-minute baseline. Keep the ratio, not the exact minutes - the baseline is specific to the APIs measured.
## Personalized onboarding (vendor's own product - Twilio)
Twilio's redesigned onboarding uses a short intake survey (role, code preference, use case) to tailor the experience, auto-selects relevant configuration, and lets users test with or without code and see live results instantly. It also verifies a phone number at signup - not just email - so trial users can act immediately instead of stalling on a later verification step. Twilio's public onboarding promise is a concrete outcome with a time ("send your first SMS in minutes"), not a vague "get started" - copy the pattern of promising a specific outcome.
## AI docs assistant at scale (vendor showcase - kapa.ai, traffic figure corroborated by Docker's own engineering blog)
Docker deployed a RAG "Ask AI" assistant across docs serving ~13 million monthly views. The vendor reports the rollout took weeks versus an estimated 6-12 months of internal development.
Deflection outcomes from the same vendor's announcements:
- One customer reported a 20% monthly support-ticket reduction.
- Another reported a 28% cut in response times.
All deflection figures are vendor-reported.
## TTFC benchmark anchors (published, but context-bound - use as anchors, not pass/fail bars)
- No universal TTFC standard exists. Nordic APIs explicitly cautions that TTFC varies by API complexity, price, audience familiarity, and competitive pressure.
- Ably's portal-scoring rubric awards top marks when time to hello world is under 30 minutes.
- Twilio publicly targets developers up and running in 5 minutes or less.
- Practitioner guidance (WriteChoice): under 15 minutes for a simple REST API with token auth. Under an hour for a complex payment-orchestration API with OAuth and webhooks. Also: "Auth is where most developers stall first... If a developer can't authenticate in under five minutes, everything downstream stops."
- Survey figures place the early-stage quit rate between 50% and 70% when friction appears (secondary citation via Young Copy - treat as directional).
- Postman's State of the API research (13,500+ respondents in 2020): lack of documentation is the #1 reported obstacle to consuming APIs "by an extremely wide margin" (54.3%). It stayed the top blocker (52%) in the 2023 edition.
## Common friction points (synthesized from Nordic APIs, WriteChoice, DigitalAPI, Young Copy)
- Mandatory signup before any exploration.
- Email/phone verification delays.
- API-key provisioning delays or manual approval.
- Unclear base URLs.
- Sandbox-vs-production confusion.
- Missing or broken quickstarts.
- Code examples referencing deprecated endpoints or auth.
- Sandboxes gated behind a sales call.
- SDK installation friction.
- Auth and CORS setup snags.
SKILL.md›
---
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.1"
---
# 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.
**Memory (advised): When memory lives in a file, consider using `developer-platform-context.md`; if a different memory system is in use, rely on that instead. The file is an advisory reference, not a mandatory requirement. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.**
## 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](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](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](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](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
- [references/portal-case-studies.md](references/portal-case-studies.md) - quantified TTFC and portal-rebuild case studies.
- [references/maturity-benchmark.md](references/maturity-benchmark.md) - the Pronovix maturity model, focus-area diagnostic, and adjacent frameworks.
- [references/component-checklist.md](references/component-checklist.md) - full component checklist, credential-lifecycle UX patterns, try-it console requirements, RBAC patterns, and platform-category integration notes.
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.
- `samber/developer-platform-skills@sample-app-strategy` - refer for which sample apps, templates and playgrounds the portal links to, and how they stay current.
- `samber/developer-platform-skills@public-roadmap-strategy` - refer for whether a roadmap page exists at all and what it may promise; this skill only places it.