FastAPI Expert
Jeffallan/claude-skills
Builds async Python APIs with FastAPI and Pydantic V2, covering endpoints, JWT authentication, async SQLAlchemy, WebSockets and pytest checks against the OpenAPI docs.
Review changes to Polar's API contract — Pydantic schemas, FastAPI endpoints, OpenAPI output and the generated SDKs.
Install API Surface Review
$ npx skills add polarsource/polar --skill api-surface-review -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install polarsource/polar api-surface-review --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/polarsource/polar.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/api-surface-review .claude/skills/api-surface-review && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "api-surface-review" agent skill from https://github.com/polarsource/polar/tree/main/.agents/skills/api-surface-review into .claude/skills/api-surface-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-surface-review", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/polarsource/polar/tree/main/.agents/skills/api-surface-reviewType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add polarsource/polar --skill api-surface-review -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install polarsource/polar api-surface-review --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/polarsource/polar.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/api-surface-review .agents/skills/api-surface-review && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "api-surface-review" agent skill from https://github.com/polarsource/polar/tree/main/.agents/skills/api-surface-review into .agents/skills/api-surface-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-surface-review", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add polarsource/polar --skill api-surface-review -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install polarsource/polar api-surface-review --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/polarsource/polar.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/api-surface-review .cursor/skills/api-surface-review && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "api-surface-review" agent skill from https://github.com/polarsource/polar/tree/main/.agents/skills/api-surface-review into .cursor/skills/api-surface-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-surface-review", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/polarsource/polar.git --path .agents/skills/api-surface-review--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add polarsource/polar --skill api-surface-review -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install polarsource/polar api-surface-review --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/polarsource/polar.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/api-surface-review .gemini/skills/api-surface-review && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "api-surface-review" agent skill from https://github.com/polarsource/polar/tree/main/.agents/skills/api-surface-review into .gemini/skills/api-surface-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-surface-review", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install polarsource/polar api-surface-reviewInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add polarsource/polar --skill api-surface-review -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/polarsource/polar.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/api-surface-review .github/skills/api-surface-review && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "api-surface-review" agent skill from https://github.com/polarsource/polar/tree/main/.agents/skills/api-surface-review into .github/skills/api-surface-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-surface-review", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add polarsource/polar --skill api-surface-review -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install polarsource/polar api-surface-review --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/polarsource/polar.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/api-surface-review .opencode/skills/api-surface-review && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "api-surface-review" agent skill from https://github.com/polarsource/polar/tree/main/.agents/skills/api-surface-review into .opencode/skills/api-surface-review/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "api-surface-review", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
api-surface-review- GitHub stars
- 10k
- Token cost
- ~1.3k tokens
- SKILL.md length
- 645 words
- Files
- 1
- Skills in repo
- 18
- Repo updated
- First seen
- Licence
- MIT
At a glance
Review changes to Polar's API contract — Pydantic schemas, FastAPI endpoints, OpenAPI output and the generated SDKs.
- Works in 5 steps: Public or private → Schema shape → Naming → …
- A diff touches schemas.py
- SKILL.md covers Scope, Checks and Output
- Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
What it does
API Surface Review is an agent skill from polarsource/polar. Review changes to Polar's API contract — Pydantic schemas, FastAPI endpoints, OpenAPI output and the generated SDKs. Checks public vs private exposure, schema shape and naming, and whether the change breaks merchants or the generated clients. Use when a diff touches schemas.py, endpoints.py, docs/openapi.json or sdk/, or when the user asks whether an API change is breaking.
Its SKILL.md is about 1.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Backend & APIs, covering DataFrames, OpenAPI specifications and API design. It works with OpenAPI, FastAPI and Pydantic. The repository describes itself as: Polar — A billing platform for the intelligence era. The licence is MIT.
When your agent uses it
- A diff touches schemas.py
- Docs/openapi.json
- The user asks whether an API change is breaking
Example prompts
- “/api-surface-review”
Workflow steps
5 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit e4fc909. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
No scripts in the folder and no shell commands in SKILL.md.
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
API Surface Review loads about 1.3k tokens when it runs. Until then it costs about 99 tokens; SKILL.md has 645 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from polarsource/polar at commit e4fc909, republished under its MIT licence (© polarsource). 645 words, ~1,346 tokens.
Download SKILL.mdSave it as
.claude/skills/api-surface-review/SKILL.md (or your agent's skills folder).- name
- api-surface-review
- description
- Review changes to Polar's API contract — Pydantic schemas, FastAPI endpoints, OpenAPI output and the generated SDKs. Checks public vs private exposure, schema shape and naming, and whether the change breaks merchants or the generated clients. Use when a diff touches schemas.py, endpoints.py, docs/openapi.json or sdk/, or when the user asks whether an API change is breaking.
- license
- MIT
- metadata.author
- polar
- metadata.version
- 1.0.0
API Surface Review (Polar)
The handle is the diff. The evidence is what this change does to the API contract, and whether any of it is breaking.
This is where Polar's most expensive review mistakes live. A schema change does not stay in
the repo: it flows into docs/openapi.json, the generated TypeScript client, the Speakeasy
SDKs under sdk/, and out to merchants who already wrote code against it.
Scope
Diffs touching **/schemas.py, **/endpoints.py, polar/openapi.py, docs/openapi.json,
sdk/, clients/packages/client/.
CI already does part of this job. The OpenAPI Diff workflow posts the schema delta as a
PR comment, and OpenAPI Client Regeneration Check fails if the client is stale. Do not
recompute either by hand. Read the diff comment if it exists and judge whether the delta is
acceptable; that judgement is the thing CI cannot make.
Owned elsewhere: ADR-0002 (status-coded PolarError), ADR-0007 (no default in output
schemas) → adr-check. Endpoint conventions written in server/AGENTS.md — response_model
and ORM returns, POST/PATCH/DELETE status codes, ListResource, responses=, the
PolarRequestValidationError boundary → conventions-check. Existing shared types →
reuse-check.
Checks
1. Public or private
APITag has two values, public and private (polar/openapi.py). Public means documented
and in the SDKs.
- Set it deliberately on every new router and route. Never hide something with
include_in_schema=False; usetags=[APITag.private]. - Tag the route, not the router, when only one route should change. The pattern: keep
APITag.publicon what stays, addAPITag.privateto the deprecated one. - Private endpoints (payouts are the standing example) are not in the SDK. Do not reason about them as public API.
- On every new field, ask: does a merchant need to see this? Internal
Organizationsettings keep leaking into the public API this way.
2. Schema shape
- Output fields are required, nullable where needed. A
defaultmakes them optional in OpenAPI, which generates a wrongly-optional TS field. (ADR-0007 — name it, do not restate it.) - Type fields with their enum, not
str. - Reuse a related resource's base schema rather than redefining its fields:
class DisputeCustomer(CustomerBase): .... - A value that already exists as a model property is a plain field, not a reimplemented
computed_field. - Descriptions are user-facing: no implementation detail, and write
Nonenotnull. - Any field writing to a SQL
INTcolumn isInt32, so out-of-range input is rejected at validation instead of overflowing. - Constrain enums by listing allowed values (
reason: Literal[RefundReason.foo, ...]) rather than a hand-rolled validator. Pydantic validates, OpenAPI documents. - Discriminated unions get a plain
DiscriminatorplusSetSchemaReference, so the union lands in OpenAPI properly. - Do not over-constrain fields fed by a payment processor. "We'll never know what Stripe or other payment processor will send us."
Show full SKILL.md (221 more words)Show less
3. Naming
The union takes the clean name, the variants get qualified: CustomerCreate is the union,
CustomerIndividualCreate and CustomerTeamCreate are members. Same for CustomerState.
Fields are snake_case. Prefer explicit over clever (payment_method_type, not
payment_method). Do not overload an existing concept with a new meaning.
4. Breaking changes
Breaking = removing a field, flipping required/optional, changing a type, renaming anything, or changing a status code a client branches on.
Before removing a field or behaviour:
- Check Logfire for real usage. This is what François actually does. Merchants create things programmatically that nobody expects.
- If it is used, keep a compatibility layer and use
SkipJsonSchemaso runtime still accepts the value while it disappears from future SDKs. - If it is genuinely breaking, say so plainly. That is a human decision, not something to wave through.
5. Route shape
Only the parts AGENTS.md does not already cover:
- Trailing slash on root endpoints.
- Errors on the same route need distinct status codes, or their schemas collide in the OpenAPI output.
- A query parameter must act as a pure filter. If it changes the response shape, the resource is wrong and it wants its own route.
- Removing an endpoint and updating its frontend caller in one PR is a deploy hazard →
ship-safetyowns the split.
Output
## API Surface
### 🔴 Blocking
- `file:line` — <what breaks, and for whom>. Fix: <fix>
### 🟠 Should fix
- `file:line` — <claim>. Fix: <fix>
### 🟡 Question
- `file:line` — <question>
### Notes
- public surface delta: <one line, or "see the OpenAPI Diff PR comment">
### Verdict
✅ Clean | ❌ n blocking, n should-fixAnything blocking needs a human decision before merge.
© polarsource, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in .agents/skills/api-surface-review of polarsource/polar.
Open the folder on GitHubat commit e4fc909
Compare with similar skills
API Surface Review next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| API Surface Review this skillpolarsource/polar | 10k | — | ~1.3k | Automated safety check: Pass | MIT | |
| FastAPI ExpertJeffallan/claude-skills | 12k | — | ~1.8k | Automated safety check: Pass | MIT | |
| Python Fastapi Patternsaiskillstore/marketplace | 430 | 1 repos | ~1.3k | Automated safety check: Notes | None | |
| API Designericrisco/rsc-harness | 167 | — | ~3.1k | Automated safety check: Pass | MIT | |
| Fastapi Patternsaffaan-m/ECC | 275k | — | ~2.3k | Automated safety check: Pass | MIT | |
| Fastapi Patternsaffaan-m/ECC | 275k | — | ~2k | Automated safety check: Pass | MIT |
Similar skills
Python Fastapi Patterns
aiskillstore/marketplace
FastAPI web framework patterns. An agent skill from aiskillstore/marketplace.
API Design
ericrisco/rsc-harness
A skill your agent uses when settling the contract of an API you expose, before implementation: resources/URLs, REST vs GraphQL, versioning, one RFC 9457 error envelope, pagination, idempotency —…
Fastapi Patterns
affaan-m/ECC
FastAPI patterns for async APIs, dependency injection, Pydantic request and response models, OpenAPI docs, tests, security, and production readiness.
Fastapi Patterns
affaan-m/ECC
非同期API、依存性注入、Pydanticのリクエスト・レスポンスモデル、OpenAPIドキュメント、テスト、セキュリティ、本番対応のためのFastAPIパターン。
API Docs Generator
Mathews-Tom/armory
Audits and enhances FastAPI and REST API documentation: missing descriptions, response codes, examples, docstrings, Pydantic models, OpenAPI spec.
More from polarsource/polar
All 18 skills in this repoPolar Python SDK
polarsource/polar
Integrate Polar billing in server-side Python applications using the versioned Polar and PolarAsync clients.
Polar Typescript SDK
polarsource/polar
Integrate Polar billing in server-side TypeScript applications using the versioned createPolar and createPolarCore clients.
Adr Check
polarsource/polar
Check a code change against the repo's Accepted Architecture Decision Records (ADRs) in handbook/engineering/decisions/ and report violations with citations.
Billing Review
polarsource/polar
Review a diff that touches Polar's billing domain — subscriptions, cycles and crons, orders, billing entries, meters and usage, discounts, checkout, payments and dunning, refunds, disputes, payouts…
Interview Task
polarsource/polar
Prepare an interview task for a candidate, as part of our hiring process.
Open PR
polarsource/polar
Open or update a draft GitHub pull request after Polar-specific review and cubic CLI review.
Related
Categories
Questions about API Surface Review
What does API Surface Review do?
Review changes to Polar's API contract — Pydantic schemas, FastAPI endpoints, OpenAPI output and the generated SDKs. API Surface Review is an agent skill from polarsource/polar. Review changes to Polar's API contract — Pydantic schemas, FastAPI endpoints, OpenAPI output and the generated SDKs.
When should I use API Surface Review?
API Surface Review fits situations like: A diff touches schemas.py; docs/openapi.json; the user asks whether an API change is breaking.
How do I install API Surface Review in Claude Code?
Run `npx skills add polarsource/polar --skill api-surface-review -a claude-code`. Or copy the skill folder (.agents/skills/api-surface-review in polarsource/polar) into .claude/skills/api-surface-review in your project. Claude Code loads it when a task matches its description.
How do I install API Surface Review in Codex?
Run `npx skills add polarsource/polar --skill api-surface-review -a codex`. Or copy the skill folder (.agents/skills/api-surface-review in polarsource/polar) into .agents/skills/api-surface-review in your project. Codex loads it when a task matches its description.
Can I use API Surface Review in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add polarsource/polar --skill api-surface-review -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/api-surface-review, .gemini/skills/api-surface-review, .github/skills/api-surface-review and .opencode/skills/api-surface-review in your project.
What does API Surface Review need to run?
SKILL.md names no scripts, command-line tools or credentials: API Surface Review is instructions for the agent only.
Does API Surface Review access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is API Surface Review safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does API Surface Review use?
API Surface Review is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does API Surface Review use?
About 1.3k tokens (SKILL.md is roughly 5.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to API Surface Review?
Skills that share tags, products or a category with API Surface Review: FastAPI Expert (Jeffallan/claude-skills, 12k stars), Python Fastapi Patterns (aiskillstore/marketplace, 430 stars), API Design (ericrisco/rsc-harness, 167 stars) and Fastapi Patterns (affaan-m/ECC, 275k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains API Surface Review?
polarsource (a GitHub organization) maintains it in polarsource/polar, which has 10,340 GitHub stars. The repository holds 18 skills in this directory. The repository was last updated on October 7, 2026.
Source: polarsource/polar on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.