Portability & Extensions

⚠️ Experimental — Squad is alpha software. APIs, commands, and behavior may change between releases.

Your squad isn’t locked to one repo, one editor, or one set of tools. Export a trained team and import it somewhere else. Install plugins for instant expertise. Inherit org-wide practices from upstream repos. Wire up MCP servers so agents can talk to anything.

Try This

Export my team to a file — I want to use them on another project

Install the AWS deployment plugin

Add the platform team's repo as an upstream source

How It Works

Squad is designed to be portable by default. Four systems make this possible:

Your Repo (.squad/)
    ↑ inherits from
Upstream Sources (org repo, sibling repo, export snapshot)
    ↑ enhanced by
Plugins (community marketplaces)
    ↑ connected to
MCP Servers (GitHub, Teams, Trello, Aspire, etc.)

Export & Import

Squad teams are portable. Export your trained agents, casting state, skills, and decisions to a single JSON file.

Export

squad export                          # creates squad-export.json
squad export --out ./backups/team.json  # custom path

What’s Included

Skills are fully portable — they export and import with perfect fidelity.

Import

squad import squad-export.json

If .squad/ already exists, Squad warns you and stops. Use --force to archive the existing team and replace it:

squad import squad-export.json --force

Nothing is deleted — the current team moves to an archive.

History Splitting

During import, agent histories are split into:

• Portable knowledge — general patterns and conventions that transfer across projects
• Project-specific learnings — context-tagged entries tied to the original repo

Imported agents bring their skills and general knowledge without assuming your project works the same way.

Plugins

Plugins are community-curated bundles of agent templates, skills, and best practices. Install one and your agents get instant expertise.

What’s in a Plugin

• Agent templates — specialized role charters (e.g., “AWS DevOps”, “Python Data Science”)
• Skills — reusable .squad/skills/SKILL.md files
• Instructions — decisions.md snippets for conventions and routing
• Sample prompts — ready-to-use prompts that activate plugin capabilities

Available Marketplaces

Installing a Plugin

Install the react-component-library plugin from awesome-copilot

Or use the command:

/plugin install awesome-copilot/react-component-library

Squad downloads the bundle, merges agent templates into .squad/agents/, adds skills to .squad/skills/, updates decisions.md, and seeds agents with the new knowledge.

Managing Marketplaces

/plugin marketplace add github/awesome-copilot       # register
/plugin marketplace browse awesome-copilot            # browse
/plugin marketplace remove awesome-copilot            # unregister

Installed plugins remain even after removing a marketplace — you just can’t install new ones from it.

Creating Your Own Marketplace

A plugin marketplace is just a GitHub repo with a specific structure:

my-team-plugins/
├── awesome-patterns/
│   ├── charter.md
│   ├── skills/
│   │   └── awesome-skill.md
│   └── decisions.md
├── microservices-template/
│   ├── charter.md
│   └── skills/
│       ├── service-discovery.md
│       └── fault-tolerance.md
└── README.md

Register it with squad and your team can install from it.

Upstream Inheritance

Declare external Squad sources and automatically inherit their context at session start. Knowledge flows down from org → team → repo without duplicating configuration.

Three Source Types

What Gets Inherited

• Skills — all .squad/skills/*/SKILL.md files
• Decisions — .squad/decisions.md
• Wisdom — .squad/identity/wisdom.md
• Casting Policy — .squad/casting/policy.json
• Routing — .squad/routing.md

Closest-Wins Resolution

Org-level upstream
    ↓
Team-level upstream
    ↓
Repo config (local .squad/)
    ↓
Agent instance

Upstreams are read in order from upstream.json — later entries override earlier ones for the same content type. Your local .squad/ always wins.

Quick Start

# Local upstream
squad upstream add ../org-practices/.squad --name org

# Git upstream
squad upstream add https://github.com/acme/platform-squad.git --name platform --ref main

# Export snapshot
squad upstream add ./exports/snapshot.json --name snapshot

# List configured upstreams
squad upstream list

# Sync git upstreams
squad upstream sync

Git upstreams clone to .squad/_upstream_repos/{name} (auto-added to .gitignore). Local and export upstreams are read live at session start — no sync needed.

MCP Setup

MCP (Model Context Protocol) servers extend Squad with external services. Agents discover and use MCP tools automatically — no per-agent configuration required.

Configuration

Example: GitHub MCP

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/github-mcp.js"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    }
  }
}

Use environment variables instead of hardcoding tokens:

export GITHUB_TOKEN=$(gh auth token)

Other Integrations

Agents discover tools at spawn time and use them naturally during work. See GitHub Integration for how notifications connect to your workflow.

VS Code Integration

Squad runs identically in VS Code — same .squad/ state, same agents, same decisions. Initialize with CLI, open in VS Code, and everything just works.

Key Differences from CLI

What’s the Same

• Same .squad/ directory and state
• Same team roster, skills, and decisions
• Parallel execution works (multiple agents per turn)
• MCP tools are inherited from workspace config

Tips

• Use single-root workspaces (multi-root has path resolution bugs)
• Accept file modification approval once — subsequent writes are automatic
• For heavy parallel work (5+ agents), SQL workflows, or per-spawn model selection → use CLI
• Check the model picker if agents seem slow — switch to Haiku for cost savings

Tips

• Export before running upgrade — it’s your rollback point.
• The export JSON is human-readable — inspect it to see exactly what your team knows.
• Imported agents keep their names and universe casting.
• Commit .squad/ after importing so everyone who clones the repo gets the team.
• Order matters in upstream.json — later entries override earlier ones. Use remove + add to reorder.

Sample Prompts

export the current team

Creates a squad-export.json snapshot of the entire team.

import squad-export.json into this repo

Imports a team snapshot into the current project’s .squad/ directory.

install the azure-infrastructure plugin for the DevOps agent

Downloads the Azure plugin and seeds the DevOps agent with cloud expertise.

show me available plugins for React development

Searches all configured marketplaces for React-related plugins.

add the platform team's repo as an upstream source

Inherits skills, decisions, and routing from a shared org repo.

show me all configured MCP servers and which ones are working

Tests each MCP server and reports status.

squad upstream sync

Updates all git upstream clones and validates local/export paths.

package our current React conventions into a plugin called react-best-practices

Exports your relevant skills and decisions into a reusable plugin bundle for sharing.