aduhappy/multi-agent-project-skill

Multi-Agent Collaboration Project Skeleton (Cross-Tool Resumable)

One-Line Installation (User Says "Install This Skill" – Execute Autonomously)

Source repo: https://github.com/aduhappy/multi-agent-project-skill. Clone it into your tool's skills directory (no other dependencies).

Different tools have different skills directories; choose the correct path for your tool:

Tool	User-Level Skills Directory	Project-Level Skills Directory
ZCode / Codex CLI	~/.agents/skills/	<project>/.agents/skills/
Claude Code	~/.claude/skills/	<project>/.claude/skills/
Cursor	N/A (use rules)	.cursor/rules/ (modern format) or .cursorrules (legacy)

General principles:

• On Windows, ~ = %USERPROFILE%.
• When unsure between user-level vs project-level, default to user-level (install once, use everywhere).
• Create the directory if it doesn't exist, then clone. After cloning, tell the user to start a new conversation to activate this skill.

What This Skill Does

It generates a tool-agnostic, pure Markdown collaboration skeleton in the project root — one authoritative entry point + several thin pointers + self-contained task cards + handoff conventions. Switching between Claude / Cursor / Gemini / ZCode / Copilot, any agent that reads the same entry point can pick up the predecessor's work without losing context or overwriting each other.

Four core principles:

1. Single Source of Truth: AGENTS.md is the sole authoritative entry point; all other tool-specific convention files (CLAUDE.md / GEMINI.md / .cursorrules / copilot-instructions.md) are 3-line thin pointers that redirect to AGENTS.md.
2. Keep Details External, Keep Entry Point Short: AGENTS.md is limited to 1–2 screens — every new agent must read it completely. Details are delegated to specialized documents under docs/, with the entry point only holding pointers.
3. Pure Markdown + Relative Paths: No tool-specific syntax; won't break when switching tools.
4. Trust but Verify: Agent self-checks are insufficient — key outputs must be independently reviewed by a controller or another agent (conservation/check/bounds/magnitude/consistency) before passing to the next step. This is the foundation of a trustworthy multi-agent pipeline.

When to Trigger

• User says "start a new project/topic," "how to organize docs for AI collaboration," "how to write AGENTS.md," or "multiple agents handing off."
• Existing project agents frequently ask the same questions, can't find status, or overwrite each other's outputs.
• User wants to solidify "manual collaboration experience" into a reusable structure.

How to Use (Two Modes)

Mode A: Generate Skeleton from Scratch

