| name | api-reports |
| description | Check or update the committed API reports for the @trycourier packages (API Extractor reports under api/*.api.md). Use when CI's "Build packages and check API changes" job fails on an API diff, when you intentionally changed a package's public API surface and need to refresh the committed report, or to verify locally that the reports are in sync before pushing. |
Check & update the API reports
The public API surface of every @trycourier/* package is captured by API Extractor in a committed report at the repo root: api/<package>.api.md. CI fails if a package's built API no longer matches its committed report, so any intentional API change must ship with an updated report in the same PR.
How it works
- Each package's
api-extractor.json writes its report to the root api/ folder (apiReport.reportFolder: "../../api").
- API Extractor reads the built types (
dist/index.d.ts) — so the package must be built before the report is accurate.
api-extractor run (no flags) runs in check mode: read-only, exits non-zero if the report is stale. This is wired into each package's build:ci.api-extractor run --local runs in update mode: rewrites api/<package>.api.md.
Check whether the reports are in sync (read-only)
This is exactly what CI runs — it builds every package and runs API Extractor in check mode:
yarn build-packages:ci
If it fails with an API report mismatch, the public API changed without the committed report being updated → go update it below.
Update the reports after an intentional API change
Rebuilds all packages and regenerates every report with --local:
yarn generate-api-docs
Then:
- Review the diff:
git diff api/ — confirm the changes match what you intended to expose/remove/rename. An unexpected entry usually means an accidental export or a forgotten release tag.
- Commit the updated
api/*.api.md files in the same PR as the source change.
- If the diff is large or surprising, double-check it's not a side effect of an unintended public export.
Notes
- Run from the repo root. Package manager is
yarn@1 (classic).
- Reports live at
api/*.api.md; per-package config is each package's api-extractor.json. Scripts: scripts/generate-api-docs (update) and scripts/build-packages-ci (build + check, used by CI's build-packages.yml).
- This skill lives at
.agents/skills/api-reports/SKILL.md (the cross-tool Agent Skills standard path). Cursor and Codex discover it there natively; Claude Code discovers it via the .claude/skills → ../.agents/skills directory symlink.
