OpenParable
Skip to content
← Back to skills

Cross Squad

Productivity
cross-squad

Cross Squad is an Agent Skill for productivity published in the CommunityToolkit/Aspire repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Coordinating work across multiple Squad instances

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/CommunityToolkit/Aspire/blob/HEAD/examples/squad/CommunityToolkit.Aspire.Hosting.Squad.AppHost/dev-squad/.squad/templates/skills/cross-squad/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cross-squad, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Context

When an organization runs multiple Squad instances (e.g., platform-squad, frontend-squad, data-squad), those squads need to discover each other, share context, and hand off work across repository boundaries. This skill teaches agents how to coordinate across squads without creating tight coupling.

Cross-squad orchestration applies when:

  • A task requires capabilities owned by another squad
  • An architectural decision affects multiple squads
  • A feature spans multiple repositories with different squads
  • A squad needs to request infrastructure, tooling, or support from another squad

Patterns

Discovery via Manifest

Each squad publishes a .squad/manifest.json declaring its name, capabilities, and contact information. Squads discover each other through:

  1. Well-known paths: Check .squad/manifest.json in known org repos
  2. Upstream config: Squads already listed in .squad/upstream.json are checked for manifests
  3. Explicit registry: A central squad-registry.json can list all squads in an org
{
  "name": "platform-squad",
  "version": "1.0.0",
  "description": "Platform infrastructure team",
  "capabilities": ["kubernetes", "helm", "monitoring", "ci-cd"],
  "contact": {
    "repo": "org/platform",
    "labels": ["squad:platform"]
  },
  "accepts": ["issues", "prs"],
  "skills": ["helm-developer", "operator-developer", "pipeline-engineer"]
}

Context Sharing

When delegating work, share only what the target squad needs:

  • Capability list: What this squad can do (from manifest)
  • Relevant decisions: Only decisions that affect the target squad
  • Handoff context: A concise description of why this work is being delegated

Do NOT share:

  • Internal team state (casting history, session logs)
  • Full decision archives (send only relevant excerpts)
  • Authentication credentials or secrets

Work Handoff Protocol

  1. Check manifest: Verify the target squad accepts the work type (issues, PRs)
  2. Create issue: Use gh issue create in the target repo with:
    • Title: [cross-squad] <description>
    • Label: squad:cross-squad (or the squad's configured label)
    • Body: Context, acceptance criteria, and link back to originating issue
  3. Track: Record the cross-squad issue URL in the originating squad's orchestration log
  4. Poll: Periodically check if the delegated issue is closed/completed

Feedback Loop

Track delegated work completion:

  • Poll target issue status via gh issue view
  • Update originating issue with status changes
  • Close the feedback loop when delegated work merges

Examples

Discovering squads

# List all squads discoverable from upstreams and known repos
squad discover

# Output:
#   platform-squad  →  org/platform  (kubernetes, helm, monitoring)
#   frontend-squad  →  org/frontend  (react, nextjs, storybook)
#   data-squad      →  org/data      (spark, airflow, dbt)

Delegating work

# Delegate a task to the platform squad
squad delegate platform-squad "Add Prometheus metrics endpoint for the auth service"

# Creates issue in org/platform with cross-squad label and context

Manifest in squad.config.ts

export default defineSquad({
  manifest: {
    name: 'platform-squad',
    capabilities: ['kubernetes', 'helm'],
    contact: { repo: 'org/platform', labels: ['squad:platform'] },
    accepts: ['issues', 'prs'],
    skills: ['helm-developer', 'operator-developer'],
  },
});

Anti-Patterns

  • Direct file writes across repos — Never modify another squad's .squad/ directory. Use issues and PRs as the communication protocol.
  • Tight coupling — Don't depend on another squad's internal structure. Use the manifest as the public API contract.
  • Unbounded delegation — Always include acceptance criteria and a timeout. Don't create open-ended requests.
  • Skipping discovery — Don't hardcode squad locations. Use manifests and the discovery protocol.
  • Sharing secrets — Never include credentials, tokens, or internal URLs in cross-squad issues.
  • Circular delegation — Track delegation chains. If squad A delegates to B which delegates back to A, something is wrong.