multi-agent-repo
Skill2 starsChanged 4 months agoMITView on GitHub
Use when auditing or setting up a repository for multi-agent development across Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, and OpenCode. Triggers: multi-agent repo, audit agent setup, AGENTS.md gaps, make this repo work with Claude and Cursor, add Codex, Gemini CLI or OpenCode support, generate cursor rules from AGENTS.md, capability registry, agent drift, canonical AGENTS.md, multi-agent-repo review, plan or dev.
- Commits and pushes
1 other project uses a version of this.
Adopted by
Most recently taken up by
- gwendall/skillstheir own version, first seen Nov 16, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- gwendall/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository46 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .cursor/rules/commit-conventions.mdcCursor rule
- .cursor/rules/cross-platform-handoff.mdcCursor rule
- .cursor/rules/dev-files-workspace.mdcCursor rule
- .cursor/rules/documentation-standards.mdcCursor rule
- .cursor/rules/gh-cli-preference.mdcCursor rule
- .cursor/rules/github-repository-policy.mdcCursor rule
- .cursor/rules/git-worktree-agent-workflow.mdcCursor rule
- .cursor/rules/hooks-guide.mdcCursor rule
- .cursor/rules/plugin-structure.mdcCursor rule
- .cursor/rules/plugin-version-bump.mdcCursor rule
- .cursor/rules/skill-frontmatter.mdcCursor rule
- .cursor/rules/skill-quality-standards.mdcCursor rule
- .cursor/rules/skills-guide.mdcCursor rule
- .cursor/rules/user-facing-script-standards.mdcCursor rule
- run-tamirs-superpowersSkill
- field-notebook-uiSkill
- diagnose-refusalSkill
- targeted-debugSkill
- decisionSkill
- deliver-devSkill
- diagnose-objectiveSkill
- orchestrate-devSkill
- plan-devSkill
- pr-devSkill
- start-devSkill
- switch-devSkill
- worker-devSkill
- changelog-reviewSkill
- dark-terminal-docSkill
- docs-reviewSkill
- platform-syncSkill
- mcp-builderSkill
- mcp-paginationSkill
- cleanupSkill
- github-policySkill
- repo-scaffoldSkill
- repo-standardsSkill
- capture-configSkill
- find-skillSkill
- notify-setupSkill
- retroSkill
- session-reportSkill
- skill-creatorSkill
- usage-captureSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 5 are distinctive, and 13 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 77
Run inventory + gap scoring before any rubric walk (review) or plan grouping.
- Very specific: line 79
Write outputs only to paths in references/mode-contracts.md.
- Very specific: line 108
Read references/target-layouts.md — note expected layout for $REPO_TYPE.
- Very specific: line 109
Run inventory and score-inventory-gaps.sh (already captured above).
- Very specific: line 110
Start the report gap table from auto-scored $GAPS JSON.
- Very specific: line 113
Write $REVIEW_PATH using templates/review-report.md.tmpl.
- Distinctive: line 117
ALWAYS include these sections in order:
- Distinctive: line 132
Stop: Do not edit AGENTS.md, CLAUDE.md, or rules in review mode.
- Distinctive: line 142
If user did not pass a review doc path, run review mode first in the same turn.
- Very specific: line 143
Read the review report ($DOC_PATH, user path, or latest multi-agent-review-*.md under docs/agent-guidelines/).
- Very specific: line 158
Write $PLAN_PATH from templates/remediation-plan.md.tmpl.
- Distinctive: line 177
If no plan doc in arguments, run plan mode first.
- Very specific: line 178
Read plan doc ($DOC_PATH, user path, or $PLAN_PATH).
- Very specific: line 191
Follow references/platform-setup.md for live doc fetch, AGENTS.md, CLAUDE.md (@AGENTS.md), and 000-project.mdc.
- Very specific: line 195
Add scoped .mdc rules (globs for src/tests/db per stack)
- Very specific: line 196
Create docs/agent-guidelines/ stubs linked from AGENTS.md
- Very specific: line 205
Add CI step if .github/workflows/ exists (mirror AGENTS.md validation command)
- Very specific: line 222
Commit in logical chunks (feat(agents): …, chore(ci): …).
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
multi-agent-repo
Audit, plan, and implement canonical multi-agent repository setup: one AGENTS.md source of truth, thin adapters per tool, portable skills, and CI-enforced validation.
Why this skill exists
Teams running Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI, and OpenCode in parallel often maintain a diverging instruction file per tool. Policies drift, context bloats past Codex's 32 KiB limit, and agents ignore duplicated rules. Worse, "which target supports hooks?" gets answered differently in three documents. The fix is structural: one canonical body per rule, a thin generated adapter per target, and one capability registry — core/capabilities/platforms.json — that every other file derives from. make check-feature-equivalence fails the build when two views of the platform set disagree. This skill runs review → plan → dev so you know what's missing, what order to fix it, and can land the full setup via PR. For quick file generation without a prior audit, use dev mode directly.
Supporting files
| Path | When to read |
references/mode-contracts.md | Parse arguments; know stop conditions per mode |
references/target-layouts.md | Classify app vs claude-plugin vs hybrid |
references/audit-rubric.md | Full checklist for review mode |
references/gap-scoring.md | Auto vs manual rubric mapping |
references/platform-setup.md | Fetch docs + generate AGENTS.md and thin adapters (phases 0–1) |
references/platform-specs.md | Schema fallback when live doc fetch fails |
scripts/parse-mode-args.sh | Deterministic mode/target parsing |
scripts/inventory-agent-setup.sh | Re-export → ../_contract/scripts/ |
scripts/score-inventory-gaps.sh | Re-export → ../_contract/scripts/ |
scripts/check-agent-drift.sh | Re-export → ../_contract/scripts/ |
templates/*.md.tmpl | Report, plan, and PR body shapes |
Required execution flow
- Parse args with
parse-mode-args.sh— do not guess mode from free text alone. - Run inventory + gap scoring before any rubric walk (review) or plan grouping.
- Route to exactly one mode section; plan/dev may chain prior modes in the same turn.
- Write outputs only to paths in
references/mode-contracts.md.
Parse input
SKILL_DIR="$CLAUDE_SKILL_DIR"
PARSED="$(bash "$SKILL_DIR/scripts/parse-mode-args.sh" $ARGUMENTS)"
MODE="$(echo "$PARSED" | jq -r '.mode')"
TARGET_ROOT="$(echo "$PARSED" | jq -r '.target')"
DOC_PATH="$(echo "$PARSED" | jq -r '.doc_path // empty')"
CONSTRAINTS="$(echo "$PARSED" | jq -r '.constraints')"
DATE="$(date +%Y-%m-%d)"
INVENTORY="$(bash "$SKILL_DIR/scripts/inventory-agent-setup.sh" "$TARGET_ROOT")"
GAPS="$(bash "$SKILL_DIR/scripts/score-inventory-gaps.sh" <<<"$INVENTORY")"
REPO_TYPE="$(echo "$INVENTORY" | jq -r '.repo_type')"
REVIEW_PATH="$TARGET_ROOT/docs/agent-guidelines/multi-agent-review-$DATE.md"
PLAN_PATH="$TARGET_ROOT/docs/agent-guidelines/multi-agent-plan-$DATE.md"Route to the matching section below. Do not skip review data in plan/dev when no prior doc path is given.
Mode: review (read-only)
Goal: Gap report vs canonical multi-agent layout. No repo edits except docs/agent-guidelines/ + report file.
Steps
- Read
references/target-layouts.md— note expected layout for$REPO_TYPE. - Run inventory and
score-inventory-gaps.sh(already captured above). Readreferences/gap-scoring.mdfor auto vs manual split. - Start the report gap table from auto-scored
$GAPSJSON. - Walk manual sections in
references/audit-rubric.md(content quality, duplication, command accuracy). Merge new findings; dedupe by rubric ID. mkdir -p "$TARGET_ROOT/docs/agent-guidelines"- Write
$REVIEW_PATHusingtemplates/review-report.md.tmpl.
Report structure
ALWAYS include these sections in order:
# Multi-agent review — [repo name]
## Executive summary
## Repo classification
## Gap summary (P1 / P2 / P3 counts)
## Findings table
| ID | Severity | Evidence | Remediation | Phase |
## Recommended next step
## Inventory appendix (JSON)- Print executive summary: repo type, P1/P2/P3 counts, path to report.
Stop. Do not edit AGENTS.md, CLAUDE.md, or rules in review mode.
Mode: plan
Goal: Phased remediation plan from review findings.
Steps
- If user did not pass a review doc path, run review mode first in the same turn.
- Read the review report (
$DOC_PATH, user path, or latestmulti-agent-review-*.mdunderdocs/agent-guidelines/). - Group P1/P2 gaps into phases:
| Phase | Focus |
| 0 | Canonical AGENTS.md |
| 1 | Thin adapters: CLAUDE.md (@AGENTS.md), .cursor/rules/000-project.mdc |
| 2 | Scoped .mdc rules + docs/agent-guidelines/{testing,security,style}.md |
| 3 | Portable skills (.agents/skills/ or plugin skills/ per repo type) |
| 4 | Copy check scripts + makefile-agent-targets.mk.tmpl into Makefile; wire agent:check in CI |
| 5 | Feature equivalence — manifests, bridges, MCP, platform-equivalence.md (see _contract/feature-equivalence.json) |
| 5b | Platform targets — Skill("platform-sync") read-only; update platform-targets.json + README Row 3 badges |
| 6 | Run validation scripts; re-inventory; P1 must be 0 |
- For each phase list: actions, files, implementation notes (
references/platform-setup.mdfor phases 0–1), validation command, risk. - Write
$PLAN_PATHfromtemplates/remediation-plan.md.tmpl. - Present plan summary to user.
Stop unless mode is dev.
Mode: dev
Goal: Implement plan on feature branch; open PR. Never merge.
Preconditions
- Git repo at
$TARGET_ROOT ghsigned in to the repository's host (gh repo viewsucceeds in$TARGET_ROOT; it resolves the host from the remote)- Warn if working tree dirty; do not discard user changes
Steps
- If no plan doc in arguments, run plan mode first.
- Read plan doc (
$DOC_PATH, user path, or$PLAN_PATH). - Create branch:
cd "$TARGET_ROOT"
BRANCH="feat/multi-agent-setup"
git checkout -b "$BRANCH" 2>/dev/null || git checkout -b "feat/multi-agent-setup-$(date +%s)"- Implement phases in order:
Phase 0–1 — platform files
Follow references/platform-setup.md for live doc fetch, AGENTS.md, CLAUDE.md (@AGENTS.md), and 000-project.mdc. Respect $CONSTRAINTS.
Phase 2–3 — local
- Add scoped
.mdcrules (globs for src/tests/db per stack) - Create
docs/agent-guidelines/stubs linked from AGENTS.md - For app repos: ensure
.agents/skills/or document bridge - For claude-plugin repos: keep
skills/perplugin.json— do not force.agents/skills/
Phase 4 — enforcement
- Copy or adapt
scripts/check-agent-drift.sh,check-feature-equivalence.sh, andcheck-platform-targets.shfrom_contract/scripts/into targetscripts/ - For Node repos: copy
templates/check-no-agent-drift.mjs.tmpl→scripts/check-no-agent-drift.mjs - Wire
agent:rulesor extendvalidatein Makefile /package.jsonscripts - Add CI step if
.github/workflows/exists (mirror AGENTS.md validation command)
Phase 5 — feature equivalence + platform targets
- Scaffold missing manifests,
.agents/skills/bridges,platform-equivalence.md, andplatform-targets.jsonper_contract/feature-equivalence.json - Optional:
Skill("platform-sync")read-only for latest platform versions
Phase 6 — validate
make agent-polish-gate
make platform-targets-sync (then update JSON/badges) and make platform-targets-assert
bash scripts/check-agent-drift.sh
# plus stack-specific command from AGENTS.md
bash "$SKILL_DIR/scripts/inventory-agent-setup.sh" "$TARGET_ROOT"- Commit in logical chunks (
feat(agents): …,chore(ci): …). - Push and open PR:
git push -u origin HEAD
gh pr create --title "feat(agents): multi-agent repo setup" --body "$(cat <<'EOF'
<fill from templates/pr-body.md.tmpl>
EOF
)"- Print PR URL and re-inventory summary.
Stop at PR. User or pr-dev merges after approval.
Agent execution rule
Agents run Make targets — never ask the user to run bash scripts.
| When | Agent runs |
| After wiring scripts/Makefile | make agent:check |
| Before polish PR (multi-platform) | make agent-polish-gate (syncs targets, asserts current, full check) |
| After changing repo skills (tamirs-superpowers) | make platform-targets-sync then update platform-targets.json + README Row 3 |
Users invoke /repo-standards polish or /multi-agent-repo dev — not manual make commands.
Anti-patterns (do not do these)
| Anti-pattern | Why it fails |
| Editing AGENTS.md in review mode | Review is read-only except the report path |
| Skipping review before dev on unfamiliar repos | Misses P1 gaps; run review or plan first unless user explicitly wants quick dev |
Duplicating AGENTS.md into CLAUDE.md or .mdc | Drift on next policy change; violates thin-adapter model |
More than 2 alwaysApply: true Cursor rules | Context bloat; Codex/Cursor ignore overflow |
Skipping score-inventory-gaps.sh | Manual rubric walk alone misses deterministic P1s inconsistently |
| Merging the PR from this skill | User or pr-dev owns merge after review |
Hard rules
- AGENTS.md is canonical — CLAUDE.md and
.mdcfiles point to it; never duplicate full policy text. - ≤ 2 Cursor rules with
alwaysApply: true. - AGENTS.md ≤ 32 KiB — no Claude-only syntax in AGENTS.md.
- Plugin repos — respect existing
skills/layout; do not migrate to.agents/skills/without explicit user request. - Windows — prefer
@AGENTS.mdin CLAUDE.md over symlinks. - Never force-push or push to branches other than the feature branch.
- Never merge the PR from this skill.
Relationship to other skills
| Skill | When to use instead |
repo-standards | Full Tamir repo standards (README, docs, CI, multi-agent) — uses shared _contract |
repo-scaffold | Greenfield repos — output must pass app-gold contract |
plan-dev | Break arbitrary features into GitHub issues |
start-dev | Implement a feature issue, not agent infrastructure |
pr-dev | Drive the PR to merge after dev mode opens it |
Error handling
| Situation | Action |
| Target not a directory | Ask for valid path; stop |
| Not a git repo in dev mode | Stop; suggest review/plan only |
gh not signed in | Stop; ask the user to sign in to the GitHub CLI |
| Platform doc fetch partial failure | Log platform; use references/platform-specs.md fallback; continue |
| Inventory shows P1 after dev | List remaining gaps; do not claim complete |
Example invocations
/multi-agent-repo
/multi-agent-repo review ../other-repo
/multi-agent-repo plan
/multi-agent-repo plan docs/agent-guidelines/multi-agent-review-2026-06-23.md
/multi-agent-repo dev
/multi-agent-repo dev . -- prioritize CI and drift checker onlyDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

