beam-ai-team/airtable-master

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

uv run 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

uv run 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)

uv run 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: 02-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})

uv run 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:

--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})

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

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

# Delete record(s)
uv run 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 or --file required *For update: --record + --data or --file required *For delete: --record or --file required

Usage Examples:

# Create a single record
uv run python manage_records.py create --base "My CRM" --table "Contacts" \
    --data '{"Name": "John Doe", "Email": "[email protected]"}'

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

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

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

# Batch operations with typecast
uv run 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

uv run 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

If ai_action is prompt_for_api_key:

1. Tell user: "Airtable integration needs setup. I need your Personal Access Token (PAT)."
2. Show them: "Get one at: https://airtable.com/create/tokens"
3. Guide them through scopes: "Add scopes: data.records:read, data.records:write, schema.bases:read"
4. Ask: "Paste your Airtable PAT here (starts with 'pat.'):"
5. Once they provide it, write directly to .env:

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

6. Re-run config check to verify

JSON Output Structure

{
  "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:

1. AI loads airtable-connect (NOT airtable-master)
2. airtable-connect SKILL.md says: "Run check_airtable_config.py first"
3. AI executes: python 00-system/skills/airtable/airtable-master/scripts/check_airtable_config.py --json
4. If exit code 2, AI prompts user for API key and helps them set up
5. If exit code 0, AI executes: python 00-system/skills/airtable/airtable-master/scripts/query_records.py --base "Projects"
6. 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