# How Claude Skills Are Organized in the Awesome-Claude-Skills Repository

> Discover how Claude Skills are organized in the awesome-claude-skills repository. Learn about the flat-yet-categorized structure and efficient metadata streaming with SKILL.md files.

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

---

**The *awesome-claude-skills* repository uses a flat-but-categorized directory structure where every skill lives in its own folder containing a mandatory [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file with YAML front-matter, enabling Claude to stream metadata efficiently while keeping helper scripts and templates in optional sub-folders.**

The **ComposioHQ/awesome-claude-skills** repository provides a curated collection of reusable instructions that extend Claude's capabilities across document processing, development workflows, and app automation. Understanding how **Claude Skills are organized** is essential for contributors adding new capabilities and developers integrating existing skills into Claude Code or the Anthropic API.

## Root-Level Index and Category Structure

The repository's top-level [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) serves as the master index, listing skill categories including Document Processing, Development & Code Tools, Data & Analysis, and App Automation via Composio. Each category section in [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) maps directly to logical groupings in the directory structure, with explicit links to individual skill folders for immediate navigation.

## One-Folder-Per-Skill Architecture

Every skill resides in a dedicated directory directly under the repository root (or within logical category folders), using the skill's identifier as the directory name. This self-contained approach ensures that version control, documentation, and dependencies remain isolated per skill. Examples from the repository include:

- `canvas-design/`
- `slack-gif-creator/`
- `salesforce-automation/`
- `slack-automation/`

## Standard Skill Structure and SKILL.md Format

Each skill folder follows a mandatory file convention centered around [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md). This file contains YAML front-matter defining the skill's name and description, followed by the full instructional markdown body that Claude uses for execution.

The standard directory layout is:

```

skill-name/
├── SKILL.md          # Required – metadata + instructions

├── scripts/          # Optional – helper scripts

├── templates/        # Optional – document/templates

└── resources/        # Optional – reference files, assets

```

### Discovery Optimization via Front-Matter Loading

When Claude loads a skill, it first reads only the YAML front-matter (approximately 100 tokens) to determine relevance. The full markdown body, scripts, and resources stream on-demand, minimizing context window usage while maintaining rich functionality. This design is documented in the "What Are Claude Skills?" section of the root [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md).

## Logical Groupings and App Automation

Related skills are grouped into descriptive sub-directories for discoverability. The **App Automation via Composio** section, for instance, contains specific automation skills like `salesforce-automation/` and `slack-automation/`, with the README sections mapping exactly to these physical folder locations.

## Complete Plugin Packaging

The repository includes a reference implementation for full plugin distribution in `connect-apps-plugin/`, which contains [`plugin.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/plugin.json) and its own README. This demonstrates how to package multiple skills alongside configuration files for broader Claude plugin distribution, distinct from individual skill folders.

## Loading Skills into Claude Code and the API

Skills from this repository can be consumed locally through the Claude Code CLI or programmatically via the Anthropic API, following the same organizational conventions.

### Local Installation for Claude Code

To install a skill for local CLI usage:

```bash

# Create the local skills directory if it does not exist

mkdir -p ~/.config/claude-code/skills/

# Copy the desired skill folder (e.g., slack-gif-creator) into that directory

cp -r $HOME/github.com/ComposioHQ/awesome-claude-skills/slack-gif-creator \
      ~/.config/claude-code/skills/

# Verify the skill metadata (first 20 lines of SKILL.md)

head -20 ~/.config/claude-code/skills/slack-gif-creator/SKILL.md

```

### Programmatic Access via the Skills API

When using the Anthropic Python client, reference skills by their folder identifier:

```python
import anthropic

client = anthropic.Anthropic(api_key="YOUR_API_KEY")

# The skill-id is the folder name; the API expects the exact path or ID

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    skills=["slack-gif-creator"],
    messages=[{"role": "user", "content": "Create a celebration GIF for our Slack channel"}],
)
print(response.content[0].text)

```

The API automatically fetches the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) content (metadata and instructions) and any scripts needed for the skill to execute.

## Summary

- **Flat directory structure**: Each skill occupies one folder named after its identifier, enabling modular version control.
- **Required [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md)**: Every skill must include this file with YAML front-matter for efficient metadata discovery.
- **Optional sub-folders**: `scripts/`, `templates/`, and `resources/` directories hold auxiliary assets without cluttering the root skill definition.
- **Root categorization**: The [`README.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/README.md) provides categorized navigation that maps directly to physical folder locations.
- **Dual consumption paths**: Skills load into Claude Code via `~/.config/claude-code/skills/` or through the API using the folder name as the skill identifier.

## Frequently Asked Questions

### What is the purpose of the SKILL.md file?

The [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) file serves as the single source of truth for each skill, containing mandatory YAML front-matter (name, description) followed by the complete instructional markdown. Claude reads only the front-matter initially to assess relevance, then streams the full body on-demand to prevent context window overflow.

### How do optional sub-folders like scripts/ and templates/ function?

The `scripts/`, `templates/`, and `resources/` directories are optional containers for auxiliary files that support skill execution. For example, `canvas-design/` includes font assets and templates, while `slack-gif-creator/templates/` holds document templates. These remain separate from the core [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) definition to keep the instruction file clean and parseable.

### Can I use skills from this repository with the Claude API or only Claude Code?

You can use these skills with both Claude Code and the Anthropic API. For Claude Code, copy the skill folder to `~/.config/claude-code/skills/`. For the API, pass the folder name (e.g., `"slack-gif-creator"`) in the `skills` parameter of `client.messages.create()`, and the system will automatically retrieve the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/SKILL.md) content.

### What is the connect-apps-plugin directory?

The `connect-apps-plugin/` folder demonstrates how to package a complete Claude plugin rather than an individual skill. It contains [`plugin.json`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/plugin.json) and supporting documentation, showing how multiple skills can be bundled with configuration files for distribution as a unified plugin extension.