cross-agent-coordination

Cross-Agent Coordination

Cross-platform Agent task coordination hub. The core responsibility is to let Agents on different platforms allocate tasks around the task source specified by project configuration or project context, preserve handoff context, and mark Agent attribution in commits/PRs.

1. When to Use

Use this Skill:

• Agents on multiple different platforms need to collaborate in the same repository
• Need to trace which Agent completed a certain commit/PR
• Need to dispatch tasks to external Agents such as Manus, AnyGen, Coze, etc.
• Need to preserve task context, dependencies, and handoff records across sessions

Do not use this Skill:

• Parallel execution within a single platform: use multi-agent-orchestration
• Pure Git safety rules: use git-workflow

2. Core Rules

1. Task source is defined by the project: The regular task status is based on the task source specified by project configuration or project context; the task folder is only a material package, artifact package, and handoff package.
2. Attribution first: Git Author must be set before committing; the PR body should include Agent Attribution.
3. Tasks are executed according to assignment: By default, only process tasks in the project task source whose assignee/delegate matches the current Agent.
4. Project can be configured: Task types, templates, status mappings, and claim strategies are determined by project-level configuration, without modifying the Skill source code.
5. Handoffs are traceable: Issue, task README, or .agent-context/handoff.md must record the goal, source, decisions, blockers, and next steps.

3. Project Configuration

The project root directory uses a locally ignored configuration:

cp .claude/skills/cross-agent-coordination/config/collab.yaml.example config/collab.yaml

Key fields (example; the specific task source is determined by the project):

project:
  mode: task_folders          # task_folders | single_repo
  default_agent: codex
  issue_file: project-tasks.md
  task_context_mode: issues_primary
  status_map:
    "⬜": pending_confirmation
    "✅": ready
    "🟢": created
  available_statuses: [ready, created, todo]
  dependency_done_statuses: [ready, created, done, resolved, closed]
  claim_policy: assigned_only # assigned_only | claim_pool
  task_types_file: config/task-types.yaml
  template_dir: templates/tasks

agents:
  codex:
    name: "Codex"
    email: "codex@agents.local"
    github_user: "codex-bot"
    token_env: "CODEX_GITHUB_TOKEN"

The configuration path is fixed to config/collab.yaml. The old github-monorepo-collab and config/monorepo.yaml are no longer read.

4. Task Model

The project.issue_file in the project configuration or the task file specified by the project context is the default entry point for scripts to read tasks. Scripts can parse the following format:

### ✅ Issue #9: 触发 Manus 调研任务

- **类型**: 研究（委托 Manus）
- **依赖**: Issue #7 确定后
- **目标**: 为 ch03 法律 AI 基础设施章节提供调研支撑

#### 验收标准
- [ ] 形成产品对比表

Parsed fields include Issue number, title, status marker, type, assignee/delegated Agent, dependencies, goal, material source, and acceptance criteria. Status is mapped by project.status_map ;find_task.py --available only returns Issues whose status is executable, dependencies are satisfied, and assignee matches.

The task folder mode can still use {YYMMDDNNN}-{type}-{title}/README.md, but it is a heavy-task material package/artifact package/handoff package and does not override the primary task source status:

---
id: 260517001
title: 法律AI产品生态调查
type: 研究
status: todo
assignee: manus
dependencies: []
artifact_paths: []
progress: 0
created: 2026-05-17
updated: 2026-05-17
---

assignee is the material package assignee field;agent is only read for backward compatibility with old tasks and is no longer a required field for new tasks. Task folder dependencies are still determined by done / resolved / closed ; Issue dependencies are determined by dependency_done_statuses .

The project can extend task types in config/task-types.yaml :

task_types:
  整合:
    aliases: [integration]
    description: 多来源材料融合
    output_hint: 统一稿/整合报告
  审阅:
    aliases: [review]
    description: 质量审查/事实核查
    output_hint: 审阅意见/修订稿

The project can define task README templates in templates/tasks/{type}.md or templates/tasks/default.md . Template variables use {{ id }}、{{ slug }}、{{ title }}、{{ type }}、{{ assignee }}、{{ created }}、{{ updated }}。

5. Dependencies

Python packages

Package name	Purpose	Install command
PyYAML	Read collab.yaml、task-types.yaml and frontmatter	python3 -m pip install -r scripts/requirements.txt

Install dependencies (only when the script reports they are missing):

python3 -m pip install -r scripts/requirements.txt

6. Common scripts

