api-changes
$
npx mdskill add microsoft/FluidFramework/api-changes<required> Before doing any work, create one task/todo item per applicable step using your available task tooling (TaskCreate for Claude, TodoWrite for Copilot). Mark each task in_progress when you start it and completed when you finish. This prevents steps from being silently skipped as context grows. </required>
SKILL.md
.github/skills/api-changesView on GitHub ↗
---
name: api-changes
description: Use when customer-facing API changes were made — i.e., API report .md files differ from main. Guides through release tag assignment, API Council review requirements, breaking change classification, deprecation process, and changeset guidance. Triggered automatically by ci-readiness-check when api-report diffs are detected.
---
<required>
Before doing any work, create one task/todo item per applicable step using your available task tooling (TaskCreate for Claude, TodoWrite for Copilot). Mark each task in_progress when you start it and completed when you finish. This prevents steps from being silently skipped as context grows.
</required>
# API Changes Review
## Step 1: Identify what changed
```bash
git diff $(git merge-base HEAD origin/main)...HEAD -- '**/api-report/**/*.md'
```
Build a summary table and present it to the user:
| Package | Change type | Tag(s) | Breaking? |
|---------|-------------|--------|-----------|
Change types: addition, removal, signature change, tag promotion.
If all changes are `@internal`-only, tell the user there are no customer-facing API changes and stop.
---
## Step 2: Check release tags, documentation, and export reachability
For any new exports, verify each has a release tag and flag any missing ones to the user — API Extractor will fail with `ae-missing-release-tag`. Help the user choose the right tag:
| Tag | When to use |
|-----|-------------|
| `@public` | Stable, production-ready. Full SemVer. Use only when the shape is final. |
| `@beta` | Seeking feedback, path to `@public`. Production OK with caution. |
| `@alpha` | Experimental, early feedback only. Not for production. No stability guarantees. |
| `@internal` | Framework-internal only, not for external consumers. |
When in doubt: `@alpha` — easier to promote than demote. `@legacy` is a paired modifier (`@legacy @public` or `@legacy @alpha`) for FF v1 APIs; don't apply it to new APIs.
For every new customer-facing export (`@public`, `@beta`, `@alpha`) that is intended to be usable by package consumers, verify it is reachable from the package's public entrypoint, not just exported from the adjacent module or folder. Trace and update the export chain through every relevant `index.ts` barrel up to the package root entrypoint (typically `src/index.ts`, or tiered entrypoints such as `src/alpha.ts` / `src/beta.ts` where used). Missing parent-barrel exports are incomplete API changes. API Extractor may not report the intended API at all, and consumers are expected to import from the package's top-level entrypoint rather than reaching into subpaths.
Also check that each new customer-facing export (`@public`, `@beta`, `@alpha`) has TSDoc documentation — at minimum a summary, `@param` tags, and `@returns` if applicable. Flag any missing documentation to the user.
---
## Step 3: Inform the user about API Council review
Tell the user whether their change requires API Council approval:
| Changed surface | Approval required? |
|---|---|
| `@public`, `@legacy @public`, `@beta`, `@legacy @alpha` | Yes — `fluid-cr-api` will be automatically assigned as a required reviewer on the PR |
| `@alpha` only (not `@legacy`) | No — but early engagement with the council is encouraged |
| `@internal` only | No |
Tell the user: council approval is a separate sign-off from the area owner review. To engage the council, they can reach out to the API Council member on their EM team or tag `@FF API` on Teams. Share this link with the user for more details:
https://eng.ms/docs/experiences-devices/opg/office-shared/fluid-framework/fluid-framework-internal/fluid-framework/docs/dev/resources/api-council
---
## Step 4: Assess breaking changes
A breaking change removes or modifies an existing API in a way that causes compile errors for consumers upgrading.
### @public / @legacy+@public
If this is a breaking change to `@public` or `@legacy @public`, tell the user this is likely a mistake — major releases happen very rarely. Breaking `@public` APIs must be coordinated with a major release; the old API must be deprecated at least 3 months prior in a minor release with a clear replacement.
Share these links with the user for the required process:
- API Deprecation wiki: https://github.com/microsoft/FluidFramework/wiki/API-Deprecation
- Client 3.0 Breaking Changes tracking issue: https://github.com/microsoft/FluidFramework/issues/23271
### @beta / @legacy+@alpha
If this is a breaking change to `@beta` or `@legacy @alpha`, tell the user:
- Breaking changes may only land in minor versions that are an increment of 10 (2.10, 2.20, 2.30, …)
- The PR must be staged on a `test/breaks/client/#.#0/` branch and held until the break window opens
- They should check whether partners (e.g. office-bohemia) consume the API directly — if in doubt, assume they do and allow 12 weeks lead time
Share these links with the user:
- Beta | Legacy Breaking Changes tracking issue: https://github.com/microsoft/FluidFramework/issues/25322
- Full process: https://github.com/microsoft/FluidFramework/wiki/Beta-Break-Process
### @alpha only
Tell the user: while `@alpha` has no contractual stability guarantees, there is an informal agreement not to break office-bohemia. If this change could break office-bohemia, it should be staged using the same process as above.
If there is any doubt, recommend the user test against office-bohemia first by running the office-bohemia integration pipeline against their branch. Share these links:
- Office-bohemia integration pipeline: https://dev.azure.com/office/OC/_build?definitionId=29163
- Build - client packages pipeline: https://dev.azure.com/fluidframework/internal/_build?definitionId=12
- Full instructions: https://eng.ms/docs/experiences-devices/opg/office-shared/fluid-framework/fluid-framework-internal/fluid-framework/docs/dev/monitoring/loop-integration-pipeline/index
Also tell the user: if they skip this check and the change does break office-bohemia, the daily integration pipeline will catch it and FF OCE will revert the PR or contact them to do so ASAP.
---
## Step 5: Deprecation checklist
If any API is being deprecated, check that the following are in place and flag anything missing to the user:
- [ ] `@deprecated` TSDoc comment includes: version deprecated, version of removal, replacement, and a link to the tracking issue:
```typescript
/**
* @deprecated 2.x.y. Removed in 3.0.0. Use {@link replacementApi} instead.
* See {@link https://github.com/microsoft/FluidFramework/issues/ABCD} for context.
*/
```
- [ ] GitHub issue filed using the "Deprecated API" template as a sub-issue of the appropriate tracking issue
- [ ] In-codebase uses removed (test-only uses may remain with an explanatory comment)
- [ ] Changeset present (see Step 6)
Share this link with the user for full deprecation guidance: https://github.com/microsoft/FluidFramework/wiki/API-Deprecation
---
## Step 6: Changeset
All customer-facing API changes require a changeset — additions, modifications, deprecations, tag promotions, removals.
Check whether one exists: `git status --porcelain -- .changeset/`
If none exists, create one on behalf of the user from the repo root:
```bash
pnpm flub changeset add --empty
```
This drops a randomly-named file in `.changeset/`. Edit it with content based on what changed. YAML front matter lists affected packages (only those meaningful to consumers) with bump type `minor`, plus `"__section"` to route to the right release notes section: `feature` (new APIs), `deprecation`, `breaking` (major / server only; use `legacy` for legacy API breaks), `tree` (changes to SharedTree/`@fluidframework/tree` APIs), `fix`, or `other`.
Summary line rules (from `.changeset/README.md`): succinct, no terminal punctuation, no backtick formatting, present tense. Prefix test: mentally prepend "In this release," to verify it reads naturally. Body may include a code example for features, deprecations, and breaking changes.
After drafting the changeset, show the content to the user and confirm it looks right before moving on.
---
## Step 7: Summary
Present the user with a clear summary:
1. API changes found (table from Step 1)
2. Any missing release tags or documentation
3. Whether API Council review is required
4. Any breaking change warnings and the process the user needs to follow
5. Any deprecation issues
6. Changeset status
End with a clear go/no-go: "Your changes look good to merge" or "Please resolve these issues before merging: …"
More from microsoft/FluidFramework
- brainstormingIMMEDIATELY USE THIS SKILL when creating or develop anything and before writing code or implementation plans - refines rough ideas into fully-formed designs through structured Socratic questioning, alternative exploration, and incremental validation
- building-ui-uxUse when implementing user interfaces or user experiences - guides through exploration of design variations, frontend setup, iteration, and proper integration
- ci-readiness-checkUse when the user explicitly asks for a CI check or to push their branch — e.g. "ci readiness", "check ci", "pre-push check", "ready for CI", "ci check", "ready to push", "push my changes", "push the branch", "let's push". Catches common CI failures before pushing — formatting, stale API reports, missing changesets, policy violations.
- creating-debug-tests-and-iteratingUse this skill when faced with a difficult debugging task where you need to replicate some bug or behavior in order to see what is going wrong.
- creating-skillsUse when you need to create a new custom skill for a profile - guides through gathering requirements, creating directory structure, writing SKILL.md, and optionally adding bundled scripts
- ff-oce-dashboardGenerate the OCE shift status dashboard. Triggers on: 'generate shift dashboard', 'show dashboard', 'shift status', 'status dashboard', 'what's going on', or any request for a NON-SPECIFIC overview of current OCE status (incidents, pipelines, errors).
- ff-oce-kustoUse this skill for any Kusto query or telemetry investigation specifically related to Fluid Framework or its partners. Triggers include: writing or running a Kusto query against the Office Fluid database, investigating Fluid Framework telemetry or error rates, querying Office_Fluid_FluidRuntime_* tables, looking up a Fluid session by Session_Id or docId, investigating a Fluid-related error in Loop or Whiteboard telemetry, monitoring an FF bump or partner ring deployment, checking Fluid render reliability or Scriptor errors, or when the user mentions Fluid-specific tables (Office_Fluid_FluidRuntime_*, OwhLoads, HostTracker, Scriptor) or Fluid-specific error types (dataCorruptionError, dataProcessingError, DeltaConnectionFailureToConnect, ICE, ACE). Do NOT trigger for general Kusto questions that are not related to Fluid Framework.
- finishing-a-development-branchUse this when you have completed some feature implementation and have written passing tests, and you are ready to create a PR.
- fluid-prUse when creating a pull request in the Fluid Framework repo. Composes a PR title and body following Fluid Framework conventions, proposes them to the user, then pushes the branch and creates the PR on GitHub. Triggers on "create a PR", "make a PR", "open a PR", "submit a PR", or "push and create a PR".
- fluid-pr-guideUse when composing, writing, drafting, or reviewing a PR title, PR description, or PR body in Fluid Framework — provides title style, body template, and section guidance.