Airtable Master

This is NOT a user-facing skill. It's a shared resource library.

Purpose

Provides shared resources to eliminate duplication across:

```
airtable-connect
```
- Connect to bases, discover schema
```
airtable-query
```
- Query records with filters
```
airtable-sync
```
- Import/export records

Instead of loading this skill, users invoke the specific skill above.

Architecture: DRY Principle

Problem solved: Multiple Airtable skills would have duplicated content (setup instructions, API docs, error handling).

Solution: Extract shared content into

references/

and

scripts/

Result: Single source of truth, reduced context per skill.

Shared Resources

references/

setup-guide.md - Complete setup wizard

Creating Personal Access Token (PAT)
Configuring .env file
Selecting scopes
Validation steps

api-reference.md - API patterns

Base URL and headers
Key endpoints (bases, tables, records)
Pagination
Batch operations
Rate limits

error-handling.md - Troubleshooting

HTTP error codes (401, 403, 404, 422, 429)
Recovery patterns
Debugging tips

field-types.md - Field type reference

All 20+ Airtable field types
Read and write formats
Type-specific validation

scripts/

Configuration & Setup

check_airtable_config.py - Pre-flight validation

bash

python check_airtable_config.py [--verbose] [--json]

Argument	Required	Default	Description
`--verbose` / `-v`	No	False	Show detailed output
`--json`	No	False	Output structured JSON for AI consumption

Exit codes: 0=configured, 1=partial (no bases), 2=not configured

When to Use: Run this FIRST before any Airtable operation. Use to validate PAT is configured, test API connection, check base access, or diagnose authentication issues.

setup_airtable.py - Interactive setup wizard

bash

python setup_airtable.py [--non-interactive] [--api-key KEY]

Argument	Required	Default	Description
`--non-interactive`	No	False	Skip prompts (requires API key)
`--api-key`	No	-	API key for non-interactive mode

Default: Runs interactively. Guides through PAT creation, tests connection, saves to

.env

, auto-runs base discovery.

When to Use: Use when Airtable integration needs initial setup, when check_airtable_config.py returns exit code 2, or when user needs to reconfigure credentials or switch workspaces.

discover_bases.py - Base discovery (GET /meta/bases)

bash

python discover_bases.py [--refresh] [--json] [--with-schema]

Argument	Required	Default	Description
`--refresh`	No	False	Force re-discovery even if cache exists
`--json`	No	False	Output as JSON only (no progress messages)
`--with-schema`	No	False	Also fetch table schemas (slower)

Saves to:

01-memory/integrations/airtable-bases.yaml

When to Use: Use when user asks "what bases do I have", "list my airtable bases", "show tables", after adding new bases, or when base/table name resolution fails (--refresh to update cache).

Record Operations

query_records.py - Query records from table (GET /{baseId}/{tableIdOrName})

bash

python query_records.py --base BASE --table TABLE [--filter FORMULA] [--fields FIELDS] [--view VIEW] [--sort FIELD] [--limit N] [--json] [--verbose]

Argument	Required	Default	Description
`--base`	Yes	-	Base ID (appXXX) or name
`--table`	Yes	-	Table ID (tblXXX) or name
`--filter`	No	-	Airtable formula filter
`--fields`	No	-	Comma-separated field names to retrieve
`--view`	No	-	View ID or name
`--sort`	No	-	Sort field (prefix with `-` for descending)
`--limit`	No	-	Max records to return
`--json`	No	False	Output as JSON
`--verbose` / `-v`	No	False	Show debug info

Filter Formula Examples:

bash

--filter "{Status}='Active'"
--filter "AND({Status}='Active', {Priority}='High')"
--filter "SEARCH('john', LOWER({Name}))"
--filter "{Due Date} < TODAY()"

When to Use: Use when user wants to read records from a table, search with filters, list data from Airtable, or retrieve specific records. Supports Airtable formula syntax for complex filters.

manage_records.py - CRUD operations (POST/PATCH/PUT/DELETE /{baseId}/{tableIdOrName})

bash

# Create record(s)
python manage_records.py create --base BASE --table TABLE --data JSON [--file FILE] [--typecast] [--json] [--verbose]

# Update record(s)
python manage_records.py update --base BASE --table TABLE --record RECID --data JSON [--file FILE] [--typecast] [--replace] [--json] [--verbose]

# Delete record(s)
python manage_records.py delete --base BASE --table TABLE --record RECID [--file FILE] [--json] [--verbose]

Argument	Required	Default	Description
`action`	Yes	-	Action: `create` , `update` , `delete` (positional)
`--base`	Yes	-	Base ID (appXXX) or name
`--table`	Yes	-	Table ID (tblXXX) or name
`--record`	No*	-	Record ID (for update/delete single record)
`--data`	No*	-	JSON data for fields
`--file`	No*	-	JSON file with record(s) data
`--typecast`	No	False	Enable automatic type conversion
`--replace`	No	False	Replace mode for update (PUT vs PATCH)
`--json`	No	False	Output as JSON
`--verbose` / `-v`	No	False	Show debug info

*For create:

--data

--file

required *For update:

--record

--data

--file

required *For delete:

--record

--file

required

