Thank you for your interest in contributing to the Ultimate AI Agent Directory! This document provides guidelines and instructions for contributing to this project.
- About This Project
- Ways to Contribute
- Getting Started
- Contribution Workflow
- Data Quality Guidelines
- Technical Requirements
- Pull Request Process
- Code of Conduct
The Ultimate AI Agent Directory is a data-driven documentation project that maintains a comprehensive, curated directory of AI agent frameworks, platforms, tools, and resources. Unlike traditional software projects, this repository:
- Uses YAML files as the single source of truth (in
data/) - Automatically generates README.md and the static website from YAML data
- Focuses on data quality and accuracy over code development
We welcome the following types of contributions:
Submit new AI agent frameworks, platforms, tools, or resources that aren't currently in the directory. See Adding a New Entry below.
- Update outdated information
- Add missing metadata (GitHub repos, documentation links, pricing info)
- Improve descriptions for clarity and accuracy
- Mark entries as
verified: trueafter checking links and metadata
- Broken links or outdated information
- Incorrect categorization
- Missing important tools or frameworks
- Documentation improvements
- Enhance setup instructions
- Add examples or clarifications
- Fix typos or formatting issues
Propose new categories if you notice a gap in the current structure (see data/categories/).
- Git
- Python 3.8 or higher
- Text editor or IDE
-
Fork the repository on GitHub
-
Clone your fork:
git clone https://github.com/YOUR-USERNAME/Ultimate-Agent-Directory.git cd Ultimate-Agent-Directory -
Install dependencies:
make install
This creates a virtual environment and installs all Python dependencies.
-
Verify the setup:
make validate make generate
Both commands should complete without errors.
data/
├── agents/ # YAML files for all entries (SOURCE OF TRUTH)
│ ├── open-source-frameworks/
│ ├── no-code-platforms/
│ ├── autonomous-agents/
│ └── ...
├── boilerplates/ # YAML files for starter kits and templates
├── boilerplate-categories/ # Boilerplate stack/category definitions
└── categories/ # Category definitions
scripts/ # Python automation tools
templates/ # Jinja2 templates
static/ # Website assets
README.md # Generated from YAML (DO NOT EDIT DIRECTLY)
The repository is YAML-first. Agent entries live in data/agents/<category>/<slug>.yml;
boilerplate entries live in data/boilerplates/<stack>/<slug>.yml. README.md,
BOILERPLATES.md, and the static site are generated outputs.
-
Verify it exists and belongs
- Prefer official sources: GitHub repo, official product/docs page, official marketplace listing, or vendor docs.
- For GitHub-backed entries, verify the repo exists, is public, is not archived unless intentionally included, and matches the claimed product.
- Do not add duplicate products already present under another category unless the directory intentionally has separate entries for distinct surfaces.
-
Choose the correct existing category
- Agent categories are defined in
data/categories/*.yml. - Boilerplate categories are defined in
data/boilerplate-categories/*.yml. - Do not create new top-level categories as part of a normal add-entry change. If a new category is needed, propose it separately with rationale and anchor entries.
- Agent categories are defined in
-
Create a YAML file in
data/agents/{category}/{name}.yml:name: Your Tool Name url: https://example.com description: A concise, factual description (20-1000 characters). Focus on what the tool does and who uses it, avoiding marketing hype. category: category-id type: framework # or platform, tool, course, community, research tags: - machine-learning - automation # Optional but recommended: github_repo: owner/repo documentation_url: https://docs.example.com pricing: free # or freemium, paid, enterprise platform: - Python - TypeScript license: MIT featured: false verified: false
Boilerplate entries use the same YAML-first workflow but live under
data/boilerplates/{stack}/. Required boilerplate fields arename,url,description,category,type, andtags. Add schema-supported fields such asgithub_repo,license,platform,technical_stack,key_features, anddeploymentwhen verified. -
Keep tags valid
- Every tag must be lowercase, hyphenated, unique within the file, and present in
data/tags.yml. - Reuse existing tags where possible. Add only broadly useful new tags to
data/tags.yml, sorted consistently with the existing list.
- Every tag must be lowercase, hyphenated, unique within the file, and present in
-
Validate your changes:
make validate
Fix any schema validation errors reported.
-
Generate the derived docs:
make generate
This updates README.md with your new entry.
If boilerplate entries changed, also run:
make generate-boilerplates
For GitHub-backed entries, maintainers may also run:
make refresh-github-metadata
This refreshes GitHub stars, last-updated dates, and archived status.
-
Preview the website (optional):
make serve
Visit http://localhost:8001 to see your changes locally.
-
Commit both source YAML and generated output:
git add data/agents/{category}/{name}.yml git add README.md git commit -m "Add {Tool Name} to {category}" git push origin mainIf tags or boilerplates changed, also commit
data/tags.ymlandBOILERPLATES.md.
-
Edit the YAML file in
data/agents/{category}/{name}.yml -
Validate and regenerate:
make validate make generate
-
Commit both files:
git add data/agents/{category}/{name}.yml git add README.md git commit -m "Update {Tool Name}: {brief description of changes}" git push origin main
Always run these commands:
make validate # Ensures YAML files pass schema validation
make generate # Updates README.md from YAML dataThen commit both the YAML file(s) you edited and the generated README.md.
- Accuracy over hype: Focus on factual capabilities, not marketing claims
- Concise: 2-3 sentences ideal (20-1000 characters enforced)
- Factual: What the tool does and who uses it
- No attribution: Never mention individual contributors or maintainers
- No affiliate links: Direct to official sources only
Good Example:
Open-source framework for building autonomous data labeling agents. Enables creation of AI agents that can label, process, and improve data quality autonomously with feedback loops and continuous learning capabilities.
Bad Example:
Amazing framework created by John Doe! The best tool ever for data labeling!!! Click here to try it now!
Every entry must include:
name(1-100 characters)url(valid HTTP/HTTPS URL)description(20-1000 characters)category(must match a category ID indata/categories/)type(one of: framework, platform, tool, course, community, research)tags(list of lowercase, hyphenated tags)
Include when available:
github_repo(format: "owner/repo")documentation_urlpricing(free, freemium, paid, enterprise)platform(e.g., ["Python", "TypeScript"])license(e.g., "MIT", "Apache-2.0")
- Use lowercase letters
- Use hyphens for multi-word tags (e.g.,
machine-learning) - Be specific and relevant
- Common tags:
automation,nlp,machine-learning,workflow,integration,testing,deployment
- ASCII UTF-8 LF only - No special characters or emojis in YAML files
- Line endings: LF (Unix-style), not CRLF
- Use a text editor that supports UTF-8 LF encoding
- Use 2-space indentation (no tabs)
- Ensure proper YAML syntax (use a YAML linter)
- Quote URLs and strings with special characters
- Follow the schema defined in
scripts/models.py
- All URLs must be valid HTTP/HTTPS
- No localhost or IP addresses
- Prefer HTTPS when available
- Links should point to official sources
- Format:
"owner/repo"(e.g.,"langchain-ai/langchain") - Do not include
https://github.com/ - Validate the repository exists and is public
-
Fork the repository and create a new branch:
git checkout -b add-new-tool
-
Make your changes following the guidelines above
-
Validate and generate:
make validate make generate
-
Test locally (optional but recommended):
make serve
-
Commit your changes:
git add data/agents/{category}/{name}.yml git add README.md git commit -m "Add {Tool Name}: brief description" -
Push to your fork:
git push origin add-new-tool
-
Create a Pull Request on GitHub with:
- Clear title describing the change
- Description explaining what was added/changed and why
- Link to the official website/documentation
- Confirmation that you've run
make validateandmake generate
Before submitting, ensure:
- Ran
make validatewithout errors - Ran
make generateto update README.md - Committed both YAML file(s) and README.md
- Description is factual and concise (20-1000 chars)
- All URLs are valid and point to official sources
- Tags are lowercase and hyphenated
- Category is correct
- No attribution to individuals
- ASCII UTF-8 LF encoding used
Your pull request will automatically trigger:
- YAML validation against Pydantic schemas
- README generation test
- Website generation test
All checks must pass before merging.
- Be respectful: Treat all contributors with respect and kindness
- Be factual: Focus on accuracy and objectivity
- Be collaborative: Provide constructive feedback
- Be inclusive: Welcome contributions from everyone
- Harassment, discrimination, or personal attacks
- Spam or promotional content
- Deliberately submitting false or misleading information
- Violating copyright or intellectual property rights
Violations of the code of conduct may result in:
- Warning
- Temporary ban from contributing
- Permanent ban from the project
Report issues to the repository maintainers via GitHub Issues.
- Documentation: Check
docs/GETTING_STARTED.md,docs/REFERENCE.md, anddocs/ADVANCED.md - Issues: Search existing issues or create a new one
- Discussions: Join conversations in GitHub Discussions
- Commands Reference:
make install # Install dependencies make validate # Validate YAML files make generate # Generate README.md make site # Generate website make serve # Build and serve locally make test # Run validation + generation make clean # Remove generated files
- YAML files: lowercase with hyphens (e.g.,
langchain.yml,autogpt.yml) - Match the tool name when possible
- Use descriptive names for multi-word tools (e.g.,
semantic-kernel.yml)
# Validate a specific file
python scripts/validate.py data/agents/open-source-frameworks/langchain.yml
# Check what changed
git status
git diff
# Preview before committing
make serveIf you're unsure about anything:
- Look at existing entries in
data/agents/for examples - Check the schema in
scripts/models.py - Open an issue asking for guidance
- Start with a draft pull request marked as "WIP" (Work in Progress)
Thank you for contributing to the Ultimate AI Agent Directory! Your contributions help make this resource valuable for the entire AI community.