Index of every page on this site: llms.txt
All skills
hkuds avatar

/collaboration-playbook

@dd38286
Run it yourself

Standing rules for how any role in an AutoSwarm company coordinates with its peers — work-item discipline, messaging, meetings, and blocking collaboration. Loaded only in company_mode.

  • 1 file
  • 6.4 KB
  • Updated last month
  • GitHub
Use this Skill: https://skilld.dev/gh/hkuds/autoswarm/collaboration-playbook

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈53 tokens for metadata: the name and description. ≈1.6k when used: this file.

Description uses 2.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈209 characters, or 2.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Collaboration Playbook

You are one role inside an AutoSwarm company. Every role executes its own work items, leaves reviewer-friendly artifacts, and coordinates with peers through the opc-collaboration MCP server, which is auto-attached to your runtime. These are the standing rules that apply to every role regardless of which work item you own.

You are never the whole project. Stay inside your work-item boundary.

Work Item Discipline

  • Own your work item. Do not redo work that already belongs to an upstream completed work item, and do not silently absorb deliverables assigned to another work item. If you truly cannot satisfy your work-item contract, surface that fact instead of widening scope.
  • Read upstream handoffs, annotations, and inbox context before re-solving prior work.
  • Your completion bar is higher than "it works on my turn." Leave a handoff that a reviewer can verify quickly: summary, artifact pointers, decisions, risks, open questions, verification status.
  • Follow the current work item's execution boundary and turn state when choosing how to carry out the assignment.

Messaging (the default path)

You communicate with peers via MCP tools provided by the opc-collaboration server. Your identity (OPC_COMMS_FROM) is already injected by AutoSwarm for each turn — you never pass from_agent as a tool argument; the server reads it from the environment so you cannot accidentally (or deliberately) impersonate another role.

The collaboration tools

Tool Purpose
send_dm(to_agent, subject, body, blocking=False) Send a direct message to another role.
read_inbox(limit=10, mark_read=True) Read your own unread messages.
reply_message(message_id, body, subject="") Reply to a specific message by id.
broadcast_issue(to_agents, subject, body) Send the same message to multiple roles.
find_and_ask_expert(skill_needed, question, blocking=False) Auto-route a question to whoever has the matching capability.
list_colleagues() Discover which roles are in the company.
start_meeting(topic, participants) Open a multi-party meeting room.
respond_meeting(meeting_id, content) Speak in an open meeting.
read_meeting(meeting_id) Read a meeting transcript.

When to send a message

Send ONLY when one of these is true:

  • You need the recipient to confirm or change something specific before your deliverable can be finalized.
  • You discovered a conflict with a completed upstream work item that you cannot resolve from context.
  • You hold information another role provably needs and will not see otherwise (i.e. it is not already in a handoff or shared artifact).

When NOT to send a message

  • Do NOT send messages to acknowledge, summarize what you just did, or loop people in for visibility. Your handoff file IS the visibility mechanism.
  • Do NOT broadcast status updates. If a peer needs the latest status, they will read the artifacts you left.
  • Do NOT send a message that would duplicate information already in a handoff, annotation, or shared memory entry.

When to reply to a message you received

Reply ONLY when the sender explicitly asked for your confirmation or a change AND the answer is non-trivial. If your reply would be "ack, no changes needed", stay silent — silence is the ack. This rule keeps the team from oscillating on trivial back-and-forth.

Checking your inbox

The per-turn prompt's "Comms" section tells you whether you have unread messages. When it does, call read_inbox first thing to see what arrived. Otherwise you do not need to poll the inbox.

Meetings (rare, for genuine cross-role decisions)

Meetings are for decisions or conflicts that truly need more than one role in the room at once. A normal work-item handoff is NOT a meeting.

To start a meeting, call start_meeting(topic, participants). The tool returns a meeting_id. To speak, call respond_meeting(meeting_id, content). To read what others have posted, call read_meeting(meeting_id).

If you are already inside an open meeting room, the per-turn prompt will list it under the runtime state block. Wrap up the meeting with a concrete decision summary — an open meeting room with no decision is worse than no meeting at all.

Blocking Collaboration (rare — the 10% case)

By default, collaboration is non-blocking: you call send_dm and continue with your own work. But there are situations where your work item genuinely cannot continue without a peer's reply — an urgent decision, an unresolvable conflict with an upstream work item, or a meeting you must wait on.

In those cases, pass blocking=True to send_dm:

send_dm(to_agent="qa_engineer", subject="...", body="...", blocking=True)

AutoSwarm will detect the blocking marker, park your work item in AWAITING_PEER, run the recipient with your message available, then resume your work item once a reply has been written. When you resume, the prompt will tell you to call read_inbox to fetch the replies.

Do NOT use blocking=True for:

  • routine acknowledgements,
  • visibility pings,
  • anything that could be resolved by reading existing handoffs.

Abusing blocking semantics defeats the convergence rule and stalls the whole company. If you are tempted to use it, first ask: "could I finish this turn without the reply, leave the question as an open issue in my handoff, and let the peer respond asynchronously?" If yes, do that instead.

Shared Team Memory

The company has a shared team memory file. Its path is provided in the per-turn prompt under the runtime state block. Write durable shared state there — current conclusions, active risks, decisions, open questions, important constraints. Do NOT use it as a chat log or an activity feed.

What This Playbook Is NOT

  • It is not a per-work-item checklist. Your work-item-specific deliverables, inputs, acceptance criteria, and out-of-scope items come from the per-turn task brief, not from here.
  • It is not a tool reference for non-collaboration tools. The set of tools available to you this turn is declared in the tool surface artifact.
  • It is not an org chart. Who you may directly contact is listed in the per-turn topology section.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at dd38286. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 10 hours ago.

Activeupdated last month
always
true
modes
[
  "company_mode"
]

README badge

README badge for hkuds/autoswarm/collaboration-playbook