Usage Examples:

bash

# Create a single record
python manage_records.py create --base "My CRM" --table "Contacts" \
    --data '{"Name": "John Doe", "Email": "john@example.com"}'

# Create multiple records from file
python manage_records.py create --base appXXX --table tblYYY --file records.json

# Update a record
python manage_records.py update --base "Tasks" --table "Tasks" \
    --record recXXX --data '{"Status": "Done"}'

# Delete a record
python manage_records.py delete --base "Tasks" --table "Tasks" --record recXXX

# Batch operations with typecast
python manage_records.py create --base "CRM" --table "Leads" \
    --file leads.json --typecast

Batch Limits: Max 10 records per API call (script handles batching automatically)

When to Use: Use

create

when user wants to add new records,

update

to modify existing records (PATCH=partial, PUT=replace),

delete

to remove records. Supports batch operations from JSON files.

Intelligent Error Detection Flow

When an Airtable skill fails due to missing configuration, the AI should:

Step 1: Run Config Check with JSON Output

bash

python 00-system/skills/airtable/airtable-master/scripts/check_airtable_config.py --json

Step 2: Parse the

ai_action

Field

The JSON output includes an

ai_action

field that tells the AI what to do:

ai_action	What to Do
`proceed_with_operation`	Config OK, continue with the original operation
`proceed_with_warning`	Partial config (API works but no bases accessible)
`prompt_for_api_key`	Ask user: "I need your Airtable API key. Get one at https://airtable.com/create/tokens"
`run_setup_wizard`	Run: `python 00-system/skills/airtable/airtable-master/scripts/setup_airtable.py`

Step 3: Help User Fix Issues

ai_action

prompt_for_api_key

Tell user: "Airtable integration needs setup. I need your Personal Access Token (PAT)."
Show them: "Get one at: https://airtable.com/create/tokens"
Guide them through scopes: "Add scopes: data.records:read, data.records:write, schema.bases:read"
Ask: "Paste your Airtable PAT here (starts with 'pat.'):"

Once they provide it, write directly to
.env
:

# Edit .env file to add:
AIRTABLE_API_KEY=pat.their_token_here

Re-run config check to verify

JSON Output Structure

json

{
  "status": "not_configured",
  "exit_code": 2,
  "ai_action": "prompt_for_api_key",
  "missing": [
    {"item": "AIRTABLE_API_KEY", "required": true, "location": ".env"}
  ],
  "fix_instructions": [...],
  "env_template": "AIRTABLE_API_KEY=pat.YOUR_TOKEN_HERE",
  "setup_wizard": "python 00-system/skills/airtable/airtable-master/scripts/setup_airtable.py"
}

How Skills Reference This

Each skill loads shared resources only when needed (progressive disclosure):

airtable-connect uses:

```
check_airtable_config.py
```
(validate before connection)
```
discover_bases.py
```
(find and cache bases)
```
api-reference.md
```
(schema endpoints)
```
error-handling.md
```
(troubleshooting)

airtable-query uses:

```
check_airtable_config.py
```
(validate before query)
```
query_records.py
```
(list/filter records)
```
api-reference.md
```
(query patterns)
```
field-types.md
```
(interpret results)

airtable-sync uses:

```
check_airtable_config.py
```
(validate before sync)
```
manage_records.py
```
(CRUD operations)
```
api-reference.md
```
(batch patterns)
```
error-handling.md
```
(recovery)

Usage Example

User says: "query my Projects base in Airtable"

What happens:

AI loads
```
airtable-connect
```
(NOT airtable-master)
```
airtable-connect
```
SKILL.md says: "Run check_airtable_config.py first"

AI executes:

python 00-system/skills/airtable/airtable-master/scripts/check_airtable_config.py --json

If exit code 2, AI prompts user for API key and helps them set up

If exit code 0, AI executes:

python 00-system/skills/airtable/airtable-master/scripts/query_records.py --base "Projects"

If errors occur, AI loads:

airtable-master/references/error-handling.md

airtable-master is NEVER loaded directly - it's just a resource library.

Key Differences from Notion

Aspect	Airtable	Notion
Auth	Personal Access Token (PAT)	Integration Token
Rate Limit	5 req/s per base	3 req/s
Batch Size	10 records	Variable
Pagination	Offset-based	Cursor-based
Field Types	20+ types	20+ property types

Version: 1.3 Created: 2025-12-11 Updated: 2025-12-11 Status: Production Ready

Changelog:

v1.3: Added "When to Use" sections to all 5 scripts for AI routing guidance
v1.2: Added comprehensive script argument documentation with usage examples and argument tables
v1.1: Added Intelligent Error Detection Flow with
```
--json
```
support, added setup_airtable.py
v1.0: Initial release

airtable-master

NPX Install

Tags

SKILL.md Content

Airtable Master

Purpose

Architecture: DRY Principle

Shared Resources

references/

scripts/

Configuration & Setup

Record Operations

Intelligent Error Detection Flow

Step 1: Run Config Check with JSON Output

Step 2: Parse the
`ai_action`
Field

Step 3: Help User Fix Issues

JSON Output Structure

How Skills Reference This

Usage Example

Key Differences from Notion