# How to Contribute a New Claude Skill to the Awesome Claude Skills Repository

> Contribute a new Claude Skill to the Awesome Claude Skills repository. Follow simple steps to add your skill, test it, and submit a pull request. Enhance the community today.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: how-to-guide
- Published: 2026-08-29

---

**To contribute a new Claude Skill, create a lowercase-hyphenated folder containing a [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file with YAML front-matter, test the skill across Claude.ai and Claude Code, update the central [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md), and submit a pull request following the contribution guidelines.**

The **ComposioHQ/awesome-claude-skills** repository is a curated collection of reusable capabilities that extend Claude's functionality across different contexts. Contributing a new skill involves following a standardized folder structure, documentation format, and testing protocol to ensure consistency and portability across the Claude ecosystem.

## Understanding the Repository Structure

Each skill in the repository lives as an independent folder within the root directory. According to the [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) *Creating Skills* section, the repository expects a specific layout that separates skill instructions from optional helper assets.

A standard skill folder follows this structure:

```text
my-awesome-skill/
├── SKILL.md          # required – skill instructions & metadata

├── scripts/          # optional – helper scripts used by the skill

│   └── run.sh
├── templates/        # optional – document templates

│   └── report.md
└── resources/        # optional – reference files, images, etc.

    └── data.json

```

The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file is mandatory and serves as the single source of truth for Claude's behavior. The `scripts/`, `templates/`, and `resources/` directories are optional but recommended for complex skills requiring external tooling or reference data.

## Step-by-Step Contribution Process

### 1. Create the Skill Folder

Name your folder in lowercase with hyphens separating words (e.g., `changelog-generator/`, `pr-review-assistant/`). This naming convention ensures compatibility with file systems and consistent URL patterns. Place this folder at the repository root alongside existing skills.

### 2. Author the SKILL.md File

The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file must contain YAML front-matter followed by structured documentation. As specified in [`CONTRIBUTING.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/CONTRIBUTING.md), the file requires:

- **YAML front-matter** with `name` and `description` fields
- A clear H1 title and detailed description
- **"When to Use This Skill"** bullet points defining use cases
- Step-by-step instructions for Claude's behavior
- Real-world examples showing input prompts and expected outputs
- Attribution if the skill builds upon existing workflows

The template structure looks like this:

```markdown
---
name: my-awesome-skill
description: One-sentence description of what this skill does and when to use it.
---

# My Awesome Skill

Detailed description of the skill and what it helps users accomplish.

## When to Use This Skill

- Use case 1
- Use case 2
- Use case 3

## What This Skill Does

1. **Capability 1**: Description
2. **Capability 2**: Description

## How to Use

### Basic Usage

```

Simple example prompt

```

### Advanced Usage

```

More complex example prompt with options

```

## Example

**User**: "Generate a weekly sales report"

**Output**:

```

[Generated report content]

```

**Inspired by:** [Original author’s workflow]

```

### 3. Test Your Implementation

Before submitting, validate that your skill functions correctly across all supported platforms. The repository's best practices require testing on:

- **Claude.ai** (web interface)
- **Claude Code** (terminal application)
- **Skills API** (programmatic integration)

Run multiple test prompts from your [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) examples to ensure Claude interprets the instructions consistently across contexts.

### 4. Update the Central README

Add your skill to the main [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) in the appropriate category (e.g., *Development & Code Tools*, *Writing & Content*, *Data Analysis*). Entries must follow alphabetical order within categories and use the exact Markdown format specified in [`CONTRIBUTING.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/CONTRIBUTING.md).

The entry typically includes the skill name linked to its folder, followed by a brief description:

```markdown
- **[My Awesome Skill](./my-awesome-skill/)** – Generate automated reports from JSON data.

```

### 5. Submit a Pull Request

Follow the Git workflow defined in [`CONTRIBUTING.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/CONTRIBUTING.md):

```bash

# Fork the repository on GitHub, then clone your fork

git clone https://github.com/<your-username>/awesome-claude-skills.git
cd awesome-claude-skills

# Create a feature branch

git checkout -b add-my-awesome-skill

# Add your files

git add my-awesome-skill/ README.md

# Commit with a clear message

git commit -m "Add My Awesome Skill"

# Push and create PR

git push origin add-my-awesome-skill

```

Open a Pull Request against the main repository. The PR description should follow the template in [`CONTRIBUTING.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/CONTRIBUTING.md), including a summary of the skill's purpose, testing evidence, and confirmation that you've read the contribution guidelines.

## Quality Criteria and Review Process

Maintainers evaluate contributions against the criteria defined in the repository documentation. Your skill must demonstrate a **real use case** with practical applications, include **complete documentation** following the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) template, adhere to **safety guidelines** avoiding harmful automation, and maintain **portability** across Claude platforms.

Address reviewer feedback by pushing additional commits to your branch. Once approved, maintainers will merge your skill into the main branch, making it immediately available to the Claude community.

## Summary

- **Use lowercase hyphenated folder names** (e.g., `my-skill-name/`) for your contribution
- **Include mandatory YAML front-matter** in [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) with `name` and `description` fields
- **Test across three platforms**: Claude.ai, Claude Code, and the Skills API
- **Update [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md)** with an alphabetically sorted entry in the correct category
- **Follow the PR template** from [`CONTRIBUTING.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/CONTRIBUTING.md) when submitting your contribution

## Frequently Asked Questions

### What naming convention should I use for the skill folder?

Name your folder in all lowercase with hyphens separating words, such as `code-reviewer/` or `meeting-transcriber/`. This convention appears in the *Creating Skills* section of [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) and ensures consistency with existing skills in the repository.

### Is the YAML front-matter in SKILL.md required?

Yes, the YAML front-matter is mandatory. According to the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) template in [`CONTRIBUTING.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/CONTRIBUTING.md), you must include at minimum the `name` and `description` fields between triple dashes at the top of the file. Without this metadata, the skill cannot be properly indexed by automated tools.

### How do I handle optional scripts or templates?

Place helper files in appropriately named subdirectories within your skill folder. Use `scripts/` for executable code, `templates/` for document formats, and `resources/` for static assets like JSON files or images. Reference these files in your [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) instructions so Claude knows when to utilize them.

### Can I modify an existing skill instead of creating a new one?

Yes, improvements to existing skills are welcome. Submit changes as a pull request with a clear description of what you're fixing or enhancing. However, if your modification fundamentally changes the skill's purpose or adds entirely new capabilities, consider creating a separate skill folder to preserve the original functionality.