beam-ai-team/share-skill

Share Skill to Marketplace

Upload your local skill to the central Skill Marketplace (Airtable) for others to use.

Safety Contract

Before uploading or publishing a skill, show the skill path, files bundled, target marketplace/base/table, visibility/team metadata, and any secrets or private references found during validation. Require explicit user approval in the current turn before uploading to Airtable or sharing externally. Local validation and bundle previews do not require approval.

Purpose

Push any skill from skills/general/ or skills/ to the shared marketplace. Handles:

• Validating SKILL.md format
• Creating JSON bundle with all skill files
• Uploading to Airtable Skills table
• Handling large skills via SkillFiles table

Typically used after create-skill to share new skills with the team.

---

Quick Start

# Upload a single skill
uv run python skills/integrations/airtable/airtable-master/scripts/upload_local_skills.py \
  --base app1gngDx52VAgjVQ --table tblsQL8n9EfMAFIyD \
  --token MUTAGENT --skill-path skills/general/my-skill

# Upload all local skills (batch)
uv run python skills/integrations/airtable/airtable-master/scripts/upload_local_skills.py \
  --base app1gngDx52VAgjVQ --table tblsQL8n9EfMAFIyD \
  --token MUTAGENT

---

Workflow

Step 1: Validate Your Skill

Ensure your skill has a valid SKILL.md:

---
name: my-skill
description: Load when user mentions "trigger phrase"...
version: 1.0
---

# My Skill

## Purpose

What this skill does...

Required fields:

• name - Skill identifier (lowercase, hyphenated)
• description - Must include trigger phrases

Optional fields:

• version - Defaults to 1.0
• team - Defaults to General

Step 2: Preview Upload (Dry Run)

uv run python skills/integrations/airtable/airtable-master/scripts/upload_local_skills.py \
  --base app1gngDx52VAgjVQ --table tblsQL8n9EfMAFIyD \
  --token MUTAGENT --skill-path skills/general/my-skill --dry-run

Output:

[DRY-RUN] Would upload: my-skill
  Version: 1.0
  Team: General
  Files: 3 (SKILL.md, scripts/helper.py, references/guide.md)
  Bundle size: 4,521 bytes

Step 3: Upload to Marketplace

uv run python skills/integrations/airtable/airtable-master/scripts/upload_local_skills.py \
  --base app1gngDx52VAgjVQ --table tblsQL8n9EfMAFIyD \
  --token MUTAGENT --skill-path skills/general/my-skill

Output:

my-skill... OK (created recXXX)

Step 4: Handle Large Skills

If skill is too large (>90KB), it becomes a "partial" bundle. Upload files separately:

uv run python skills/integrations/airtable/airtable-master/scripts/upload_skill_files.py \
  --base app1gngDx52VAgjVQ --table tblhx8DRvcHN7GWmJ \
  --token MUTAGENT --skill my-skill

---

Parameters

| Parameter | Required | Description | |-----------|----------|-------------| | --skill-path | No | Path to single skill (default: all skills) | | --dry-run | No | Preview without uploading | | --force | No | Update existing skill | | --json | No | Output as JSON |

---

Marketplace Details

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

---

Bundle Format

Skills are packaged as JSON bundles:

{
  "skill_name": "my-skill",
  "version": "1.0",
  "bundle_format": "beam-next-skill-bundle-v1",
  "created": "2025-12-31T12:00:00",
  "files": {
    "SKILL.md": "<base64-encoded>",
    "scripts/helper.py": "<base64-encoded>",
    "references/guide.md": "<base64-encoded>"
  },
  "partial": false
}

Included files:

• SKILL.md (required)
• scripts/ folder
• references/ folder
• assets/ folder

Excluded:

• .git/
• pycache/
• *.pyc
• node_modules/

---

Team Assignment

Set team in SKILL.md frontmatter:

---
name: my-skill
description: ...
team: Solutions
---

Available teams:

• General - Company-wide utilities
• Solutions - Client implementation
• Engineering - Dev tools
• Sales - Sales workflows
• Integration-specific: google, slack, hubspot, langfuse, etc.

---

Version Management

---
name: my-skill
version: 1.1
---

Version format: MAJOR.MINOR or MAJOR.MINOR.PATCH

| Change | Bump | |--------|------| | Bug fix | 1.0 → 1.1 | | New feature | 1.1 → 1.2 | | Breaking change | 1.x → 2.0 |

---

Example Session

User: "share my new gmail-helper skill"

AI: Uploading gmail-helper to Skill Marketplace...

    Validating SKILL.md... OK
    Creating bundle... 3 files, 2,845 bytes

    uv run python upload_local_skills.py --base app1gngDx52VAgjVQ \
      --table tblsQL8n9EfMAFIyD --token MUTAGENT \
      --skill-path skills/general/gmail-helper

    gmail-helper... OK (created recABC123)

    Skill uploaded to marketplace.
    Others can now import it with: "import gmail-helper"

---

Updating Existing Skills

To update a skill that already exists:

--force  # Overwrite existing record

Or delete from Airtable first and re-upload.

---

Troubleshooting

| Error | Solution | |-------|----------| | Skill already exists | Use --force to update | | Bundle too large | Use upload_skill_files.py for linked files | | Missing SKILL.md | Every skill needs SKILL.md | | Invalid YAML | Check frontmatter format | | Permission denied | Check AIRTABLE_API_KEY_MUTAGENT in .env |

---

Related Skills

• create-skill - Create a new skill locally
• import-skill - Download from marketplace
• search-skill-database - Browse available skills

---

Skill Marketplace powered by Airtable