1. Ask (ask everything at once, don't drag it out): project root, one-sentence goal, which AI tools to support, whether cloud-synced directories exist, and relevant data sources.
2. Also ask for a hard constraint checklist: "List dimensions in this domain that must not be conflated (calibration/units/coordinate system/resolution/epoch/age class, etc.). Write them as hard rules that all subsequent agents must follow." — This is the most commonly overlooked rule, and getting it wrong breaks everything.
3. Copy AGENTS.md from assets/ to the root directory, filling in the user's provided content.
   • Placeholder rules (important): Fill in directly where the user provided info; if the user didn't provide something, prefer a reasonable default (inferred from the project topic) and briefly mark it as "default, can change"; only leave 【TODO】 for details that are user-specific and cannot be reasonably inferred (e.g., specific DOIs, passwords, accounts). Goal: minimize 【TODO】 in the AGENTS.md body; ideally zero.
4. For each tool the user selected, copy the corresponding thin pointer file (CLAUDE.md, GEMINI.md, copilot-instructions.md, etc.) with the unified content "Refer to AGENTS.md". For Cursor users, recommend .cursor/rules/multi-agent.mdc (modern format); .cursorrules as legacy fallback. Do not generate files for tools the user didn't select.
5. Create docs/task_plan_<topic>.md (copy from assets/task_plan_template.md). If the project has multiple task cards, also copy assets/task_card_README.md (task card directory index template listing dependency chains and current status). Each task card must include a 📋 Delegation Prompt (Copy & Use) block at the end — fill in the card's fields so the user can copy and paste it to any agent for a cold start, without rewriting delegation wording each time. Fill this block while building the card.
6. (Optional) Create as needed: docs/delegation_task_template.md (copy from assets/delegation_task_template.md, for the controller agent to delegate tasks), docs/decision_records/ (for ADRs), docs/glossary.md (project terminology). Note: These are optional templates; skip for small projects to keep the entry point lean.
7. Derive dataset directories: From the user-described data sources — one directory per data type (e.g., user says "MODIS + Landsat" → create MODIS/ and Landsat/ directories; user says "survey + measurements" → create survey/ and measurements/). Place a source.txt file in each dataset directory (copy from assets/source.txt). Skip this step for projects without explicit data sources.
8. Organize code: Create scripts/ directory + scripts/README.md (copy from assets/scripts_README.md). Populate with the user's existing scripts list (if any), or leave empty for subsequent agents to fill. Also copy check_handoff.py (from assets/check_handoff.py) — the handoff self-check script that agents run with python scripts/check_handoff.py each time they finish, verifying that §3/§4/STATUS have been updated. In AGENTS.md §5 ironclad rules, agree that "scripts don't scatter in the root directory."
9. Create STATUS.md (copy from assets/STATUS.md) — an empty template; the first agent fills it in with an incremental handoff (what this agent did, which files were modified, what pitfalls were encountered).
10. Write the user's environment and constraints into §Ironclad Rules and §Path Conventions.
11. After completion, tell the user: which files were generated, which "defaults" need confirmation, and which 【TODO】 items need filling in.

Mode B: Diagnose an Existing Project

B1: Fix a Messy Project (Zero Documentation or Chaotic Docs)

The user has an existing project but collaboration is chaotic — agents repeatedly ask the same questions, overwrite each other, or can't find status. First, read the existing README / any docs / directory structure. Compare against §File Skeleton and §AGENTS.md Sections, check what's missing, and provide a full remediation list (missing thin pointers? missing entry point? task cards not self-contained? missing source.txt? no handoff conventions?). After user confirmation, fill in the gaps. Read first, then modify; never overwrite existing files without review.

B2: Enhance a Good Project (Good Docs Already, Just Missing Thin Pointers)

The user already has solid project documentation (e.g., AI_COLLABORATION_PLAN.md / README.md / detailed wiki), but AI tools won't automatically read it (Codex/Claude default to AGENTS.md and won't proactively discover custom filenames). Just add a single AGENTS.md thin pointer (3 lines) pointing to the existing documentation; then add tool-specific thin pointer files (CLAUDE.md, etc.) for each tool the user selected. Do not modify any existing documentation. Criterion: After adding, a new agent enters → reads AGENTS.md → jumps to existing docs → gets full context, without the user needing to say "first read file X."

File Skeleton (After Generation)

<project root>/
├── AGENTS.md                          ← Sole authoritative entry point (top 3-line TL;DR + 7 sections, all tools read by default)
├── STATUS.md                          ← Incremental handoff (what this agent did, which files were modified, what pitfalls were encountered; written at end of session)
├── CLAUDE.md                          ← Thin pointer → "Refer to AGENTS.md"
├── GEMINI.md                          ← Thin pointer (same, optional)
├── .cursorrules                       ← Thin pointer (for Cursor, optional)
├── .github/copilot-instructions.md    ← Thin pointer (for Copilot, optional)
├── docs/
│   ├── task_plan_<topic>.md           ← Self-contained task card (includes "pre-delivery checklist" + optional recommended model)
│   ├── task_card_README.md            ← Task card directory index (dependency chain + status table, optional)
│   ├── delegation_task_template.md    ← Standard wording for delegating tasks to an AI agent (copy and fill, optional)
│   ├── decision_records/              ← Key technical decisions (optional, see advanced.md)
│   └── glossary.md                    ← Project terminology (optional)
├── <dataset_name>/                    ← One directory per dataset
│   ├── source.txt                     ← DOI/URL/date/calibration/units
│   └── ...
├── scripts/                           ← Code organization (recommended: keep scripts out of root)
│   ├── README.md                      ← One-line description per script: what it does/input/output/author
│   └── check_handoff.py               ← Handoff self-check script (run to verify §3/§4/STATUS have been updated)
└── progress_log.md                    ← Timestamped change log (optional)

