Best Practices

Follow these best practices to get the most out of the Bluebag CLI and keep your team's Skills in sync.

Version Control

Commit Configuration

Add .bluebagrc to your version control:

git add .bluebagrc
git commit -m "Add Bluebag configuration"

This ensures your team syncs with the same project.

Ignore Sync State

Add .bluebag/ to your .gitignore:

.bluebag/

The CLI creates this directory to track sync state—it shouldn't be committed.

Commit Skills

Keep your Skills in version control alongside your code:

git add skills/
git commit -m "Add pdf-processing skill"

This provides:

• History of changes
• Ability to revert mistakes
• Code review for Skill changes

Sync Workflow

Pull Before Working

Always pull the latest changes before starting work:

bluebag pull

This minimizes conflicts with teammates.

Push When Done

Push your changes when you finish:

bluebag push

Don't wait too long—frequent pushes reduce merge conflicts.

Preview with Dry Run

Use dry-run to preview changes before committing:

bluebag push --dry-run

This helps catch issues before they affect your remote Skills.

Naming Conventions

Descriptive Skill Names

Use clear, descriptive names that indicate what the Skill does:

Consistent Patterns

Use consistent naming patterns across your project:

• {domain}-{action}: pdf-extraction, image-resize
• {feature}-{version}: analytics-v2, reporting-v3

Documentation

Document Your Skills

Include clear instructions in your SKILL.md:

• What the Skill does
• When to use it
• How to use it (with examples)
• Requirements or dependencies

Example Structure

---
name: pdf-processing
description: Extract text and tables from PDF files.
---

# PDF Processing

## When to Use

Use this skill when:

- Extracting text from PDF documents
- Converting PDF tables to structured data

## Usage

```bash
python /skills/pdf-processing/scripts/extract.py document.pdf

Dependencies

Requires pdfplumber (installed automatically via requirements.txt).

## Testing

### Test Locally First

Before pushing, test your Skills locally:

1. Verify `SKILL.md` parses correctly
2. Run scripts to ensure they work
3. Check all dependencies are declared

### Use Dry Run

Preview changes before pushing:

```bash
bluebag push --dry-run

Test After Pushing

After pushing, verify in the Bluebag dashboard that:

• All files uploaded correctly
• The Skill appears in your project
• No validation errors occurred

Team Collaboration

Communicate Changes

Let your team know when you push significant changes to shared Skills.

Avoid Simultaneous Edits

Coordinate with teammates to avoid editing the same Skill simultaneously.

Review Changes

Consider using pull requests for Skill changes:

1. Create a branch for your changes
2. Make and test changes locally
3. Create a PR for team review
4. Merge and push after approval

Organization

Group Related Skills

Organize related Skills in your project:

skills/
  pdf/
    pdf-extraction/
    pdf-merge/
  data/
    csv-analysis/
    json-transform/

Separate Concerns

Keep Skills focused on single tasks:

Security

Don't Commit Secrets

Never include secrets in your Skills:

• API keys
• Passwords
• Private credentials

Use environment variables instead.

Review Before Pushing

Always review what you're pushing:

bluebag push --dry-run

Ensure no sensitive data is included.