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

To contribute a new Claude Skill, create a lowercase-hyphenated folder containing a SKILL.md file with YAML front-matter, test the skill across Claude.ai and Claude Code, update the central 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 Creating Skills section, the repository expects a specific layout that separates skill instructions from optional helper assets.

A standard skill folder follows this structure:

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 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 file must contain YAML front-matter followed by structured documentation. As specified in 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:

---
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 examples to ensure Claude interprets the instructions consistently across contexts.

4. Update the Central README

Add your skill to the 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.

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

- **[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:

# 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, 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 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 with name and description fields
• Test across three platforms: Claude.ai, Claude Code, and the Skills API
• Update README.md with an alphabetically sorted entry in the correct category
• Follow the PR template from 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 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 template in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}