API roadmap builder · free AI skill

Transforms an API surface area description into a phased delivery roadmap with versioned milestones, developer impact assessments, breaking-change classifications, dependency mapping, and a deprecation strategy. Use…

Purpose

Turn a description of an API's current and intended surface area into a phased, milestone-driven roadmap that sequences work by dependency order and developer impact — so the team knows what ships when, which changes break consumers, and how versioning and deprecation are handled across the timeline.

When to Use

Invoke this skill when the user asks to:

Plan the evolution of a public, partner, or internal API over multiple quarters
Sequence new endpoints, fields, or capabilities into a release order
Manage breaking changes and version transitions across a developer base
Build a developer-facing API roadmap to share externally or with stakeholders
Plan an SDK or platform capability expansion tied to API changes
Define a deprecation and migration path for legacy endpoints

Inputs Required

Before starting, collect:

Current API surface: Existing endpoints, resources, or capabilities (or "greenfield" if net-new)
Target capabilities: What the API needs to support that it doesn't today
Consumer profile: Who calls this API — internal teams, partners, public developers, SDK users
Time horizon: Total span to plan (e.g., 2 quarters, 12 months)
Versioning approach: URL path, header, or none yet (default: assume no formal versioning exists and recommend one)
Known constraints: Dependencies, team capacity, compliance/security gates, or fixed deadlines
Stability commitments: Any backward-compatibility or SLA guarantees already made to consumers

If versioning approach or stability commitments are missing, assume a public API with no formal versioning, recommend semantic versioning by URL path, and note the assumption.

Instructions

Step 1: Surface Area Inventory and Classification

Catalog every capability — current and target — and tag each one:

State: Existing / Planned / Deprecating
Type: New resource / New endpoint on existing resource / New field / Behavior change / Removal
Compatibility: Additive (non-breaking) / Breaking
Consumer impact: None / Optional adoption / Required migration

Group capabilities into logical capability clusters (e.g., "Auth & identity," "Webhooks," "Bulk operations"). Clusters become the unit of roadmap sequencing.

Step 2: Dependency Mapping

For each capability, identify what must exist first:

Technical dependencies: An endpoint that requires another resource, auth model, or data contract to ship first
Sequencing dependencies: Changes that should land together to avoid forcing consumers through two migrations
External dependencies: Third-party services, infra changes, or other teams' deliverables

Flag any circular or ambiguous dependencies explicitly. A capability cannot be scheduled before its dependencies resolve.

Step 3: Phasing into Milestones

Break the time horizon into 3–5 sequenced phases. For each phase, name a theme and a developer-facing outcome. Order phases by these rules:

Foundation first: Auth, core resources, and data contracts that everything else depends on
Additive before breaking: Ship non-breaking capabilities early to build adoption before any forced migration
Batch breaking changes: Concentrate breaking changes into deliberate version boundaries — never trickle them out
Deprecation tail last: Removal of legacy surface comes after the replacement has shipped and a migration window has passed

For each phase, define:

Milestone name and target window
Capabilities shipping (referencing the Step 1 inventory)
Version impact: New version, additive to current, or no version change
Developer impact: What consumers must do, can do, or experience automatically
Exit criteria: The condition that marks the phase complete

Step 4: Breaking Change and Versioning Strategy

For every breaking change in the roadmap:

Classify the break: Removed field/endpoint, changed response shape, changed default behavior, stricter validation, or auth change
Migration path: The concrete steps a consumer takes to move off the old behavior
Coexistence window: How long old and new run in parallel
Communication trigger: When consumers are notified relative to the change (e.g., changelog at announce, email at deprecation, hard cutoff date)

Recommend a versioning scheme if none exists, and specify which phases introduce a new version.

Step 5: Deprecation Plan

For each capability being retired, define a four-stage lifecycle:

Announce: Marked deprecated in docs and response headers (e.g., Sunset header), replacement available
Discourage: Warnings in responses, new consumers blocked from adopting
Sunset window: Fixed date range; active consumers notified directly
Removal: Endpoint returns a clear error pointing to the migration guide

Specify the minimum deprecation window appropriate to the consumer profile (internal: weeks; partner: a quarter or more; public: 6–12 months).

Step 6: Risk and Dependency Notes

Summarize the roadmap's structural risks:

Capabilities blocked on external dependencies (highest schedule risk)
Phases carrying multiple breaking changes (highest consumer risk)
Migration windows that overlap and could force consumers through back-to-back migrations
Any commitment in the inputs that the roadmap puts at risk

Output Format

Structure: Inventory table → phased roadmap (one section per phase) → breaking change strategy → deprecation plan → risk notes
Length: 1,000–1,400 words
Format: Structured document — inventory and breaking changes as tables; phases as named sections with sub-bullets; risks as a prioritized list
Sections: Surface Area Inventory → Dependency Map → Phased Roadmap (3–5 phases) → Breaking Change & Versioning Strategy → Deprecation Plan → Risk & Dependency Notes
Tone: Technical product manager — precise, decision-oriented, written for both engineering and developer-relations readers

Quality Checklist

Before delivering output, verify:

[ ] Every capability in the inventory is tagged with state, type, compatibility, and consumer impact
[ ] No capability is scheduled in a phase before its dependencies resolve
[ ] Every breaking change has a classification, migration path, and coexistence window
[ ] Breaking changes are batched at version boundaries, not scattered across phases
[ ] Each deprecation follows the four-stage lifecycle with a specified window
[ ] Each phase has explicit exit criteria, not just a list of features

Notes

The most common roadmap failure is forcing consumers through two migrations in close succession — check the deprecation windows against the phasing before delivering
Additive changes should dominate early phases; a roadmap that front-loads breaking changes will stall adoption
For public APIs, the deprecation window is a trust signal — under-promising the window and removing early damages developer confidence more than a longer timeline costs
If the inventory reveals no clean version boundary, recommend establishing one as the first phase's primary deliverable

How to use this skill

This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.

Installing in Claude Code:

~/.claude/skills/<folder-name>/SKILL.md — auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)
<your-project>/.claude/skills/<folder-name>/SKILL.md — auto-loads only when working in that project (recommended for project-specific skills)

Restart Claude Code or open a new session to register.

Using in Claude.ai, ChatGPT, Gemini, or other AI tools:

Drag this file into a new chat, or copy and paste its contents
Send your task or request as your next message — the AI will apply the skill where it fits

For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills