[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7DP10VVAHVNSCBC2N4GDT84":3,"skill-same:01M7DP10VVAHVNSCBC2N4GDT84":51},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":30,"commitSha":31,"skillDirectory":32,"forksCount":33,"repositoryHtmlUrl":34,"repositoryHomepageUrl":6,"ownerHtmlUrl":35,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":36,"install":37,"resources":50},"01M7DP10VVAHVNSCBC2N4GDT84","polis-protocol-a-self-optimizing-city-of-agents",null,"Polis Protocol: A Self-Optimizing City of Agents","Hazek-dc\u002FPresensiGuru_FaceNet_EMAR","Hazek-dc","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F75208960?v=4","01M7DEQV5B4YGS86A81DYH81DR","Hazek","01M7DEQV5XP4TM0C6NTHXCXCHR",1,"MIT","https:\u002F\u002Fgithub.com\u002FHazek-dc\u002FPresensiGuru_FaceNet_EMAR\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fpolis-protocol-a-self-optimizing-city-of-agents\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: polis-protocol-a-self-optimizing-city-of-agents\ndescription: \"Polis Protocol: A Self-Optimizing City of Agents\"\nrisk: unknown\nsource: https:\u002F\u002Fgithub.com\u002Fyehudalevy-collab\u002Fpolis-protocol\u002Ftree\u002Fmain\u002F\nsource_repo: yehudalevy-collab\u002Fpolis-protocol\nsource_type: community\ndate_added: 2026-07-01\nlicense: MIT\nlicense_source: https:\u002F\u002Fgithub.com\u002Fyehudalevy-collab\u002Fpolis-protocol\u002Fblob\u002Fmain\u002FLICENSE\n---\n\n# Polis Protocol: A Self-Optimizing City of Agents\n## When to Use\n\nUse this skill when you need polis Protocol: A Self-Optimizing City of Agents.\n\n\nA protocol that lets AI agents from different vendors collaborate on a long-running project, route work to whoever is best at it, and get measurably better over time. Everything lives in a folder of markdown files, so any tool that reads and writes text can participate — no central server, no required runtime.\n\n## The core idea\n\nTreat the project as a small *polis*: citizens (the agents) that share a constitution (the protocol), publish public identities (capability cards), enter contracts (tasks), and leave a public record of how things went (lessons). Three institutions plus a self-change mechanism:\n\n1. **The Register** — identity and capability discovery (capability cards).\n2. **The Contract** — structured tasks with learned routing.\n3. **The Chronicle** — lessons that compound and feed back into routing.\n4. **The Amendment** — citizens change the rules when reality demands it.\n\nThis buys what shared-vault setups don't: cross-vendor optimization (work goes to whoever is best at it), self-development (routing improves with use), and constitutional evolution (the protocol updates itself from friction). For pure note-passing without routing, prefer agent-vault.\n\n## When this skill is active\n\nAny multi-agent scenario where \"who should do this\" is a real question: founding or joining a polis; writing, claiming, or settling a contract; running a chavruta review; proposing or ratifying an amendment; or diagnosing a stalled contract, sync conflict, router pathology, or stuck quorum. Upgrading from agent-vault → `references\u002Ftroubleshooting.md` (\"Migrating from agent-vault\").\n\n## Structure of a polis\n\nA polis lives in a `_polis\u002F` folder at the project root; everything outside it is project content the protocol never touches.\n\n- `CONSTITUTION.md` — canonical tool-agnostic protocol · `index.md` — current state · `README.md` — human explainer\n- `chronicle.md` — append-only event log\n- `citizens\u002F\u003Cagent-id>\u002F` — `capability_card.yml`, `status.md`, `inbox.md`, `journal.md`\n- `contracts\u002Fopen\u002F\u003Cid>.md` · `contracts\u002Fsettled\u002F\u003Cid>.md` · `contracts\u002Frouting_stats.yml` (learned policy, updated on settle)\n- `lessons\u002F\u003Ccapability-tag>\u002F\u003Cid>.md` · `reviews\u002F\u003CYYYY-MM-DD-HHMM>-\u003Ccontract>.md` · `amendments\u002Fproposed|ratified\u002F`\n- Project root also gets `CLAUDE.md` \u002F `AGENTS.md` \u002F `GEMINI.md` bridge pointers and `.agents\u002Fskills\u002Fpolis-protocol\u002FSKILL.md` (Codex\u002FAntigravity copy), all pointing at `CONSTITUTION.md`.\n\nCitizens link to project files with wikilinks (`[[path\u002Fto\u002Fnote]]`). The `_polis\u002F` folder is the only thing the protocol owns.\n\n## The first thing to do every session\n\nBefore touching any project file, run the entry routine, in order:\n\n1. **Polis exists?** Look for `_polis\u002FCONSTITUTION.md`. If absent, scaffold it (see \"Founding a polis\").\n2. **You are registered?** Look for `_polis\u002Fcitizens\u002F\u003Cself>\u002Fcapability_card.yml`. If absent, register (see \"Registering a citizen\").\n3. **Read `_polis\u002FCONSTITUTION.md`** once per session — it is the canonical protocol for this polis; this SKILL.md is the seed it grew from.\n4. **Read `_polis\u002Findex.md`** — where things stand (a two-minute read).\n5. **Read your inbox** — `_polis\u002Fcitizens\u002F\u003Cself>\u002Finbox.md`.\n6. **Scan the tail of `chronicle.md`** backward until you reach the `last_seen_event:` in your `status.md`. That is your catch-up.\n7. **Read your open contracts** — anything in `_polis\u002Fcontracts\u002Fopen\u002F` with `owner: \u003Cself>`.\n8. **Update `last_seen_event` and `last_active` in your `status.md`.**\n9. **Report back to the user** — state of the project, what's in flight, what needs their input, a concrete first move.\n\nIf `chronicle.md` has grown large, the rollover policy (`references\u002Ftroubleshooting.md`) keeps it bounded.\n\n## The chronicle: recording what you did\n\nAfter each meaningful action, append exactly one line to `_polis\u002Fchronicle.md`. The format is rigid because the router and other citizens parse it:\n\n```\n- YYYY-MM-DD HH:MM | \u003Cagent-id> | \u003Cverb-phrase> | [[\u003Cwikilink>]] | \u003Cone-line note or - >\n- 2026-05-14 09:15 | codex-frontend-pesaj | settled contract | [[contracts\u002Fsettled\u002Fauth-refactor]] | tests passing, lesson filed\n```\n\nA meaningful action is anything another citizen needs to know about (contract opened\u002Fsettled, handoff, blocker, review requested, amendment proposed, index-keeper change). Internal reasoning and minor edits stay in your private `journal.md` and never reach the chronicle — protecting its signal-to-noise ratio is the single most important discipline.\n\nReserved verb phrases carry meaning scripts may filter on: `joined`\u002F`left polis`, `opened`\u002F`claimed`\u002F`settled`\u002F`abandoned contract`, `filed lesson`, `requested review`\u002F`signed off`\u002F`rejected review`, `proposed`\u002F`ratified`\u002F`rejected amendment`, `blocked on \u003Cthing>`\u002F`unblocked`, `assumed`\u002F`released index keeper`. Full semantics in `references\u002Fprotocol-spec.md`; otherwise use plain past-tense verbs.\n\n**Granularity — the most common failure is over-recording:** would another citizen waste time, make the wrong call, or duplicate work if this is *not* recorded? If yes, record it; if no, don't. Calibration table in `references\u002Ftroubleshooting.md`.\n\n## The Register: capability cards\n\nEvery citizen publishes `_polis\u002Fcitizens\u002F\u003Cagent-id>\u002Fcapability_card.yml` — the machine-parseable answer to \"who can do what\":\n\n```yaml\nagent_id: claude-research-pesaj\nvendor: anthropic        # model: claude-opus-4-7\ncapability_tags:\n  long-context-reading: { self_rating: 5, evidence: \"150k token context\" }\n  spanish-translation:  { self_rating: 3, evidence: \"native-ish, not certified\" }\ncost_envelope: { relative: medium }   # low|medium|high   latency: typical\u002Fmax minutes\ncontent_hash: \"sha256:…\"   # tamper-evidence, not a cryptographic signature\n```\n\nSelf-ratings are starting points, not truth — actual performance in `routing_stats.yml` takes over within a few tasks per tag. Keep tags specific (`react-component-design`, not `frontend-code`), edit your own card freely as you learn, and treat `content_hash` as tamper-evidence (it shows a card changed since last stamped via `polis verify`, not *who* changed it). New agents write their own card without asking — the Register is open by design. Full schema: `references\u002Fprotocol-spec.md`.\n\n## The Contract: structured tasks with learned routing\n\nContracts have three sections written over the contract's life: **Intent** (goal, acceptance criteria, required capability tags, deadline, cost ceiling, stakes) at open; **Assignment** (owner, approach, effort) at claim; **Settlement** (outcome, what worked\u002Fbit, lesson reference, quality score) at close. Schema in `references\u002Fprotocol-spec.md`; templates in `references\u002Ftemplates.md`.\n\n**Routing** is a multi-armed bandit: for each required tag, score every citizen from self-rating (weighted heavily at cold-start), historical quality in `routing_stats.yml`, cost, and availability; usually route to the top score (exploit), occasionally to another (explore, default 15%) to keep the policy honest. Runs as `scripts\u002Froute_contract.py` or as a brief reasoning step — same recommendation either way. It is a recommendation, **not a command**: any citizen may override by claiming and noting why in the `Assignment` section; overrides are logged and feed the policy. Math and tuning: `references\u002Frouting.md`.\n\n**Settling** does three things together: write the `Settlement` section; create a lesson under `_polis\u002Flessons\u002F\u003Ctag>\u002F\u003Cid>.md` (one paragraph + tags); post a `settled contract` chronicle line. The router reads settled contracts and lessons to update `routing_stats.yml` — that update is what makes the team improve. Lessons (frontmatter: `lesson_id`, `filed_by`, `capability_tags`, `related_contracts`, `quality_impact`, then one paragraph) are pulled by new contracts in the same tag before routing, so both the router and the executing agent carry the team's accumulated wisdom. This is what turns amnesiac agents into a team with institutional memory.\n\n## Chavruta review for high-stakes contracts\n\nAny contract flagged `stakes: high` (deletes data, ships to production, makes an architectural call, or commits to an expensive-to-reverse direction) requires a second citizen — ideally **from a different vendor** — to critique the plan before execution. Flow: owner writes the `Assignment` \"Plan\" and posts `requested review` + an inbox note to a strong reviewer → reviewer writes `_polis\u002Freviews\u002F\u003Cts>-\u003Ccontract>.md` answering \"what's right \u002F what's missing \u002F sign off, request changes, or reject\" → on sign-off the owner executes; on changes, revise once and repeat; on reject, escalate or abandon. Same-vendor review is allowed but weaker — the structural difference between models is the whole value. Use sparingly; most contracts are low-stakes and skip it. Details: `references\u002Fprotocol-spec.md`.\n\n## The Amendment: a polis that updates itself\n\nWhen a citizen notices a recurring failure, an unclear rule, or a routing pathology, they propose an amendment. Flow: write `_polis\u002Famendments\u002Fproposed\u002F\u003Cid>.md` (problem + proposed constitution change + any new rule\u002Fformat) → post `proposed amendment` to the chronicle and a one-line pointer to every inbox → citizens respond in the file (`agree | disagree | abstain | request changes` + rationale) → on quorum (default: simple majority of citizens active in the last 14 days) move it to `ratified\u002F` and edit `_polis\u002FCONSTITUTION.md`, one chronicle line each. Rejected amendments stay in `proposed\u002F` with `status: rejected` so future citizens know what was tried. The constitution is always canonical for a given polis; this SKILL.md is the seed. When to amend vs. work around, quorum rules, examples: `references\u002Famendments.md`.\n\n`polis reflect` automates the *noticing*: it mines settled-contract history for recurring process pathologies (chronic misroutes, low-quality tags, stakes miscalibration) and drafts evidence-backed proposals into `amendments\u002Fproposed\u002F` (authored by `polis-reflector`, citing the contracts). It only proposes — citizens still vote and ratify. Run `polis reflect` to preview, `--apply` to file them.\n\n## Founding a polis\n\nIf `_polis\u002FCONSTITUTION.md` does not exist, found the polis. Three paths, in order of preference — use the first one available in your environment:\n\n1. **Online, latest (recommended).** `uvx` fetches the newest release from PyPI, so users stay current automatically:\n   ```\n   uvx polis-protocol init --project-root \u003Cpath> --agent-id \u003Cyour-agent-id> \\\n     --vendor \u003Canthropic|openai|google|other> --model \u003Cmodel-id> --project-name \"\u003Cname>\"\n   ```\n   (Equivalent: `pipx install polis-protocol` then `polis init …`.)\n\n2. **Offline — no network, no install.** This skill ships a self-contained initializer next to its `templates\u002F`. Run it with the same flags from the skill folder:\n   ```\n   python scripts\u002Finit_polis.py --project-root \u003Cpath> --agent-id \u003Cyour-agent-id> \\\n     --vendor \u003C…> --model \u003Cmodel-id> --project-name \"\u003Cname>\"\n   ```\n   It needs only Python 3 and the bundled `templates\u002F` — no `polis` package, no network. Use this whenever `uvx`\u002F`pipx` is unavailable (sandbox, offline, no PyPI) instead of hunting for a missing CLI.\n\n3. **By hand — no Python at all.** Copy the templates in `references\u002Ftemplates.md`. The minimum viable polis is `_polis\u002FCONSTITUTION.md` + your own `capability_card.yml` + an empty `chronicle.md` with a frontmatter block.\n\nAll three write the full `_polis\u002F` structure (constitution, founder's capability card, seed `chronicle.md`, empty `routing_stats.yml`, and the `CLAUDE.md`\u002F`AGENTS.md`\u002F`GEMINI.md` bridge pointers). All are idempotent and never overwrite existing files. `polis init --repair` (or re-running the script) restores missing managed files; `polis migrate --plan|--apply|--rollback` handles schema upgrades reversibly.\n\n## Registering a citizen into an existing polis\n\nWhen you arrive at a project that has `_polis\u002FCONSTITUTION.md` but no card for you, register yourself — do not wait for permission:\n\n1. Pick an agent ID (convention below).\n2. Create `_polis\u002Fcitizens\u002F\u003Cyour-id>\u002F`.\n3. Write `capability_card.yml` (schema in `references\u002Fprotocol-spec.md`).\n4. Create empty `status.md`, `inbox.md`, `journal.md` from the templates.\n5. Post a `joined polis` line in `chronicle.md` linking your card.\n6. Continue with the entry routine.\n\n**Agent ID convention:** `\u003Cvendor-or-tool>-\u003Crole>-\u003Cproject>`. The vendor prefix lets any citizen see at a glance which model produced a chronicle line. Good: `claude-research-pesaj`, `codex-frontend-pesaj`, `gemini-translator-pesaj`. Bad: `agent-7a3f` (opaque), `helper` (generic), `gemini-2026-05-14-1430` (timestamps aren't identity). Lowercase, hyphens only, 8–40 chars; once registered, never rename.\n\n## Working across vendors\n\nThe bridge pointers written at bootstrap let Claude, Codex, Gemini CLI, GPT-based tools, and anything that reads markdown share one polis (`AGENTS.md` also covers Jules, Aider, goose, opencode, Zed, Warp, VS Code, Devin). All point at `_polis\u002FCONSTITUTION.md`, so the protocol updates in one file. Cross-vendor routing is the payoff: the bandit sends a translation to whoever has the best `spanish-translation` track record, not whoever happens to be the current chat.\n\n## Failure modes and recovery\n\nFull recovery steps in `references\u002Ftroubleshooting.md`. A citizen goes silent → check `status.md`; past the stale threshold, transfer ownership. Two citizens claim one contract → first-write-wins on `owner:`, loser re-picks. Router keeps picking wrong → likely cold-start; override a few to seed, else amend the weights. A card edited by a non-owner → `content_hash` mismatch via `polis verify`; restore and log. Amendment stuck without quorum → lower the activity threshold or merge proposals (30-day auto-expire). Polis too large → roll `chronicle.md` over quarterly, archive settled contracts past 90 days; lessons never roll over.\n\n## References\n\n- `references\u002Fprotocol-spec.md` — full schema for every file + reserved-verb semantics; read to validate or parse a file.\n- `references\u002Ftemplates.md` — annotated copy-paste templates; read when founding by hand, registering, or filing.\n- `references\u002Frouting.md` — bandit math, scoring, cold-start, explore-rate tuning; read when the router picks weird.\n- `references\u002Famendments.md` — when to amend vs. work around, quorum rules, examples.\n- `references\u002Ftroubleshooting.md` — failure modes, the granularity calibration table, scaling, agent-vault migration.\n- `templates\u002FPOLIS_CONSTITUTION.md` — the canonical protocol written into each polis on bootstrap.\n\n## Limitations\n\n- Use this skill only when the task clearly matches its upstream source and local project context.\n- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.\n- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.\n","# Polis Protocol: A Self-Optimizing City of Agents\n## When to Use\n\nUse this skill when you need polis Protocol: A Self-Optimizing City of Agents.\n\n\nA protocol that lets AI agents from different vendors collaborate on a long-running project, route work to whoever is best at it, and get measurably better over time. Everything lives in a folder of markdown files, so any tool that reads and writes text can participate — no central server, no required runtime.\n\n## The core idea\n\nTreat the project as a small *polis*: citizens (the agents) that share a constitution (the protocol), publish public identities (capability cards), enter contracts (tasks), and leave a public record of how things went (lessons). Three institutions plus a self-change mechanism:\n\n1. **The Register** — identity and capability discovery (capability cards).\n2. **The Contract** — structured tasks with learned routing.\n3. **The Chronicle** — lessons that compound and feed back into routing.\n4. **The Amendment** — citizens change the rules when reality demands it.\n\nThis buys what shared-vault setups don't: cross-vendor optimization (work goes to whoever is best at it), self-development (routing improves with use), and constitutional evolution (the protocol updates itself from friction). For pure note-passing without routing, prefer agent-vault.\n\n## When this skill is active\n\nAny multi-agent scenario where \"who should do this\" is a real question: founding or joining a polis; writing, claiming, or settling a contract; running a chavruta review; proposing or ratifying an amendment; or diagnosing a stalled contract, sync conflict, router pathology, or stuck quorum. Upgrading from agent-vault → `references\u002Ftroubleshooting.md` (\"Migrating from agent-vault\").\n\n## Structure of a polis\n\nA polis lives in a `_polis\u002F` folder at the project root; everything outside it is project content the protocol never touches.\n\n- `CONSTITUTION.md` — canonical tool-agnostic protocol · `index.md` — current state · `README.md` — human explainer\n- `chronicle.md` — append-only event log\n- `citizens\u002F\u003Cagent-id>\u002F` — `capability_card.yml`, `status.md`, `inbox.md`, `journal.md`\n- `contracts\u002Fopen\u002F\u003Cid>.md` · `contracts\u002Fsettled\u002F\u003Cid>.md` · `contracts\u002Frouting_stats.yml` (learned policy, updated on settle)\n- `lessons\u002F\u003Ccapability-tag>\u002F\u003Cid>.md` · `reviews\u002F\u003CYYYY-MM-DD-HHMM>-\u003Ccontract>.md` · `amendments\u002Fproposed|ratified\u002F`\n- Project root also gets `CLAUDE.md` \u002F `AGENTS.md` \u002F `GEMINI.md` bridge pointers and `.agents\u002Fskills\u002Fpolis-protocol\u002FSKILL.md` (Codex\u002FAntigravity copy), all pointing at `CONSTITUTION.md`.\n\nCitizens link to project files with wikilinks (`[[path\u002Fto\u002Fnote]]`). The `_polis\u002F` folder is the only thing the protocol owns.\n\n## The first thing to do every session\n\nBefore touching any project file, run the entry routine, in order:\n\n1. **Polis exists?** Look for `_polis\u002FCONSTITUTION.md`. If absent, scaffold it (see \"Founding a polis\").\n2. **You are registered?** Look for `_polis\u002Fcitizens\u002F\u003Cself>\u002Fcapability_card.yml`. If absent, register (see \"Registering a citizen\").\n3. **Read `_polis\u002FCONSTITUTION.md`** once per session — it is the canonical protocol for this polis; this SKILL.md is the seed it grew from.\n4. **Read `_polis\u002Findex.md`** — where things stand (a two-minute read).\n5. **Read your inbox** — `_polis\u002Fcitizens\u002F\u003Cself>\u002Finbox.md`.\n6. **Scan the tail of `chronicle.md`** backward until you reach the `last_seen_event:` in your `status.md`. That is your catch-up.\n7. **Read your open contracts** — anything in `_polis\u002Fcontracts\u002Fopen\u002F` with `owner: \u003Cself>`.\n8. **Update `last_seen_event` and `last_active` in your `status.md`.**\n9. **Report back to the user** — state of the project, what's in flight, what needs their input, a concrete first move.\n\nIf `chronicle.md` has grown large, the rollover policy (`references\u002Ftroubleshooting.md`) keeps it bounded.\n\n## The chronicle: recording what you did\n\nAfter each meaningful action, append exactly one line to `_polis\u002Fchronicle.md`. The format is rigid because the router and other citizens parse it:\n\n```\n- YYYY-MM-DD HH:MM | \u003Cagent-id> | \u003Cverb-phrase> | [[\u003Cwikilink>]] | \u003Cone-line note or - >\n- 2026-05-14 09:15 | codex-frontend-pesaj | settled contract | [[contracts\u002Fsettled\u002Fauth-refactor]] | tests passing, lesson filed\n```\n\nA meaningful action is anything another citizen needs to know about (contract opened\u002Fsettled, handoff, blocker, review requested, amendment proposed, index-keeper change). Internal reasoning and minor edits stay in your private `journal.md` and never reach the chronicle — protecting its signal-to-noise ratio is the single most important discipline.\n\nReserved verb phrases carry meaning scripts may filter on: `joined`\u002F`left polis`, `opened`\u002F`claimed`\u002F`settled`\u002F`abandoned contract`, `filed lesson`, `requested review`\u002F`signed off`\u002F`rejected review`, `proposed`\u002F`ratified`\u002F`rejected amendment`, `blocked on \u003Cthing>`\u002F`unblocked`, `assumed`\u002F`released index keeper`. Full semantics in `references\u002Fprotocol-spec.md`; otherwise use plain past-tense verbs.\n\n**Granularity — the most common failure is over-recording:** would another citizen waste time, make the wrong call, or duplicate work if this is *not* recorded? If yes, record it; if no, don't. Calibration table in `references\u002Ftroubleshooting.md`.\n\n## The Register: capability cards\n\nEvery citizen publishes `_polis\u002Fcitizens\u002F\u003Cagent-id>\u002Fcapability_card.yml` — the machine-parseable answer to \"who can do what\":\n\n```yaml\nagent_id: claude-research-pesaj\nvendor: anthropic        # model: claude-opus-4-7\ncapability_tags:\n  long-context-reading: { self_rating: 5, evidence: \"150k token context\" }\n  spanish-translation:  { self_rating: 3, evidence: \"native-ish, not certified\" }\ncost_envelope: { relative: medium }   # low|medium|high   latency: typical\u002Fmax minutes\ncontent_hash: \"sha256:…\"   # tamper-evidence, not a cryptographic signature\n```\n\nSelf-ratings are starting points, not truth — actual performance in `routing_stats.yml` takes over within a few tasks per tag. Keep tags specific (`react-component-design`, not `frontend-code`), edit your own card freely as you learn, and treat `content_hash` as tamper-evidence (it shows a card changed since last stamped via `polis verify`, not *who* changed it). New agents write their own card without asking — the Register is open by design. Full schema: `references\u002Fprotocol-spec.md`.\n\n## The Contract: structured tasks with learned routing\n\nContracts have three sections written over the contract's life: **Intent** (goal, acceptance criteria, required capability tags, deadline, cost ceiling, stakes) at open; **Assignment** (owner, approach, effort) at claim; **Settlement** (outcome, what worked\u002Fbit, lesson reference, quality score) at close. Schema in `references\u002Fprotocol-spec.md`; templates in `references\u002Ftemplates.md`.\n\n**Routing** is a multi-armed bandit: for each required tag, score every citizen from self-rating (weighted heavily at cold-start), historical quality in `routing_stats.yml`, cost, and availability; usually route to the top score (exploit), occasionally to another (explore, default 15%) to keep the policy honest. Runs as `scripts\u002Froute_contract.py` or as a brief reasoning step — same recommendation either way. It is a recommendation, **not a command**: any citizen may override by claiming and noting why in the `Assignment` section; overrides are logged and feed the policy. Math and tuning: `references\u002Frouting.md`.\n\n**Settling** does three things together: write the `Settlement` section; create a lesson under `_polis\u002Flessons\u002F\u003Ctag>\u002F\u003Cid>.md` (one paragraph + tags); post a `settled contract` chronicle line. The router reads settled contracts and lessons to update `routing_stats.yml` — that update is what makes the team improve. Lessons (frontmatter: `lesson_id`, `filed_by`, `capability_tags`, `related_contracts`, `quality_impact`, then one paragraph) are pulled by new contracts in the same tag before routing, so both the router and the executing agent carry the team's accumulated wisdom. This is what turns amnesiac agents into a team with institutional memory.\n\n## Chavruta review for high-stakes contracts\n\nAny contract flagged `stakes: high` (deletes data, ships to production, makes an architectural call, or commits to an expensive-to-reverse direction) requires a second citizen — ideally **from a different vendor** — to critique the plan before execution. Flow: owner writes the `Assignment` \"Plan\" and posts `requested review` + an inbox note to a strong reviewer → reviewer writes `_polis\u002Freviews\u002F\u003Cts>-\u003Ccontract>.md` answering \"what's right \u002F what's missing \u002F sign off, request changes, or reject\" → on sign-off the owner executes; on changes, revise once and repeat; on reject, escalate or abandon. Same-vendor review is allowed but weaker — the structural difference between models is the whole value. Use sparingly; most contracts are low-stakes and skip it. Details: `references\u002Fprotocol-spec.md`.\n\n## The Amendment: a polis that updates itself\n\nWhen a citizen notices a recurring failure, an unclear rule, or a routing pathology, they propose an amendment. Flow: write `_polis\u002Famendments\u002Fproposed\u002F\u003Cid>.md` (problem + proposed constitution change + any new rule\u002Fformat) → post `proposed amendment` to the chronicle and a one-line pointer to every inbox → citizens respond in the file (`agree | disagree | abstain | request changes` + rationale) → on quorum (default: simple majority of citizens active in the last 14 days) move it to `ratified\u002F` and edit `_polis\u002FCONSTITUTION.md`, one chronicle line each. Rejected amendments stay in `proposed\u002F` with `status: rejected` so future citizens know what was tried. The constitution is always canonical for a given polis; this SKILL.md is the seed. When to amend vs. work around, quorum rules, examples: `references\u002Famendments.md`.\n\n`polis reflect` automates the *noticing*: it mines settled-contract history for recurring process pathologies (chronic misroutes, low-quality tags, stakes miscalibration) and drafts evidence-backed proposals into `amendments\u002Fproposed\u002F` (authored by `polis-reflector`, citing the contracts). It only proposes — citizens still vote and ratify. Run `polis reflect` to preview, `--apply` to file them.\n\n## Founding a polis\n\nIf `_polis\u002FCONSTITUTION.md` does not exist, found the polis. Three paths, in order of preference — use the first one available in your environment:\n\n1. **Online, latest (recommended).** `uvx` fetches the newest release from PyPI, so users stay current automatically:\n   ```\n   uvx polis-protocol init --project-root \u003Cpath> --agent-id \u003Cyour-agent-id> \\\n     --vendor \u003Canthropic|openai|google|other> --model \u003Cmodel-id> --project-name \"\u003Cname>\"\n   ```\n   (Equivalent: `pipx install polis-protocol` then `polis init …`.)\n\n2. **Offline — no network, no install.** This skill ships a self-contained initializer next to its `templates\u002F`. Run it with the same flags from the skill folder:\n   ```\n   python scripts\u002Finit_polis.py --project-root \u003Cpath> --agent-id \u003Cyour-agent-id> \\\n     --vendor \u003C…> --model \u003Cmodel-id> --project-name \"\u003Cname>\"\n   ```\n   It needs only Python 3 and the bundled `templates\u002F` — no `polis` package, no network. Use this whenever `uvx`\u002F`pipx` is unavailable (sandbox, offline, no PyPI) instead of hunting for a missing CLI.\n\n3. **By hand — no Python at all.** Copy the templates in `references\u002Ftemplates.md`. The minimum viable polis is `_polis\u002FCONSTITUTION.md` + your own `capability_card.yml` + an empty `chronicle.md` with a frontmatter block.\n\nAll three write the full `_polis\u002F` structure (constitution, founder's capability card, seed `chronicle.md`, empty `routing_stats.yml`, and the `CLAUDE.md`\u002F`AGENTS.md`\u002F`GEMINI.md` bridge pointers). All are idempotent and never overwrite existing files. `polis init --repair` (or re-running the script) restores missing managed files; `polis migrate --plan|--apply|--rollback` handles schema upgrades reversibly.\n\n## Registering a citizen into an existing polis\n\nWhen you arrive at a project that has `_polis\u002FCONSTITUTION.md` but no card for you, register yourself — do not wait for permission:\n\n1. Pick an agent ID (convention below).\n2. Create `_polis\u002Fcitizens\u002F\u003Cyour-id>\u002F`.\n3. Write `capability_card.yml` (schema in `references\u002Fprotocol-spec.md`).\n4. Create empty `status.md`, `inbox.md`, `journal.md` from the templates.\n5. Post a `joined polis` line in `chronicle.md` linking your card.\n6. Continue with the entry routine.\n\n**Agent ID convention:** `\u003Cvendor-or-tool>-\u003Crole>-\u003Cproject>`. The vendor prefix lets any citizen see at a glance which model produced a chronicle line. Good: `claude-research-pesaj`, `codex-frontend-pesaj`, `gemini-translator-pesaj`. Bad: `agent-7a3f` (opaque), `helper` (generic), `gemini-2026-05-14-1430` (timestamps aren't identity). Lowercase, hyphens only, 8–40 chars; once registered, never rename.\n\n## Working across vendors\n\nThe bridge pointers written at bootstrap let Claude, Codex, Gemini CLI, GPT-based tools, and anything that reads markdown share one polis (`AGENTS.md` also covers Jules, Aider, goose, opencode, Zed, Warp, VS Code, Devin). All point at `_polis\u002FCONSTITUTION.md`, so the protocol updates in one file. Cross-vendor routing is the payoff: the bandit sends a translation to whoever has the best `spanish-translation` track record, not whoever happens to be the current chat.\n\n## Failure modes and recovery\n\nFull recovery steps in `references\u002Ftroubleshooting.md`. A citizen goes silent → check `status.md`; past the stale threshold, transfer ownership. Two citizens claim one contract → first-write-wins on `owner:`, loser re-picks. Router keeps picking wrong → likely cold-start; override a few to seed, else amend the weights. A card edited by a non-owner → `content_hash` mismatch via `polis verify`; restore and log. Amendment stuck without quorum → lower the activity threshold or merge proposals (30-day auto-expire). Polis too large → roll `chronicle.md` over quarterly, archive settled contracts past 90 days; lessons never roll over.\n\n## References\n\n- `references\u002Fprotocol-spec.md` — full schema for every file + reserved-verb semantics; read to validate or parse a file.\n- `references\u002Ftemplates.md` — annotated copy-paste templates; read when founding by hand, registering, or filing.\n- `references\u002Frouting.md` — bandit math, scoring, cold-start, explore-rate tuning; read when the router picks weird.\n- `references\u002Famendments.md` — when to amend vs. work around, quorum rules, examples.\n- `references\u002Ftroubleshooting.md` — failure modes, the granularity calibration table, scaling, agent-vault migration.\n- `templates\u002FPOLIS_CONSTITUTION.md` — the canonical protocol written into each polis on bootstrap.\n\n## Limitations\n\n- Use this skill only when the task clearly matches its upstream source and local project context.\n- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.\n- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.\n",{"name":5,"risk":24,"source":25,"license":15,"date_added":26,"description":7,"source_repo":27,"source_type":28,"license_source":29},"unknown","https:\u002F\u002Fgithub.com\u002Fyehudalevy-collab\u002Fpolis-protocol\u002Ftree\u002Fmain\u002F",1782864000000,"yehudalevy-collab\u002Fpolis-protocol","community","https:\u002F\u002Fgithub.com\u002Fyehudalevy-collab\u002Fpolis-protocol\u002Fblob\u002Fmain\u002FLICENSE","main","b1e4ffadb4f933bbbcaa03a83f8b9929171ac28b",".agents\u002Fskills\u002Fpolis-protocol-a-self-optimizing-city-of-agents",0,"https:\u002F\u002Fgithub.com\u002FHazek-dc\u002FPresensiGuru_FaceNet_EMAR","https:\u002F\u002Fgithub.com\u002FHazek-dc","2026-10-22 08:36:44",{"source":8,"skillName":5,"commands":38,"prompt":48,"zipAvailable":49},[39,42,45],{"tool":40,"command":41},"npx","npx skills add Hazek-dc\u002FPresensiGuru_FaceNet_EMAR --skill polis-protocol-a-self-optimizing-city-of-agents",{"tool":43,"command":44},"bunx","bunx skills add Hazek-dc\u002FPresensiGuru_FaceNet_EMAR --skill polis-protocol-a-self-optimizing-city-of-agents",{"tool":46,"command":47},"pnpm","pnpm dlx skills add Hazek-dc\u002FPresensiGuru_FaceNet_EMAR --skill polis-protocol-a-self-optimizing-city-of-agents","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FHazek-dc\u002FPresensiGuru_FaceNet_EMAR\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fpolis-protocol-a-self-optimizing-city-of-agents\u002FSKILL.md",true,[],[52,59,66,73,80,87],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M7DS6GGYRZAYD33PFPS8Z2T3","testing-best-practices","Laravel test design and review. Use when selecting coverage, naming or structuring tests, choosing assertions or test data, isolating dependencies, testing HTTP or security boundaries, improving suite performance, or reviewing test value. Use framework guidance or search-docs for Pest and PHPUnit syntax.","https:\u002F\u002Fgithub.com\u002FHazek-dc\u002FPresensiGuru_FaceNet_EMAR\u002Fblob\u002Fmain\u002Fattendance-web\u002F.claude\u002Fskills\u002Ftesting-best-practices\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":19},"01M7DS6BC3AW7HTPRHE2TTVKWM","tailwindcss-development","Always invoke when the user's message includes 'tailwind' in any form. Also invoke for: building responsive grid layouts (multi-column card grids, product grids), flex\u002Fgrid page structures (dashboards with sidebars, fixed topbars, mobile-toggle navs), styling UI components (cards, tables, navbars, pricing sections, forms, inputs, badges), adding dark mode variants, fixing spacing or typography, and Tailwind v3\u002Fv4 work. The core use case: writing or fixing Tailwind utility classes in HTML templates (Blade, JSX, Vue). Skip for backend PHP logic, database queries, API routes, JavaScript with no HTML\u002FCSS component, CSS file audits, build tool configuration, and vanilla CSS.","https:\u002F\u002Fgithub.com\u002FHazek-dc\u002FPresensiGuru_FaceNet_EMAR\u002Fblob\u002Fmain\u002Fattendance-web\u002F.claude\u002Fskills\u002Ftailwindcss-development\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":19},"01M7DS66GE6B11MYJDVC74HXM4","laravel-best-practices","Apply this skill whenever writing, reviewing, or refactoring Laravel PHP code. This includes creating or modifying controllers, models, migrations, form requests, policies, jobs, scheduled commands, service classes, and Eloquent queries. Triggers for N+1 and query performance issues, caching strategies, authorization and security patterns, validation, error handling, queue and job configuration, route definitions, and architectural decisions. Also use for Laravel code reviews and refactoring existing Laravel code to follow best practices. Covers any task involving Laravel backend PHP code patterns.","https:\u002F\u002Fgithub.com\u002FHazek-dc\u002FPresensiGuru_FaceNet_EMAR\u002Fblob\u002Fmain\u002Fattendance-web\u002F.claude\u002Fskills\u002Flaravel-best-practices\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":19},"01M7DS5ZW717DMS6P1E90AQCKV","infer-conventions","Use this skill to analyze how a Laravel application is actually written and record its conventions as shared rules. Trigger when the user wants to detect, infer, document, or standardize project conventions or coding style, set up or grow `.ai\u002Frules`, resolve mixed or conflicting patterns (e.g. \"are we using Form Requests or inline validation?\"), or onboard agents and teammates to \"how we do things here\". Covers: a systematic sweep of ~49 Laravel convention dimensions (validation, models, architecture, testing, frontend, database, console), open-ended house-pattern discovery, conflict reporting, and recording rules scoped to the right paths via the Boost `record-rule` MCP tool. Only run this skill when the user explicitly asks for it; never start a sweep as part of another task. Do not use for one-off code review, enforcing formatting a linter already handles, or editing `.ai\u002Frules` files by hand.","https:\u002F\u002Fgithub.com\u002FHazek-dc\u002FPresensiGuru_FaceNet_EMAR\u002Fblob\u002Fmain\u002Fattendance-web\u002F.claude\u002Fskills\u002Finfer-conventions\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":19},"01M7DS5W12RGCVJTFQJ1N0GB8E","inertia-react-development","Develops Inertia.js v2 React client-side applications. Activates when creating React pages, forms, or navigation; using \u003CLink>, \u003CForm>, useForm, or router; working with deferred props, prefetching, or polling; or when user mentions React with Inertia, React pages, React forms, or React navigation.","https:\u002F\u002Fgithub.com\u002FHazek-dc\u002FPresensiGuru_FaceNet_EMAR\u002Fblob\u002Fmain\u002Fattendance-web\u002F.claude\u002Fskills\u002Finertia-react-development\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M7DS5PVDPMPCWSK2RXPDC9BB","deploying-to-cloud","Deploys and manages Laravel applications on Laravel Cloud using the `cloud` CLI. Use when the user wants to deploy an app, ship to Cloud, create or manage applications, environments, databases, caches, object storage, queues, domains, instances, background processes, secrets, compute, scheduled tasks, or Laravel Cloud infrastructure; or check billing, usage, or spend. Triggers on deployment, shipping, Cloud management, environment setup, database provisioning, billing or usage queries, the `cloud` CLI, and Laravel Cloud deployment troubleshooting.","https:\u002F\u002Fgithub.com\u002FHazek-dc\u002FPresensiGuru_FaceNet_EMAR\u002Fblob\u002Fmain\u002Fattendance-web\u002F.claude\u002Fskills\u002Fdeploying-to-cloud\u002FSKILL.md",[],[]]