agentfirst.directory

Submit

Submit a tool

Add a tool or category to the content repo by opening a pull request.

Agent Shortcut

Get your agent to do it

Point it to agentfirst.directory/SKILL.md - it tells your agent which repo to edit and how to format the files.

Repo workflow

Open a PR

Make listing changes in bradvin/agentfirst.directory . Only edit bradvin/agentfirst.directory-site for site changes.

  1. Pick the closest existing category in categories/.
  2. Add a tool file in tools/.
  3. Add a short factual body, ideally with a ## So agents can... section.
  4. Add a category file only if the current list clearly does not fit.
  5. Open a PR against main.

PR checklist

Required One tool file Add a markdown file in tools/.
Usually required Useful URLs Add githubUrl when the tool is open source.
Only if needed New category file Add one only when nothing existing fits.

Local workflow

git clone https://github.com/bradvin/agentfirst.directory.git
cd agentfirst.directory

# add or update content
$EDITOR tools/coolapi.md
$EDITOR categories/agent-security.json

git checkout -b add-coolapi
git add .
git commit -m "Add CoolAPI"
git push origin add-coolapi

Repo paths

tools/<slug>.mdOne file per tool.
categories/<slug>.jsonOne file per category.
bradvin/agentfirst.directoryThe content repo.
mainOpen the PR against the default branch.

Tool entry

Add a tool markdown file

Each tool is one markdown file with frontmatter and a short body.

Tool entry

---
slug: "coolapi"
name: "CoolAPI"
description: "An agent-first API for doing cool things"
category: "agent-security"
tags:
  - "mcp"
  - "security"
  - "api"
websiteUrl: "https://coolapi.dev"
githubUrl: "https://github.com/cooldev/coolapi"
logoUrl: "https://www.google.com/s2/favicons?sz=64&domain_url=https://coolapi.dev"
ogImageUrl: "https://coolapi.dev/og-image.png"
pricing: "freemium"
---

Short summary of what the tool does.

## So agents can...

- do outcome one
- do outcome two
- do outcome three

Required frontmatter

slugLowercase kebab-case.
namePublic tool name.
descriptionShort summary.
categoryExisting category slug.
tagsAt least one tag.
websiteUrlRequired URL.
pricingOne of open-source, freemium, free, or paid.

Optional frontmatter

githubUrlInclude it when the tool is open source.
logoUrlAdd the canonical value if you already know it.
ogImageUrlAdd the social preview image if you already know it.
sortOrderOptional integer when ordering matters.

Writing guidance

Keep the body factual and agent-specific

Short, concrete descriptions work best. Prefer canonical URLs, avoid duplicate listings, and add a brief agent-enablement section when it helps explain why the tool belongs in the directory.

Suggested section

## So agents can...

- do outcome one
- do outcome two
- do outcome three

What happens after merge

PR authorAuthor attribution is derived automatically.
logoUrlMissing values can default from the website favicon.
ogImageUrlMissing values can be discovered from site metadata.

Category proposals

Add a category only if needed

Add one only when no existing category fits.

Category JSON

{
  "slug": "agent-security",
  "label": "Agent Security",
  "sortOrder": 110
}

When a new category is justified

  1. No existing category fits.
  2. The label is short and clear.
  3. It could fit more than one tool.
  4. The same PR uses it on at least one tool.
  1. Create categories/<slug>.json.
  2. Use it in at least one tool in the same PR.
  3. Keep the slug lowercase and the label concise.
  4. Open the PR against main.