---
name: grok bots directory
description: >-
  Use when submitting a Grok bot to grokbotsdirectory.com. No API key required.
---

# grok bots directory

A public directory of Grok bots (x.ai bot templates) at https://grokbotsdirectory.com

This skill: `https://grokbotsdirectory.com/skills.md`

## Agent workflow (self / template → directory)

When a user asks you to submit **this bot** (or a bot you just packaged) to the directory:

1. **Draft the template** — Export a public shareable template of the bot (Grok Bot: `create_bot_share_json` / export-bot-template). Stage it and have the user confirm the review card so it publishes.
2. **Ask for the share URL in the same step** — Publishing does **not** return `https://x.ai/bot/…` to the agent. Tell the user to publish, then paste the plain-text share URL into chat. Do not stall searching the box, transcripts, or APIs for a URL they never sent.
3. **On paste, submit automatically** — Verify the URL resolves to a real `x.ai/bot/` page (HTTP 200), then submit it as below. Report the submission `id` and `status` (usually `pending`).

Do not invent a share URL. Do not wait hoping publish will push the link back into chat.

## Submit a bot

`POST https://grokbotsdirectory.com/api/v1/submissions`

```sh
curl -X POST https://grokbotsdirectory.com/api/v1/submissions \
  -H 'Content-Type: application/json' \
  -A 'YourBot/1.0' \
  -d '{"share_url":"https://x.ai/bot/bot-id-here"}'
```

Fields:

- `share_url` (required): the bot's x.ai share URL.
- `tweet_url` (optional): a tweet showcasing the bot.
- `x_handle` (optional): the creator's X handle, without the leading `@`.
- `note` (optional): why this bot belongs here, max 2000 characters.
- `email` (optional): contact email for this listing.

Response: `201 { "ok": true, "submission": { "id": "...", "status": "pending" } }`

Submissions are reviewed before they appear in the directory. Submitting a
bot that is already listed returns `409 conflict`. Agent submissions are
limited to 5 per day per IP.

## Or submit over MCP

Add the public MCP server and call `submit_grok_bot(share_url, tweet_url?, x_handle?, note?, email?)`:

```json
{
  "mcpServers": {
    "grok-bots-directory": {
      "url": "https://grokbotsdirectory.com/mcp"
    }
  }
}
```

In Grok Bot: `AddMcpServer name=grok-bots-directory url=https://grokbotsdirectory.com/mcp`

Setup for Claude and Cursor: https://grokbotsdirectory.com/connect

## Errors

JSON `{ "error": true, "code": "...", "message": "..." }`
Common: `400 validation_error`, `409 conflict`, `429 rate_limited`.

## Do not

- Submit bots you have not verified resolve to a real `x.ai/bot/` page
- Resubmit the same bot after a `409 conflict`
- Assume the agent can discover a published template's share URL without the user pasting it