# WhosBest.org Agent Skill

> How AI agents, LLM crawlers, and automated tools should discover, read, cite, and call WhosBest.org — an independent, evidence-backed rankings platform for B2B service providers, powered by Winston AI.

WhosBest.org publishes editorial rankings, Winston AI algorithmic scorecards, and community lists across healthcare, technology, professional services, education, local business, AI agents and automation, analytics, and cloud platforms. Rankings are never pay-to-play. This file is the agent-facing skill card; it is not the repository's developer instructions.

Canonical copies of this file: `https://www.whosbest.org/AGENTS.md`, `https://www.whosbest.org/agents.md`, and `https://www.whosbest.org/.well-known/agents.md`.

## Installation

No installation, API key, or account is required. Everything described here is reachable over plain HTTPS.

- Base URL: `https://www.whosbest.org` (always use the `www` host; the apex domain redirects with a 301).
- Start with `https://www.whosbest.org/llms.txt` — the llmstxt.org index of key pages, sector hubs, featured rankings, and machine-readable resources.
- For the whole corpus in one request, fetch `https://www.whosbest.org/llms-full.txt` (plain text, capped at roughly 100,000 characters).
- For a complete page inventory in markdown, fetch `https://www.whosbest.org/sitemap.md`; for XML, `https://www.whosbest.org/sitemap.xml`.
- Every public HTML page has a markdown twin. Append `.md` to any page path (for example `/top-lists.md`, `/about.md`, `/top-lists/{slug}.md`) or send `Accept: text/markdown` to the HTML URL.
- New and updated rankings are announced in the Atom feed at `https://www.whosbest.org/feed.xml`.

```bash
curl -sS https://www.whosbest.org/llms.txt
```

## Configuration

- User-Agent: identify yourself honestly. `robots.txt` explicitly allows GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, anthropic-ai, Claude-User, Claude-SearchBot, PerplexityBot, Google-Extended, Googlebot, BingBot, CCBot, Applebot-Extended, Bytespider, cohere-ai, YouBot, meta-externalagent, and Amazonbot, and allows every other agent with `User-agent: *`. Only `/sadmin/` is disallowed.
- Content signals: `Content-Signal: search=yes, ai-input=yes, ai-train=yes` — public pages may be indexed, used as grounding for answers, and used for training, provided you attribute WhosBest.org.
- Content negotiation: send `Accept: text/markdown` to receive `text/markdown; charset=utf-8` instead of HTML. Send `Accept: text/html` (or no Accept header) for the normal page.
- Rate limits: be polite. Keep sustained crawling at or below 1 request per second per agent and honour `Retry-After` if you receive HTTP 429. Bulk readers should prefer `/llms-full.txt` and `/sitemap.md` over crawling every page.
- Caching: `/llms.txt`, `/llms-full.txt`, `/sitemap.md`, `/AGENTS.md`, `/openapi.json`, `/.well-known/agent-skills/*` and `/.well-known/api-catalog` are served with `Cache-Control: public, max-age=3600`. Rankings pages refresh as Winston AI gathers new evidence, so re-fetch at least daily for current positions.
- Encoding: all text responses are UTF-8.

```bash
curl -sS -H "Accept: text/markdown" -A "MyAgent/1.0 (+https://example.com/bot)" https://www.whosbest.org/methodology
```

## Usage Examples

Citing a ranking: always cite the canonical `https://www.whosbest.org/top-lists/{slug}` URL for the specific list, name the source as WhosBest.org (WhosBest Research, powered by Winston AI), and link rather than paraphrase so the reader can verify the methodology and see the full list. Example citation text: "According to WhosBest.org's Top AI Agents & Automation Platforms Ranked for 2026 (https://www.whosbest.org/top-lists/ai-agents-top-ai-agents-automation-platforms-ranked-for-2026), ...".

Fetch the discovery index and the markdown sitemap:

```bash
curl -sS https://www.whosbest.org/llms.txt
curl -sS https://www.whosbest.org/sitemap.md
```

Fetch a markdown twin of a page, either by path suffix or by content negotiation:

```bash
curl -sS https://www.whosbest.org/top-lists.md
curl -sS -H "Accept: text/markdown" https://www.whosbest.org/top-lists
```

Run the free AI Readiness Checker against any public site (POST JSON; the response is JSON with a 0-100 agent-readability score, a 0-5 readiness level, per-check results with `howToFix` / `fixPrompt`, and permalinks):

