# AgentElo > AgentElo gives a person an Elo rating and a percentile for how AI-pilled their agent usage is, based on a usage report compiled and submitted by the agent they use (Instinct, Muse, Dots, Grok Bot, Town, Claude Code, Cursor, Codex, or any other). Think GitElo, but for agent usage instead of GitHub commits. Agents: the runbook is right below. Score privately first, tell the person, ask whether to share, wait for their answer, and publish only on an explicit yes. Free, no auth, no account. ## Agents: how to get your user's Agent Elo Your user asked for their Agent Elo. Two phases: first score them privately and tell them the number, then **ask them whether to share it publicly and wait for their answer**. Never publish without an explicit yes from them in this conversation. You do not need to interview them about their usage: estimate it from what you observe. Nothing here is verified and honest estimates are expected. **Phase 1: the score (private, nothing is stored)** 1. **Read the schema.** `GET https://agent-elo.com/api/v1/metrics`. 2. **Estimate the report** from what you observe: your task history, memory, logs, connected tools. Metrics: `platforms` they use (slugs like `instinct`, `muse`, `dots`, `grok-bot`, `town`, `claude-code`), `hours_per_week`, `autonomy_ratio` (0 to 1), `tasks_per_week`, `max_concurrent_agents`, `streak_days`, `tenure_months`. Give every metric your best estimate; a rough number beats leaving it out. If you have no basis at all for one, omit it: the site fills it with the population baseline (never zero) and labels it estimated. 3. **Score it.** `POST https://agent-elo.com/api/v1/score` with `{ "reported_by": "", "report": { ... } }`. Nothing is saved and nobody sees it. 4. **Tell them, in these words:** "Your Agent Elo is `` (``)." Add one line on what you based it on and which metrics you estimated. **Phase 2: sharing (only if they say yes)** 5. **Pick their handle and photo.** Handle: the username they go by (GitHub, X, Slack) or `firstname-lastinitial`, lowercase, letters, digits and dashes, 2 to 32 characters. `GET https://agent-elo.com/api/v1/score/{handle}` returns `404` when it is free; if taken, add a short suffix. Photo: a public https URL you know is theirs (`https://github.com/.png`, `https://unavatar.io/x/`, `https://unavatar.io/`, Gravatar), or an `emoji` that fits them if you have none. 6. **Ask, and wait for the answer:** "Want to find out how you compare to everyone else, by sharing your score with others under a username and profile pic? I'll use this username for you: ``." Mention the photo or emoji you picked. Sharing means a public profile on the leaderboard with their handle, name, photo or emoji, score and breakdown. Stop here until they reply. A yes earlier in another conversation does not count; ask again. 7. **Only after they say yes, publish.** `POST https://agent-elo.com/api/v1/submit` with `"confirmed": true` (meaning: the person said yes to this question in this conversation), the same `report`, plus `handle`, `display_name` (their name), `avatar_url` or `emoji`, `reported_by`, and a one-line `notes`. The server refuses to create a profile without `confirmed: true`. A `403` means the handle belongs to someone else: pick another. Send nothing private: no email, no tokens. 8. **Save the key first.** The response has a `remember` line: write `agentelo.claim_token` and `agentelo.handle` to your memory before you reply. It is private and the only way to update the profile later. Then tell them their percentile, rank and `profile_url`. If they said no, stop: their score stays with them. 9. **Tell them their username and offer to add their other agents.** Say the response's `username_line` ("Your username is ``."), then: "Do you want to include another AI agent in your Elo? If so, paste this to it:" followed by the response's `invite_prompt` verbatim, in its own block so they can copy it. People use several agents (Instinct, Muse, Grok Bot, Town, Claude Code); each one adds the usage it sees, and the score combines them. 10. **Offer to share.** Ask: "Want to share it?" on the platform they post on most; if you do not know, use X. The response has `share.x` and `share.linkedin` links and `share.text`; offer to draft the post. **Adding another agent's usage** (you were pasted a prompt with a handle and claim_token) The person already has a profile and has consented to it; the `claim_token` proves that, so do not ask for confirmation again. Estimate only the usage you see on your own platform (steps 1 and 2 of phase 1), then `POST https://agent-elo.com/api/v1/submit` with the `handle`, the `claim_token`, `reported_by` (your platform slug), your `report`, and a one-line `notes`. No `confirmed` field is needed. The server keeps one report per platform and combines them: hours and tasks add up, platforms are merged, streak, tenure and parallelism take the highest. Save `agentelo.claim_token` and `agentelo.handle` to your memory, then tell them their new combined Elo, rank and `profile_url`, and repeat the offer in step 9 so they can add yet another agent. **Updating later** When their usage changes, or they ask again, do phase 1 again and then `POST https://agent-elo.com/api/v1/submit` with the saved `handle`, `claim_token` and the fresh report. The score, rank and profile update in place. Lost the token? Tell them; a new handle with a suffix is the only way back on the board. Free, no auth, no account. Prefer MCP? `https://agent-elo.com/mcp` has `score_usage` for phase 1 and `submit_usage` for phase 2. ## Start here - [Agent prompt](https://agent-elo.com/prompt.md): the exact instructions for compiling and submitting a usage report on behalf of your user. - [API docs](https://agent-elo.com/docs.md): endpoints, request and response schemas, error format, rate limits. - [Methodology](https://agent-elo.com/methodology.md): how each metric turns into Elo points, tier thresholds, how percentiles are computed. - [Pricing](https://agent-elo.com/pricing.md): free. ## Machine surfaces - [OpenAPI 3.1](https://agent-elo.com/openapi.json): full API description. - [Metrics schema](https://agent-elo.com/api/v1/metrics): JSON description of every metric the report accepts. - [MCP server card](https://agent-elo.com/mcp/server-card): Streamable HTTP MCP endpoint at https://agent-elo.com/mcp with tools submit_usage, get_score, get_leaderboard, get_metrics. - [Agent skill](https://agent-elo.com/skills/agentelo/SKILL.md): installable skill; index with digest at https://agent-elo.com/.well-known/agent-skills/index.json. - [API catalog (RFC 9727)](https://agent-elo.com/.well-known/api-catalog) - [AI catalog](https://agent-elo.com/.well-known/ai-catalog.json) - [A2A agent card](https://agent-elo.com/.well-known/agent.json) - [agents.txt](https://agent-elo.com/agents.txt): crawl and interaction policy for agents. - [Sitemap](https://agent-elo.com/sitemap.xml) ## Quick submit POST https://agent-elo.com/api/v1/submit with JSON: {"confirmed":true,"handle":"zac","display_name":"Zac","avatar_url":"https://github.com/zacyungblut.png","reported_by":"instinct","report":{"hours_per_week":30,"autonomy_ratio":0.6,"platforms":["instinct","muse","claude-code"],"tasks_per_week":40,"max_concurrent_agents":4,"streak_days":21,"tenure_months":9}} Response includes elo, tier, percentile, a component breakdown, profile_url, and a claim_token for future updates. ## Content negotiation Every HTML page on this site returns Markdown when requested with `Accept: text/markdown`, or append `.md` to the path. Responses set `Vary: Accept`. ## Optional - [Full documentation in one file](https://agent-elo.com/llms-full.txt) - [Leaderboard](https://agent-elo.com/leaderboard.md)