polis-protocol
Coordinate multi-vendor AI agents as a self-improving team — a learning router assigns work by track record and citizens can amend the protocol's own rules.
- License 许可
- MIT
- 最近更新
- 2026-08-07
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- polis-protocol
- risk
- critical
- tags
- [ "multi-agent", "coordination", "routing", "orchestration", "governance", "vendor-agnostic" ]
- tools
- [ "claude", "cursor", "gemini", "codex", "antigravity" ]
- author
- yehudalevy-collab
- plugin
- { "targets": { "codex": "blocked", "claude": "blocked" } }
- source
- community
- license
- MIT
- category
- orchestration
- date_added
- 2026-06-02
- description
- Coordinate multi-vendor AI agents as a self-improving team — a learning router assigns work by track record and citizens can amend the protocol's own rules.
- source_repo
- yehudalevy-collab/polis-protocol
- source_type
- community
- license_source
- https://github.com/yehudalevy-collab/polis-protocol/blob/main/LICENSE
03 SKILL.md 正文
Polis Protocol — a team of agents that develops
Overview
Most agent coordination is a passive board: claim a task, do it, mark it done. It records, but it never gets smarter, and its rules are frozen. Polis Protocol is the active alternative — a folder of markdown where each agent is a "citizen" with a capability card, work is routed by a learning bandit to whoever has the best track record on the task's tags, settled work files lessons that update the routing, and citizens can propose and vote on amendments to the protocol itself. It is vendor-agnostic: Antigravity, Claude, Codex, and Gemini agents can all share one _polis/.
In Antigravity specifically, this turns Manager View's fixed pipeline into a team that learns who is actually best at each kind of work, instead of running the same roles in the same order every time.
When to Use This Skill
- Use when 2+ agents (especially across vendors) work on one project and "who should do this" is a real question.
- Use when you want the team to measurably improve over time — routing that adapts from outcomes, not static role labels.
- Use when you need a durable, git-auditable record of who did what, what was learned, and which rules changed.
- Use when Antigravity's default orchestration is too rigid and you want routing + governance on top of it.
How It Works
Step 1: Found a polis
Use a reviewed checkout by default so the scaffolder code is pinned before it writes into the project:
git clone https://github.com/yehudalevy-collab/polis-protocol.git
cd polis-protocol
git checkout <reviewed-commit-sha>
python3 scripts/init_polis.py \
--project-root . \
--agent-id gemini-antigravity-yourproject \
--vendor google --model gemini-3 --tool antigravity
If you prefer the published PyPI package, install an exact version after reviewing that release, for example pipx install polis-protocol==<reviewed-version>. Do not invoke the package through an unpinned uvx or "latest" workflow for automated setup.
This writes _polis/ plus the skill into .agents/skills/ (the path Antigravity reads), and bridge pointers (GEMINI.md, AGENTS.md) that point every tool at _polis/CONSTITUTION.md. Tip: add --dry-run to preview every file before anything is written; init never overwrites existing files, and polis init --repair restores missing ones.
Step 2: Register citizens and open contracts
Each agent publishes a capability card under _polis/citizens/. Work is opened as a contract with required_tags, not assigned to a fixed role.
Step 3: Route by track record
polis route --polis-root _polis \
--contract _polis/contracts/open/your-task.md --explain
The router prints a score breakdown (history / self-rating / cost / availability / applied lessons) and recommends the citizen with the strongest record on the task's tags. Agents can also reserve files (polis reserve src/auth --as <citizen>) so two agents never edit the same path at once — overlapping claims are rejected with the holder named.
Step 4: Settle, learn, and amend
polis contract settle <contract-id> --quality 5
polis reconcile --polis-root _polis
A settled contract files a lesson; accepted lessons carry a bounded routing_effect the router reads — and names in --explain — on the next similar task. Failures become guardrails (polis guardrail add …) that future contracts on those tags inherit as must-pass acceptance criteria. When a rule stops working, a citizen proposes an amendment and the others vote. Reproduce the learning claim yourself: polis bench --mode learning.
Examples
Example 1: See the team learn (no install, 30 seconds)
git clone https://github.com/yehudalevy-collab/polis-protocol.git
cd polis-protocol
git checkout <reviewed-commit-sha>
bash scripts/demo.sh
The router recommends Gemini for a Spanish-translation contract — because settled work taught it she has the best record on that tag, not because anyone reassigned it.
Example 2: Explain any routing decision
python3 scripts/route_contract.py --polis-root examples/research-team/_polis \
--contract examples/research-team/_polis/contracts/open/parent-newsletter-issue-3.md --explain
Notes
- No server, no runtime, no database — the whole protocol is markdown plus two small Python scripts.
- Vendor-agnostic by design; a Claude or Codex agent can join the same polis an Antigravity agent created.
- Full Antigravity integration guide: https://github.com/yehudalevy-collab/polis-protocol/blob/main/docs/antigravity.md
Limitations
- Routing quality depends on accurate citizen capability cards and enough settled work history to learn from.
- The protocol coordinates agent work but does not replace review, tests, or explicit maintainer approval.
- Multi-agent voting and amendments can add process overhead for small, single-owner tasks.
- The upstream scripts are external code; pin to a reviewed commit and run
--dry-runbefore allowing writes to a project.
04 同仓库更多 Skills
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
stop-slop
Remove AI writing patterns from prose. Use when drafting, editing, or reviewing text to eliminate predictable AI tells and produce more human-like writing.
ogilvy-copywriting
Apply David Ogilvy's advertising principles when writing or reviewing copy, headlines, product descriptions, landing pages, ads, emails, or any persuasive text. Use when the goal is copy that sells, not copy that wins awards. Covers positioning, headlines, promises, brand voice, long-form copy, and visual logic. Source: How to Create Advertising That Sells (1972) + Ogilvy on Advertising.
frontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.