beam-ai-team/import-skill

Import Skill from Marketplace

Download skills from the central Skill Marketplace (Airtable) into your local Beam Next.

Safety Contract

Before downloading or importing skills, show the marketplace source, skill names, output directory, files to create or overwrite, backup path, and credential/environment variable used. Require explicit user approval in the current turn before writing files or overwriting existing skills. Searching/listing marketplace entries in dry-run mode does not require approval.

Purpose

Pull any skill from our shared 120+ skill database directly into skills/general/. Handles:

• Searching available skills
• Downloading complete skill bundles (including large skills via linked files)
• Auto-backup of existing skills before overwriting
• Batch import of multiple skills

---

Quick Start

# Import a specific skill
uv run python skills/integrations/airtable/airtable-master/scripts/download_skill.py \
  --base app1gngDx52VAgjVQ --table tblsQL8n9EfMAFIyD \
  --files-table tblhx8DRvcHN7GWmJ \
  --skill "gmail" --token MUTAGENT --output 01-skills

# List all available skills (dry-run)
uv run python skills/integrations/airtable/airtable-master/scripts/download_skill.py \
  --base app1gngDx52VAgjVQ --table tblsQL8n9EfMAFIyD \
  --all --token MUTAGENT --dry-run

---

Workflow

Step 1: Search Available Skills

First, find what you need:

# Search by name
uv run python skills/integrations/airtable/airtable-master/scripts/query_records.py \
  --base app1gngDx52VAgjVQ --table tblsQL8n9EfMAFIyD \
  --token MUTAGENT --fields "Name,Description,Team" \
  --filter "{Name} contains 'gmail'"

# List all skills
uv run python skills/integrations/airtable/airtable-master/scripts/query_records.py \
  --base app1gngDx52VAgjVQ --table tblsQL8n9EfMAFIyD \
  --token MUTAGENT --fields "Name,Team" --limit 200

Step 2: Import the Skill

uv run python skills/integrations/airtable/airtable-master/scripts/download_skill.py \
  --base app1gngDx52VAgjVQ --table tblsQL8n9EfMAFIyD \
  --files-table tblhx8DRvcHN7GWmJ \
  --skill "<SKILL_NAME>" --token MUTAGENT --output 01-skills

Output:

Using token: AIRTABLE_API_KEY_MUTAGENT
Using linked files table: tblhx8DRvcHN7GWmJ
OK - Extracted 5 files (complete)

Step 3: Verify Import

ls skills/general/<skill-name>/
cat skills/general/<skill-name>/SKILL.md

---

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | --skill | Yes* | Skill name to import | | --all | Yes* | Import all skills (alternative to --skill) | | --output | No | Output directory (default: ./downloaded-skills) | | --files-table | No | SkillFiles table for large skills | | --no-backup | No | Skip backup of existing skills | | --dry-run | No | Show what would be imported |

*Either --skill or --all is required

---

Marketplace Details

| Property | Value | |----------|-------| | Base ID | app1gngDx52VAgjVQ | | Skills Table | tblsQL8n9EfMAFIyD | | Files Table | tblhx8DRvcHN7GWmJ | | Token | MUTAGENT | | Total Skills | 120+ |

---

Skill Categories

| Category | Examples | |----------|----------| | Integrations | gmail, slack, notion, airtable, hubspot, langfuse, fathom | | Google Suite | google-calendar, google-sheets, google-docs, google-slides | | AI/Agents | beam-connect, notebooklm, design-beam-agent | | Productivity | mental-models, ultrathink, create-meeting-minutes | | System | plan-project, close-session, validate-system |

---

Backup System

When importing a skill that already exists locally:

1. Existing skill is moved to <skill-name>.backup.<timestamp>
2. New skill is extracted
3. Backup remains in same directory

To restore:

rm -rf skills/general/my-skill
mv skills/general/my-skill.backup.20251231_120000 skills/general/my-skill

To skip backup:

--no-backup

---

Example Session

User: "import the gmail skill"

AI: Importing gmail from Skill Marketplace...

    uv run python download_skill.py --base app1gngDx52VAgjVQ \
      --table tblsQL8n9EfMAFIyD --files-table tblhx8DRvcHN7GWmJ \
      --skill "gmail" --token MUTAGENT --output 01-skills

    OK - Extracted 8 files (complete)

    Skill imported to: skills/general/gmail/

    Files:
    - SKILL.md
    - scripts/send_email.py
    - scripts/read_emails.py
    - scripts/search_emails.py
    - references/setup-guide.md
    ...

    Say "send email" to use this skill.

---

Troubleshooting

| Error | Solution | |-------|----------| | Skill not found | Check spelling, run search first | | No content | Skill has no bundle (metadata only) | | Permission denied | Check AIRTABLE_API_KEY_MUTAGENT in .env | | Partial bundle | Add --files-table for complete download |

---

Related Skills

• search-skill-database - Search the marketplace
• share-skill - Upload your skill to marketplace
• create-skill - Create a new skill locally

---

Skill Marketplace powered by Airtable