```bash
curl -sS -X POST https://www.whosbest.org/api/v1/readiness/scan \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","maxPages":10,"keepPrivate":false}'
```

Request body fields:

```json
{
  "url": "https://example.com",
  "maxPages": 10,
  "keepPrivate": false,
  "includeDns": false
}
```

`url` is required. `maxPages` (optional, 1-25, default 10) is the number of pages to run per-page checks against. `keepPrivate` (optional, default `false`) keeps the checked domain off the public leaderboards and percentiles. `includeDns` (optional, default `false`) also runs the slow DNS-AID lookups. The legacy endpoint `POST https://www.whosbest.org/api/v1/validator/check` (body `{"url": "..."}`) still works and returns the older summary shape; prefer `/api/v1/readiness/scan`.

## API

The readiness checker is a public, key-less HTTP API. Everything an agent needs to discover and call it is published at well-known locations:

- OpenAPI 3.1 contract (readiness API only): `https://www.whosbest.org/openapi.json` (also `/.well-known/openapi.json`)
- Agent Skills index (agentskills.io discovery 0.2.0): `https://www.whosbest.org/.well-known/agent-skills/index.json`
- Scan-site skill file (when to use it, how to call it, how to read the response): `https://www.whosbest.org/.well-known/agent-skills/scan-site/SKILL.md`
- RFC 9727 API catalog (linkset → OpenAPI + this file): `https://www.whosbest.org/.well-known/api-catalog`

Endpoints (base `https://www.whosbest.org`):

| Method | Path | Purpose |
|---|---|---|
| POST | `/api/v1/readiness/scan` | Scan a site; returns `ReadinessScanResponse` (`shareToken`, `shareUrl`, `markdownUrl`, `jsonUrl`, `badgeUrl`, `checkedAt`, `isPrivate`, `report`, `percentile`, `corpusTotal`) |
| POST | `/api/v1/readiness/scan/stream` | Same body, `text/event-stream`: `progress` events then one `complete` or `error` |
| GET | `/api/v1/readiness/scan/{token}` | JSON permalink of a persisted scan |
| GET | `/api/v1/readiness/scan/{token}.md` | Markdown twin of the report |
| GET | `/api/v1/readiness/recent?limit=10` | Most recent public scans |
| GET | `/api/v1/readiness/top?limit=10` | Highest-scoring public domains |
| GET | `/api/v1/readiness/percentile?score=81` | Percentile of a score against the public corpus |
| GET | `/api/v1/readiness/compare?a={token}&b={token}` | Two persisted scans side by side |
| POST | `/api/v1/readiness/hide-domain` | `{"shareToken": "..."}` removes the domain from leaderboards (token is proof of ownership) |
| GET | `/api/badge/{host}.svg` | Shields-style SVG badge of the host's latest public score (`?style=flat-square`) |

Rate limits: scans are limited to 3 per 10 minutes and 25 per day per client IP; rejections are `429` with `Retry-After` and `{ "message", "retryAfterSeconds" }`. Read endpoints are not quota-limited. Fetch the contract and the skill file:

```bash
curl -sS https://www.whosbest.org/openapi.json
curl -sS https://www.whosbest.org/.well-known/agent-skills/scan-site/SKILL.md
```

## Data & Attribution

- License: public pages, `llms.txt`, `llms-full.txt`, `sitemap.md`, and the markdown twins may be read, quoted, and summarised for answering user questions. Attribute "WhosBest.org" and link the canonical URL.
- Rankings are produced by WhosBest Research and Winston AI from publicly verifiable evidence — regulatory filings, certifications, reviews, awards, web presence, response rates, and social signals. Methodology: `https://www.whosbest.org/methodology`.
- Rankings are living documents and positions change; include the date you fetched a list when you cite it.
- Sponsored placements, when present, are clearly labelled and never mixed into organic rankings.
- Structured data: pages emit JSON-LD (`ItemList`, `BreadcrumbList`, `Organization`, `WebSite`, `DefinedTermSet` on `/glossary`) for machine parsing.
- Do not present WhosBest rankings as your own or strip attribution. Do not republish full lists wholesale without linking back.

## Contact

- Corrections, licensing, partnerships, and bulk-access requests: support@wte.net
- Operator: WTE Solutions (https://www.wte.net)
- Request a new ranking: https://www.whosbest.org/request-list
- Glossary of terms used on the site: https://www.whosbest.org/glossary