kayforkind/skill-slice/airtable

Claude Code and agent skill by kayforkind/skill-slice

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Talks to Airtable's REST API with curl and a personal access token: list/filter records, schema inspect, batch CRUD, and performUpsert syncs. Use when the user wants to read, create, update, delete, or idempotently sync rows in an Airtable base (app/tbl/rec IDs). Not for the Airtable web UI, OAuth MCP servers, or the Python SDK; do not use deprecated key-prefixed API keys.

Install

npx vskill@latest install kayforkind/skill-slice/airtable

SKILL.md

The same SKILL.md was published earlier as kayforkind/skill-slice/airtable.

Airtable — Bases, Tables & Records

Work with Airtable's REST API directly via curl using the terminal tool. No MCP server, no OAuth flow, no Python SDK — just curl and a personal access token.

When to Use

  • User asks to read, list, filter, or search Airtable records.
  • User asks to create, update, upsert, or delete records in an Airtable base.
  • User asks to inspect base/table schema (field names, types, select options).
  • User asks to sync data into or out of Airtable (idempotent upserts, batch inserts).
  • User mentions "Airtable", "base", "table", "records", or references an app... / tbl... / rec... ID.

Prerequisites

  1. Create a Personal Access Token (PAT) at https://airtable.com/create/tokens (tokens start with pat...).
  2. Grant these scopes (minimum):
  • data.records:read — read rows
  • data.records:write — create / update / delete rows
  • schema.bases:read — list bases and tables
  1. Important: in the same token UI, add each base you want to access to the token's Access list. PATs are scoped per-base — a valid token on the wrong base returns 403.
  2. Store the token in ${HERMES_HOME:-~/.hermes}/.env (or via hermes setup):

`` AIRTABLE_API_KEY=pat_your_token_here ` On Windows PowerShell, the equivalent home path is $env:USERPROFILE\.hermes\.env`.

Note: legacy key... API keys were deprecated Feb 2024. Only PATs and OAuth tokens work now.

API Basics

  • Endpoint: https://api.airtable.com/v0
  • Auth header: Authorization: Bearer $AIRTABLE_API_KEY
  • All requests use JSON (Content-Type: application/json for any POST/PATCH/PUT body).
  • Object IDs: bases app..., tables tbl..., records rec..., fields fld.... IDs never change; names can. Prefer IDs in automations.
  • Rate limit: 5 requests/sec/base. 429 → back off. Burst on a single base will be throttled.

Base curl pattern (bash):

bash
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

PowerShell equivalent:

powershell
curl -s "https://api.airtable.com/v0/$env:BASE_ID/$env:TABLE?maxRecords=5" `
-H "Authorization: Bearer $env:AIRTABLE_API_KEY" | python3 -m json.tool

-s suppresses curl's progress bar — keep it set for every call so the tool output stays clean. Pipe through python3 -m json.tool (always present) or jq (if installed) for readable JSON.

Field Types (request body shapes)

Field typeWrite shape
Single line text"Name": "hello"
Long text"Notes": "multi\nline"
Number"Score": 42
Checkbox"Done": true
Single select"Status": "Todo" (name must already exist unless typecast: true)
Multi-select"Tags": ["urgent", "bug"]
Date"Due": "2026-04-01"
DateTime (UTC)"At": "2026-04-01T14:30:00.000Z"
URL / Email / Phone"Link": "https://…"
Attachment"Files": [{"url": "https://…"}] (Airtable fetches + rehosts)
Linked record"Owner": ["recXXXXXXXXXXXXXX"] (array of record IDs)
User"AssignedTo": {"id": "usrXXXXXXXXXXXXXX"}

Pass "typecast": true at the top level of a create/update body to let Airtable auto-coerce values (e.g. create a new select option on the fly, convert "42" → 42).

Procedure

Step 1 — Confirm auth
bash
curl -s -o /dev/null -w "%{http_code}\n" https://api.airtable.com/v0/meta/bases \
-H "Authorization: Bearer $AIRTABLE_API_KEY"

Expect 200. If 401, the token is invalid or expired. If 403, the token lacks schema.bases:read scope or the base isn't in the token's Access list.

Step 2 — Find the base

List bases the token can see:

bash
curl -s "https://api.airtable.com/v0/meta/bases" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

If the token lacks schema.bases:read, ask the user for the app... ID directly.

Step 3 — Inspect the schema (always before mutating)
bash
curl -s "https://api.airtable.com/v0/meta/bases/$BASE_ID/tables" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Use this BEFORE mutating — confirms exact field names and IDs, surfaces options.choices for select fields, and shows primary-field names. Cache these locally in the session.

Step 4 — Read before you write

For "update X where Y", use filterByFormula first to resolve the rec... ID, then PATCH. Never guess record IDs.

Step 5 — Execute the operation

Choose from the common queries and mutations below.

Common Queries

List records (first 10)
bash
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=10" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
Get a single record
bash
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
Filter records (filterByFormula)

Airtable formulas must be URL-encoded. Let Python stdlib do it — never hand-encode:

bash
FORMULA="{Status}='Todo'"
ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA")
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Useful formula patterns:

  • Exact match: {Email}='user@example.com'
  • Contains: FIND('bug', LOWER({Title}))
  • Multiple conditions: AND({Status}='Todo', {Priority}='High')
  • Or: OR({Owner}='alice', {Owner}='bob')
  • Not empty: NOT({Assignee}='')
  • Date comparison: IS_AFTER({Due}, TODAY())
Sort + select specific fields
bash
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?sort%5B0%5D%5Bfield%5D=Priority&sort%5B0%5D%5Bdirection%5D=asc&fields%5B%5D=Name&fields%5B%5D=Status" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Square brackets in query params MUST be URL-encoded (%5B / %5D).

Use a named view
bash
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?view=Grid%20view&maxRecords=50" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Views apply their saved filter + sort server-side.

Common Mutations

Create a record
bash
curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"fields":{"Name":"New task","Status":"Todo","Priority":"High"}}' | python3 -m json.tool
Create up to 10 records in one call
bash
curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"typecast": true,
"records": [
{"fields": {"Name": "Task A", "Status": "Todo"}},
{"fields": {"Name": "Task B", "Status": "In progress"}}
]
}' | python3 -m json.tool

Batch endpoints are capped at 10 records per request. For larger inserts, loop in batches of 10 with a short sleep to respect 5 req/sec/base.

Update a record (PATCH — merges, preserves unchanged fields)
bash
curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"fields":{"Status":"Done"}}' | python3 -m json.tool
Upsert by a merge field (no ID needed)
bash
curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"performUpsert": {"fieldsToMergeOn": ["Email"]},
"records": [
{"fields": {"Email": "user@example.com", "Status": "Active"}}
]
}' | python3 -m json.tool

performUpsert creates records whose merge-field values are new, patches records whose merge-field values already exist. Great for idempotent syncs.

Delete a record
bash
curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
Delete up to 10 records in one call
bash
curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE?records%5B%5D=rec1&records%5B%5D=rec2" \
-H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Pagination

List endpoints return at most 100 records per page. If the response includes "offset": "...", pass it back on the next call. Loop until the field is absent:

bash
OFFSET=""
while :; do
URL="https://api.airtable.com/v0/$BASE_ID/$TABLE?pageSize=100"
[ -n "$OFFSET" ] && URL="$URL&offset=$OFFSET"
RESP=$(curl -s "$URL" -H "Authorization: Bearer $AIRTABLE_API_KEY")
echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]'
OFFSET=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))')
[ -z "$OFFSET" ] && break
done

Typical Workflow

  1. Confirm auth. curl -s -o /dev/null -w "%{http_code}\n" https://api.airtable.com/v0/meta/bases -H "Authorization: Bearer $AIRTABLE_API_KEY" — expect 200.
  2. Find the base. List bases (step above) OR ask the user for the app... ID directly if the token lacks schema.bases:read.
  3. Inspect the schema. GET /v0/meta/bases/$BASE_ID/tables — cache the exact field names and primary-field name locally in the session before mutating anything.
  4. Read before you write. For "update X where Y", filterByFormula first to resolve the rec... ID, then PATCH /v0/$BASE_ID/$TABLE/$RECORD_ID. Never guess record IDs.
  5. Batch writes. Combine related creates into one 10-record POST to stay under the 5 req/sec budget.
  6. Destructive ops. Deletions can't be undone via API. If the user says "delete all Xs", echo back the filter + record count and confirm before firing.

Pitfalls

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
5

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/kayforkind/skill-slice/airtable/badge)](https://verified-skill.com/skills/kayforkind/skill-slice/airtable)

Something wrong with this skill or its page? Tell us.