Airtable 数据库/表格协作平台 Skill
Airtable 最危险的坑不是报错，而是静默失败——filterByFormula 是 Airtable 自有公式语言，不是 SQL 或 MongoDB 风格的过滤对象，传错格式不会报错，只会悄悄返回全部或空结果。另外官方文档正文和 OpenAPI 规范都没有写出批量写请求的记录数上限，这是本次调研确认的一处文档缺口，社区共识（含官方推荐的 pyairtable 源码）是 10 条/请求。
pat 前缀）或 OAuth，实际权限是 scope 与用户本身权限的交集Agent 工具更新 2026-09-21安装
选你用的 Agent，复制命令。
npx -y skills add fxp/skillify --skill airtable --agent claude-code --yes装到项目的 .claude/skills/；加 -g 装到全局。装完需要你手动执行 /reload-plugins，这一步 Agent 代劳不了。
npx -y skills add fxp/skillify --skill airtable --agent codex --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill airtable --agent cursor --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill airtable --agent opencode --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill airtable --agent gemini-cli --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill airtable --agent github-copilot --yes装到项目的 .agents/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill airtable --agent trae --yes装到项目的 .trae/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill airtable --agent windsurf --yes装到项目的 .windsurf/skills/；加 -g 装到全局。
npx -y skills add fxp/skillify --skill airtable --agent qwen-code --yes把 --agent 换成你用的 Agent 标识，可以一次写多个。skills CLI 1.5.25 共支持 79 个，例如 qwen-code、kimi-code-cli、trae-cn、qoder、lingma、cline、roo。
或者让 Agent 自己装
读 https://github.com/fxp/skillify/blob/main/skills/airtable/prompt.md 并照它执行装对了的标志：references/ 下有 5 份文档。
装好后，可以这样问你的 Agent
这份 Skill 覆盖的典型任务。点一下复制。
5 类能力
每类能力对应一份 reference，Agent 按任务只打开需要的那份。
鉴权与 Scope
个人访问令牌 vs OAuth 怎么选、scope 列表、token 权限是 scope 与用户权限的交集、403 排查顺序
读取与过滤记录
分页（offset/pageSize/maxRecords）、view 参数、filterByFormula 完整语法与头号陷阱
写记录
创建/更新/删除（单条与批量）、PATCH vs PUT、upsert、typecast、批量上限、附件两种上传路径
字段类型与 Metadata API
32 种字段类型全表、只读字段、select/链接记录/附件的读写不对称、Metadata API 读写 base 结构
错误码与限流
错误响应结构、状态码表、按 base 维度的限流、固定 30 秒重试、官方与社区 SDK
当前事实
整理自官方文档（抓取于 2026-09-21），还没有用真实凭证验证。
| 项 | 值 |
|---|---|
| Base URL | https://api.airtable.com/v0/{baseId}/{tableIdOrName}，附件字节上传走另一个域名 content.airtable.com |
| 鉴权 | Authorization: Bearer <pat...>，旧版 api_key 已于 2024-02-01 停用 |
| filterByFormula | Airtable 自有公式语言，如 AND({Status}="Active",{Priority}>3)，不是 JSON 过滤对象 |
| 批量写入上限 | 官方文档未写明确数字，社区共识（pyairtable 硬编码）是 10 条/请求 |
| 限流 | 5 请求/秒/base + 50 请求/秒/用户，429 后固定等待 30 秒，不是指数退避 |
| 只读字段 | formula/rollup/lookup/count 等只读，不能通过 Create/Update records 写入，但字段定义本身可以用 Metadata API 创建 |
照通用经验写容易错的 6 件事
来自官方文档，还没有用真实凭证验证。
filterByFormula传错格式不会报错，只会静默返回错误结果。它是 Airtable 自有公式语言（AND()/OR()/单个=），不是 MongoDB/Pinecone 那种{field:{$gt:value}}操作符对象；传错会被当字符串处理，公式求值失败通常返回全部或空结果，没有任何报错提示。- 批量写入的记录数上限，官方文档正文和 OpenAPI 规范都没写出具体数字。这是一处确认的文档缺口；社区共识、且官方推荐的
pyairtable客户端硬编码 10 条/请求并自动分批，写批量创建/更新/删除代码时应默认按 10 条分批。 - 附件写入有两条完全不同的路径，直传文件字节还要换域名。公网 URL 走主 API 域名跟着其它字段一起提交；本地文件字节（≤5MB）要 POST 到
content.airtable.com（不是api.airtable.com），且作用于已存在的记录，不能一步创建带附件的新记录；返回的附件 URL 2 小时后过期，需要长期保存必须自己下载。 - 单选/多选字段必须精确匹配已有选项名，多选/多协作者/附件是整体覆盖不是合并。不匹配报
INVALID_MULTIPLE_CHOICE_OPTIONS，除非传typecast: true自动新建选项；更新时只传子集会导致原有其它选中项丢失，需要保留时要先读出当前值再拼接。 - 限流是按 base 维度的，触发后固定等 30 秒，不是指数退避。5 请求/秒/base + 50 请求/秒/用户是两层独立配额，操作多个 base 要按 baseId 分别维护计数器；429 后官方明确给的是固定 30 秒等待，不是
Retry-After式的指数退避。 - 计算字段的值只读，但字段定义本身可以通过 Metadata API 创建。formula/rollup/lookup/count 等类型不能通过 Create/Update records 写入 cell 值，但新建一个 formula 字段并指定公式表达式，是 Metadata API 的 Create field 接口能做的事——"值只读"和"字段类型不能被 API 涉及"是两回事。