# Set up setupmd (instructions for agents)

A person asked you to set up setupmd, an open directory of setup files that AI agents use to find and set up apps. Most people send this link to get **their own app listed**. Some want to **use the directory** to find apps. If their message doesn't say which, ask in one short line.

Complete each step yourself with your own tools. A step marked **Ask the person** needs them: ask in one short line, wait for their answer, then go on.

What this never does: it creates no account, spends nothing, and never posts or publishes anything without the person's OK.

## Part A: list the person's app

### 1. Find the app

Work out the product's name and its domain, like `yourapp.com`, from the project you're in, its README or its website. If you can't tell, **ask the person:** "Which app should I list, and what's its website?"

Fetch https://setupmd.com/api/apps.json. If the domain is already listed, tell the person, give them the page link `https://setupmd.com/<domain>/`, and stop.

### 2. Find or write the setup file

Check whether the site already has one, by fetching each of these on the app's domain: `/setup.md`, `/install.md`, `/skill.md`, `/agents.md`, `/docs/setup.md`, `/docs/install.md`. If one exists and explains how an agent sets the app up for a person, use it and go to step 4.

Otherwise write one. Use only facts you can find in the app's docs, code or website, and never invent a command, a URL or a price. Follow this shape:

```markdown
---
description: One plain sentence on what the app does.
---

# Set up <App> (instructions for agents)

A person asked you to set up <App>, so they can <what it does for them>. Complete each step yourself.
A step marked **Ask the person** needs them: ask in one short line, wait until they say it's done, then go on.

What setup never does: <what it won't spend, post or change>.

## 1. Account
**Ask the person:** "Do you have a <App> account?" If not, send them to <signup URL>. Never create it for them.

## 2. Connect
One short section per way to connect: MCP server, CLI, SDK or API key, and a section per agent if the steps differ.

## 3. Check it works
A free call that proves the connection, and what a good answer looks like.

## 4. Finish
What to tell the person, in one line.

## Remove it
How to disconnect or uninstall.
```

The `description` line becomes the summary in the directory. **Ask the person:** show them the draft and wait for their OK or changes.

### 3. Put the file on the app's own site

The file should be served at `https://<domain>/setup.md` as `text/markdown` or `text/plain`. A file there proves who wrote it, so nothing else is needed.

- If you have the site's code, add the file where the framework serves static files at the root: `public/setup.md` for Next.js, Vite, Astro, Nuxt or Remix; `static/setup.md` for SvelteKit, Hugo or Docusaurus; the site root for plain HTML.
- **Ask the person** before you commit or deploy anything.
- Once it's live, check it: `curl -sI https://<domain>/setup.md` should answer 200, and not as `text/html`.

If you can't change the site, skip to step 4b.

### 4a. Submit the link

**Ask the person:** "May I submit <App> to setupmd? It opens a public GitHub issue under your account." Then, if `gh` is installed and signed in:

```bash
gh issue create -R shansabnani/setupmd --title "submit: https://<domain>/setup.md" --body "use_cases: email, automation"
```

Use cases are optional. Valid names are listed at https://setupmd.com/api/use-cases.json, as `slug`.

### 4b. Or upload the file

Only if the file can't be hosted. The directory needs proof that the person runs the domain. **Ask the person** to add one of these, using their GitHub username, or add it yourself if you have the site's code and they agree:

- On the home page, inside `<head>`: `<meta name="setupmd-verify" content="<github-username>">`
- Or a DNS TXT record at `_setupmd.<domain>` with the value `github=<github-username>`

Get the username with `gh api user --jq .login`. Then, with the person's OK:

```bash
gh issue create -R shansabnani/setupmd --title "submit: <domain>" --body-file setup.md
```

### 5. Check the result

A bot replies on the issue within a minute or two. Read the reply with `gh issue view <number> -R shansabnani/setupmd --comments`. If it was rejected, the reply says why: fix that and submit again.

If `gh` isn't available, give the person this link instead, and tell them which file to use: https://setupmd.com/submit/

### 6. Finish

Tell the person in one or two lines, for example: "<App> is listed at https://setupmd.com/<domain>/. Agents searching for <what it does> can now find it and set it up."

## Part B: use the directory to find apps

### Claude Code

```bash
claude plugin marketplace add shansabnani/setupmd
claude plugin install setupmd@setupmd
```

**Ask the person:** "Type `/reload-plugins` to load setupmd, then tell me to go on."

### Other agents with a shell

```bash
npx skills add shansabnani/setupmd --skill setupmd
```

### Anything else

No install is needed. To find an app, fetch `https://setupmd.com/api/find?q=<what the person needs>`, and follow https://setupmd.com/AGENTS.md.

Check it works by fetching https://setupmd.com/api/find?q=send+email. A list of apps means it's ready. Tell the person: "setupmd is ready. Ask me to find or set up an app and I'll check the directory first."

To remove it: `claude plugin uninstall setupmd@setupmd`, or `npx skills remove setupmd`.