# How to Contribute New Agent Skills to the Awesome-Agent-Skills Repository

> Learn how to contribute new agent skills to the VoltAgent awesome-agent-skills repository. Follow our simple steps for adding your skill and submitting a pull request.

- Repository: [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
- Tags: how-to-guide
- Published: 2026-04-22

---

**To contribute a new agent skill to the VoltAgent catalog, ensure your repository follows the naming convention `author/skill-name`, add a markdown entry to [`README.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/README.md), and open a pull request titled "Add skill: author/skill-name".**

The **VoltAgent/awesome-agent-skills** repository maintains a curated list of ready-to-use Agent Skills from the community. Unlike monolithic projects, this repository does not host skill code directly; it indexes external public repositories that meet specific documentation and naming standards. Contributing new agent skills requires updating the master list in [`README.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/README.md) according to the guidelines defined in [`CONTRIBUTING.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/CONTRIBUTING.md).

## Verify Your Skill Repository Meets Requirements

Before submitting a contribution, confirm your skill repository satisfies three mandatory criteria defined in **[CONTRIBUTING.md](https://github.com/VoltAgent/awesome-agent-skills/blob/main/CONTRIBUTING.md)**:

- **Public visibility**: The repository must be publicly accessible on GitHub.
- **Documentation**: Include a [`README.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/README.md) or [`SKILL.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/SKILL.md) file explaining installation and usage.
- **Naming convention**: Use the format `author/skill-name` (e.g., `janeDoe/semantic-search`).

These requirements ensure the catalog maintains high-quality, discoverable resources that users can immediately integrate into their agent workflows.

## Locate the Correct Category in README.md

Open **[README.md](https://github.com/VoltAgent/awesome-agent-skills/blob/main/README.md)** and identify the appropriate section for your skill. The file organizes entries by development team (e.g., "Skills by Vercel Engineering Team") and community categories (e.g., "AI and Data").

If no existing category matches your skill's functionality, append your entry to the **Other** section at the bottom of the document. When creating a new category heading, use `###` (H3) formatting to maintain the document hierarchy.

## Format Your Entry Using the Standard Template

Insert your skill entry at the **end** of the chosen section using this exact markdown pattern:

```markdown
- **[author/skill-name](https://github.com/author/skill-name)** – Concise description (≤10 words)

```

Key formatting requirements include:
- A leading dash and space (`- `)
- Bold repository name wrapped in brackets
- Direct GitHub URL in parentheses
- An en-dash (`–`) separator before the description
- Maximum 10 words for the description

For example, adding a semantic search skill would look like:

```markdown
- **[janeDoe/semantic-search](https://github.com/janeDoe/semantic-search)** – Fast vector similarity search for AI agents

```

## Submit Your Pull Request

Commit your changes to a new branch and open a pull request following the protocol from **[CONTRIBUTING.md](https://github.com/VoltAgent/awesome-agent-skills/blob/main/CONTRIBUTING.md)**:

1. **Branch naming**: Create a descriptive branch such as `add-author-skill-name`.
2. **Commit message**: Use `Add skill: author/skill-name` for clarity.
3. **PR title**: Format exactly as `Add skill: author/skill-name`.
4. **PR description**: Provide additional context about the skill's functionality if needed.

Maintainers will verify link validity, documentation quality, and adherence to formatting standards before merging.

## Git Workflow Reference

Use these commands to prepare your contribution locally:

```bash

# Clone your fork

git clone https://github.com/yourusername/awesome-agent-skills.git
cd awesome-agent-skills

# Create feature branch

git checkout -b add-janeDoe-semantic-search

# Edit README.md, then stage and commit

git add README.md
git commit -m "Add skill: janeDoe/semantic-search"

# Push and open PR

git push origin add-janeDoe-semantic-search

```

## Summary

- **VoltAgent/awesome-agent-skills** indexes external skill repositories rather than hosting code directly.
- Skill repositories must be public, documented, and follow the `author/skill-name` naming pattern.
- Add entries to [`README.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/README.md) using the exact format: `- **[author/name](URL)** – Description`.
- Use the PR title `Add skill: author/skill-name` to match contribution guidelines.
- Reference [`CONTRIBUTING.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/CONTRIBUTING.md) for complete quality requirements and review processes.

## Frequently Asked Questions

### What file format should the skill documentation use?

Your skill repository must contain either a [`README.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/README.md) or [`SKILL.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/SKILL.md) file at the root level. This file should explain how to install, configure, and invoke the skill. According to the [`CONTRIBUTING.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/CONTRIBUTING.md) requirements, entries without proper documentation will not be accepted into the catalog.

### Where should I place my skill if it doesn't fit existing categories?

Locate the **Other** section at the bottom of [`README.md`](https://github.com/VoltAgent/awesome-agent-skills/blob/main/README.md) and append your entry there. If the **Other** heading does not exist, create it using `### Other` followed by a blank line, then add your formatted bullet entry. This ensures all contributions maintain the document's organizational structure.

### How long can the skill description be?

Keep your description concise—**10 words or fewer**. The format requires an en-dash (`–`) separating the bold repository link from the description text. Short descriptions improve scannability and maintain consistency across the curated list.

### Can I update an existing skill entry instead of adding a new one?

Yes. If you need to correct a URL or update a description for an existing skill, follow the same PR workflow but use a descriptive title like `Update skill: author/skill-name`. Ensure your changes preserve the required markdown format and do not alter the entry's category without justification.