Script	Purpose
scripts/task_scaffold.py	Create a task folder, allocate a stable Task ID, and write the README according to the project template
scripts/find_task.py	Search project task sources and task folders by topic, with support for --available dependency/assignment filters
scripts/gh_git.py	clone/branch/commit/push/PR/merge with Agent attribution
scripts/email_trigger.py	Generate a standard email trigger draft for an external Agent
scripts/audit_repo.py	Audit whether task metadata is consistent with the project type registry

Example:

python3 scripts/task_scaffold.py create --root . --type 研究 --topic "法律AI产品生态调查" --assignee manus
python3 scripts/task_scaffold.py create --root . --type 写作 --topic "ch01 Agent发展阶段" --field chapter=ch01 --field target_words=15000
python3 scripts/find_task.py . --available --agent manus
python3 scripts/gh_git.py commit --dest . --agent manus --message "docs: update handoff"
python3 scripts/gh_git.py pr --dest . --agent manus --title "docs: Manus handoff update"
python3 scripts/email_trigger.py . --agent manus --issue 9

7. Agent attribution

Each commit involves two layers of identity:

Layer	Control method	What it proves
Git Author	git config user.name / user.email	Who wrote the commit content
GitHub Actor / PR Opener	The Token or GitHub App used	Which account performs platform operations

The script sets the Git Author. The PR Opener is determined by the token; if the PR actor needs to distinguish Agents, a separate token environment variable must be configured for that Agent. For detailed rules, see references/agent-identity.md。

8. Workflow

Issue / Task primary state mode

1. Read config/collab.yaml、config/task-types.yaml, the project template, and project context.
2. Use find_task.py --available --agent <agent-id> to claim an executable task from the project task source.
3. Only when a task requires substantial materials, artifacts, or handoff records, use task_scaffold.py create to create or reuse a task folder.
4. Work on the agent/{agent-id}/{slug} branch.
5. When committing, use gh_git.py commit to mark the Git Author.
6. After completion, update the project task source status; if there is a task folder, also update the README handoff record and open a PR.

If an Issue / Task is not resolved through a PR but directly on the current branch or main , the commit message must still retain the task source. The specific commit format, reference format, and closing rules for GitHub Issues, project-local task entries, or task folder IDs follow git-workflow; this Skill is only responsible for confirming the task source and handoff context.

Single Repo mode

Do not create a task folder; still use Agent branches, Git Author, PR Attribution, and .agent-context/handoff.md to retain handoff context.

Email trigger

For external Agents that support an email entry point, use email_trigger.py to generate a draft. The email can be linked via --issue to a task in the project task source and include the goal, acceptance criteria, source materials, dependencies, duplicate-check command, branch, and PR requirements. By default, real emails are not sent.

External Agent Adapter

External Agents (such as Manus, AnyGen, Coze) serve only as execution channels or capability adapters and do not own task state. The project should declare the Agent's capabilities and trigger method in the config/collab.yaml of agents.<id> :

agents:
  manus:
    name: "Manus Bot"
    email: "manus@agents.local"
    github_user: "manus-bot"
    token_env: "MANUS_GITHUB_TOKEN"
    trigger_email: "manus-agent-inbox@example.com"
    capabilities: [web_research, citation_collection]
    trigger_modes: [email_draft]
    handoff_format: pull_request

Adapter selection rules:

• Complex web search, material collection, web operations: preferentially assign to Agents with web_research / browser_ops capabilities.
• Image generation, visual assets: preferentially assign to Agents with image_generation capabilities.
• Code changes, local testing, worktree execution: hand over to local Agents, with multi-agent-orchestration managing the session.
• Any adapter must bind to a task in the project task source or first perform a duplicate check; results return to the repository through branches, PRs, and handoff notes.

9. Reference documents

• references/naming.md: Task naming, frontmatter, archive rules
• references/agent-guide.md: Agent startup, handoff, and completion checklists
• references/agent-identity.md: Git Author and GitHub Actor attribution
• references/email-trigger.md: Email trigger protocol
• references/legacy-migration.md: Legacy task migration prompt

10. Related Skills

Dimension	cross-agent-coordination	multi-agent-orchestration	git-workflow
Positioning	Task coordination layer	Local execution layer	Git security layer
Primary responsibility	Project task source status, Agent attribution, handoff context	Agent Teams / tmux sessions, worktree, PM inspection	Branches, PRs, diffs, reviews, merge security rules
Not responsible for	Local session management, Git merge strategy	Task primary status, external Agent email triggers	Task assignment, local Agent scheduling

Collaboration mode: first by cross-agent-coordination determine the task from the project task source; when parallel execution is required on the same platform, use multi-agent-orchestration; when branches, PRs, reviews, or merges are involved, follow git-workflow。