Pushing Skills

Push local Skills to your Bluebag project so they're available to your AI agents.

Basic Usage

Push all Skills from your configured skillsDir:

bluebag push

Push Specific Skills

Push only specific Skills by name:

bluebag push my-skill

Push multiple Skills:

bluebag push my-skill another-skill

Options

Force Push

Overwrite remote changes without prompting:

bluebag push --force

Use with caution—this will overwrite remote changes even if conflicts exist.

Dry Run

Preview what would be pushed without making changes:

bluebag push --dry-run

This shows which Skills would be created, updated, or skipped.

Push Workflow

When you run bluebag push, the CLI performs these steps:

1. Validation

The CLI validates each Skill locally:

• Checks for required SKILL.md file
• Validates YAML frontmatter (name and description)
• Ensures file types are allowed
• Verifies file size limits

If validation fails, the push is aborted with a detailed error message.

2. Conflict Detection

Compares local and remote versions:

• If the remote has changes you haven't pulled, you'll be prompted to resolve the conflict
• Use --force to skip conflict detection and overwrite remote

3. Upload

Files are uploaded directly to cloud storage:

• Progress is displayed for each Skill
• Large files are streamed efficiently
• Multiple files upload in parallel

4. Verification

The server automatically verifies your upload:

• You'll see "Verifying upload..." while the server checks the files
• Hash verification ensures file integrity
• Upload is complete when verification passes

Examples

Push All Skills

# Push everything in the skills directory
bluebag push

Push a Single Skill

# Push only the pdf-processing skill
bluebag push pdf-processing

Preview Before Pushing

# See what would be pushed
bluebag push --dry-run

# Then push if everything looks good
bluebag push

Force Overwrite Remote

# Overwrite remote changes (use carefully)
bluebag push --force

What Gets Pushed

The CLI pushes all files in each Skill directory, except:

• Hidden files and directories (starting with .)
• Files with unsupported extensions
• Files exceeding size limits

See Validation for details on what files are allowed.

After Pushing

Once pushed, your Skills are:

• Available in the Bluebag dashboard
• Loaded into sandbox sessions for your AI agents
• Synced with your team members who pull