AGENTS.md Sections (Order = Priority)

Fill according to assets/AGENTS.md template. The top must have a TL;DR block (3 lines: current phase / next step / blockers) so a new agent can glance and understand status. Below are 8 sections (template numbers 1–7, with path conventions numbered separately as §5.5 because it's too important to lump with ironclad rules):

0. TL;DR (Quick Read on Entry) — 3 lines: current phase, next step, blockers. Updated each handoff. A new agent doesn't need to read the whole document to know what's happening.
1. One-Sentence North Star — What this project is really about, for whom, and its tone (voice, publication/delivery goals, which mainline not to derail).
2. Current Story/Methods — Latest agreed direction + core methods + what changed recently and why.
3. Where We Are Now — Updated each handoff, 1–5 timestamped cumulative snapshots. This is the most crucial handoff point. Incremental details go into STATUS.md; this section only holds cumulative status.
4. Task Board — [ ]/[x] + who is responsible + dependencies (T1→T2, which can be parallel) + known risks.
5. Ironclad Rules / Conventions — Violations cause rework: environment calls, plotting/data rules, naming, calibration, handoff conventions. Includes: "New agents (including sub-agents) must read AGENTS.md completely before starting work." 5.5. Path Conventions — Where large files go, where small outputs return (to prevent multi-agent collisions, prevent cloud sync explosions). A separate section, don't bury it in Ironclad Rules.
6. Deep-Read Pointers — Which document holds details (task details, decision records, glossary, task card index).
7. Environment / Tools — How to call complete tool paths, env locks.

STATUS.md vs AGENTS.md §3 Division (Prevent Overlap): STATUS.md records incremental changes (what this agent did this round, which files were modified, what pitfalls were encountered); AGENTS.md §3 records cumulative snapshots (overall current progress, 1–5 items). They don't overlap — STATUS.md is "changes since last time," §3 is "where are we overall now."

Decision Registry (Strongly Recommended, Not Just Advanced): Consolidate binding decisions into a bounded, grep-able table — one decision per row: ID | Decision | Value/Calibration | Rationale | Date | Evidence Link | Supersedes. Place it below §6 in AGENTS.md, or near §3. It differs from free-form ADRs scattered in long STATUS narratives: bounded (one decision per row, always readable), searchable (grep a keyword to instantly hit the authoritative row), traceable (supersedes chains). This is a key layer against "decisions buried in long logs, or quietly overwritten by a lagging script." Template in references/advanced.md §1.

Hard Requirements for Cross-Tool Continuity (7 Rules)

1. Pure Markdown + Relative Paths + Standard Filenames — No tool-specific syntax, no hardcoded absolute paths.
2. Data Must Have source.txt (DOI/URL/download date/calibration/units/known issues) — Any person or agent can trace the origin.
3. Handoff Conventions Written into Ironclad Rules — Every agent must update §Where We Are Now + §Task Board + write/update STATUS.md (incremental handoff: what this agent did this round, which files were modified, what pitfalls were encountered; do not repeat §3's full snapshot) before exiting. Run python scripts/check_handoff.py at handoff time — it verifies §3 date freshness, TL;DR is filled, STATUS.md is not a template, STATUS date ≥ §3 date, thin pointers exist; plus two advisories (whether decision registry exists, whether multi-script calibration constants have drifted). Handoff is only合格 if all checks pass.
4. Path Discipline — "Large files go to the working drive, small outputs return to the repo" / "copy, don't cut; don't touch paths others are using."
5. First Thing for a New Agent (Including Sub-Agents) — Read AGENTS.md (including STATUS.md) before acting; don't rely on conversation history or guess from memory. STATUS.md will grow and no one will read all of it — so any binding decisions (calibration/exclusion lists/selected parameters) must be promoted to AGENTS.md §3 or the decision registry layer — a bounded, must-read position; don't leave them only in STATUS's long narrative. Before data extraction/modeling/reproduction, check this layer first; don't trust hardcoded values in a script.
6. Single Source for Key Numbers and Calibration Parameters, Prevent Drift — Key numbers (means/percentages/areas, etc.) are only written once in STATUS.md or AGENTS.md §3; elsewhere, reference, don't restate. Calibration parameters/sample sets/exclusion lists (which points are used, which are excluded, what threshold) are the same: extract into a single config (config/parameters.yaml or one authoritative table); all scripts read from it; hardcoding in multiple scripts is strictly forbidden — two scripts encoding the same set differently is the most insidious handoff accident source (self-checks won't catch it, format checks won't catch it either). Before handoff, verify consistency across all documents and scripts; if the same number differs by more than 1%, or the same set has inconsistent members, treat it as a bug and align before handing off.
7. Retire and Quarantine Bad Outputs and Superseded Scripts Together — When an agent's output is wrong (data/figure/number), immediately: ① rename the directory with a _DEPRECATED suffix or move into a _archived/ subdirectory; ② in AGENTS.md §5 Ironclad Rules, note at the top with red text > ⚠️ 【Deprecated】<path> (don't put it in §3 — §3 is cumulative snapshot; bad output markings should go in the same section as ironclad rules and conventions); ③ update §4 task board status to [x] + note "deprecated"; ④ update STATUS.md to reflect the deprecation; ⑤ old scripts/methods superseded by a decision are also retired — add a comment at the top of the script: # _DEPRECATED → see <authoritative script/decision>, so the next agent doesn't get lured into using it as a live calibration. Never rely on memory alone saying "don't use that" — a downstream agent silently reusing a bad output, or copying a calibration from a lagging script, is more fatal than producing nothing.

💡 A Real Handoff Lesson (These 3 Rules Came From This): An agent needed to re-fit a curve and copied a sample set from a lagging script — the script still retained bad points that should have been excluded, and the "exclude this point" decision was buried 600 lines deep in STATUS, with two scripts encoding it in opposite ways. The result: that point dragged R² from 0.5 down to 0.27, and the external report was overturned. In hindsight, three things could have stopped it: the decision wasn't promoted to a bounded must-read layer (rule 5), the calibration set was hardcoded in multiple scripts instead of a single config (rule 6), and the superseded old script wasn't marked as retired (rule 7). Trusting a lagging script over a decision record is the common root cause of such accidents.

Core Workflow (Complete Agent Handoff Cycle)

A typical multi-agent handoff lifecycle contains 5 explicit steps. Skipping step ③ (Independent Review) is the root cause of most pipeline contamination.

① Delegate → ② Execute + Self-Check → ③ Independent Review → ④ Accept & Archive → ⑤ Handoff & Record

Step Details

① Delegate (Controller → Executing Agent) Use standard wording (see template below or assets/delegation_task_template.md): specify what to read, what to do, what not to touch, where to output, and where to log doubts.

② Execute + Self-Check (Executing Agent) Perform the task, then run through the DoD (acceptance checklist): verify output completeness, correct format, no errors.

③ Independent Review (Controller or Another Agent Spot-Checks Key Numbers) Don't trust self-checks — the executing agent's self-check may pass while the output is still wrong (this has been proven insufficient repeatedly).

• The controller or a third agent spot-checks key numbers: conservation (input sum ≈ output sum?), bounds (any out-of-range / unclipped values?), counts (row count / pixel count as expected?), magnitude (units off by 10³?), consistency (same number across documents consistent?).
• Pass → proceed to step ④; fail → return to the executing agent for repair, and record an ADR.
• Criterion: "Independent review passed" is the gate to the next step, not an option.

④ Accept & Archive Confirmed-correct outputs are formally placed; update source.txt (if new data) and scripts/README.md (if new script).

⑤ Handoff & Record Update AGENTS.md §3 Status + §4 Task Board + write STATUS.md. Ensure the next agent can continue using only the Markdown in the repo.

💡 For short pipelines (1–2 agents, simple outputs), step ③ can be skipped; for outputs affecting paper conclusions or downstream pipelines, all 5 steps are mandatory.

Two Layers of Continuity (Both Required)

• Hard Continuity (Primary Dependency): Markdown in the repo, tool-agnostic, readable by any agent/person. This is the source of truth.
• Soft Continuity (Enhancement): Memory layers (Cursor memory / Claude memory) speed up retrieval, but core conclusions must not live only in memory — they must land in Markdown.

Criterion: Delete all memory layers; the next agent should be able to continue using only the Markdown in the repo → compliant.

Standard Delegation Prompt for AI Agents

When delegating to a new agent each time, start with a consistent format — far more effective than free-form. Follow assets/delegation_task_template.md:

Please first read AGENTS.md (including STATUS.md to understand current status). Do not modify raw data () or existing core code (). This task only handles phase X. If you find doubts or new issues, record them in ; do not fix them directly. Output to . Known pitfalls for this task: [list known risk points] Pre-delivery self-check: [conservation/bounds/counts/magnitude…, check each item]

The core value of this template: when a new agent cold-starts, it immediately knows what to read, what not to touch, and where to report problems. The "known pitfalls" and "self-check" columns are battle-tested critical increments — guiding the agent to self-intercept common error types before reporting completion, significantly reducing defect rates.

For critical tasks affecting paper conclusions or downstream pipelines, append an Arrange independent review after delivery instruction at the end of the prompt (advanced example in the template's final section).

Delegation Prompt Travels with the Card (Recommended): Don't make the user fill in this wording each time — each task card has a built-in 📋 Delegation Prompt (Copy & Use) block (see assets/task_plan_template.md T1 end). When building the card, fill in the target, boundaries, inputs/outputs, known pitfalls, self-checks, and handoff instructions. When the user wants to delegate, they can directly copy that block and paste it to any agent (cross-tool, cross-skill), no need to write from scratch. The delegation_task_template.md is only a reference for field meanings.

Advanced Sections (Enable as Needed, See references/advanced.md)

Beyond the core 7 sections, these become useful as a project grows. Don't pile them all in from the start:

• Decision Records (ADRs) — Record "why this method was abandoned," preventing the next agent from re-exploring the same dead ends and re-questioning settled decisions.
• Glossary — Project-specific terms/abbreviations; new agents don't have to guess.
• Progress Log — Timestamped change log, more granular than §Where We Are Now.
• Concrete DoD — Write DoD as executable commands, not just "done is done."
• Standard Handoff Summary — Status / Next Steps / Unresolved Risks / Key File Paths.
• Naming Conventions + Idempotency — Output files include _v1/date/coordinate system; re-runnable scripts are idempotent (cache skip).
• Environment Lock — Pin conda env with environment.yml, preventing drift when rebuilding on a different machine.
• Data Snapshots / Immutable Inputs — Raw data is read-only with a hash; all modifications happen on copies.
• Filled AGENTS.md Example — references/example_filled_AGENTS.md, a complete example (fictional project). It's much more intuitive to fill in from a filled example than from an empty template.

Custom Reminders

• This skeleton comes from real research projects (multi-agent, multi-dataset, long pipelines, cloud-synced). Tailor after copying: for pure front-end projects, you can cut the "working drive" part of §Path Conventions; for single-agent small script projects, simplify §Task Board.
• Template placeholders use 【TODO】 uniformly; delete them after filling.
• Thin pointer files all have the same content (see assets/CLAUDE.md); don't write different rules in each — that breaks the "single source of truth."
• Don't overwrite the user's existing AGENTS.md; for Mode B diagnosis, read first, then modify, making incremental fixes.