Awesome Creator

Expert guidance for creating Awesome lists that comply with official sindresorhus/awesome standards. Awesome lists are curated collections of the best resources on specific topics, maintained by the community.

When to use this skill:

• Creating a new Awesome list from scratch
• Validating an existing Awesome list for compliance
• Updating an Awesome list with new entries
• Submitting an Awesome list to the official awesome repository
• Reviewing Awesome list pull requests

---

Quick Start: Create Your Awesome List in 5 Minutes

Follow these steps to create a compliant Awesome list:

Step 1: Set Up Your Repository (1 minute)

Repository name: awesome-topic (lowercase slug)

• ✅ awesome-rust-gui
• ✅ awesome-python-testing
• ❌ awesome-RustGUI
• ❌ AwesomePythonTesting

Required files:

awesome-topic/
├── README.md           # Your Awesome list
├── CONTRIBUTING.md     # Contribution guidelines
└── LICENSE             # CC0 license

Step 2: Create the Header (30 seconds)

# Awesome Topic

[![Awesome](https://awesome.re/badge.svg)](https://awesome.re)

> Brief description of what this list covers.

Key points:

• Title case in heading: # Awesome Topic
• Badge on right side or next to title
• Succinct, objective description
• No marketing language

Step 3: Add Table of Contents (1 minute)

## Contents

- [Category One](#category-one)
- [Category Two](#category-two)
- [Category Three](#category-three)

Requirements:

• Named "Contents" (not "Table of Contents")
• First section in README
• One level deep (no nested bullets)
• Exclude "Contributing" and "Footnotes"

Step 4: Add Your Entries (2 minutes)

## Category One

- [Project Name](https://github.com/user/project#readme) - Objective description.
- [Another Project](https://github.com/user/another#readme) - What it does.

Critical rules:

• All GitHub links end with #readme
• Descriptions start with uppercase
• Descriptions end with period
• No marketing words ("best", "amazing")
• Describe what it is, not how great it is

Step 5: Finalize (1 minute)

Add at the bottom:

## Contributing

Please see [contributing.md](contributing.md)

Create CONTRIBUTING.md and LICENSE files using the templates in templates/.

---

Awesome List Structure

Required Elements

Every Awesome list MUST include:

1. Awesome Badge

[![Awesome](https://awesome.re/badge.svg)](https://awesome.re)

• Placed on right side of heading or centered at top
• Links to https://awesome.re
• Use the flat version if preferred: badge-flat.svg

2. Succinct Description

A brief, objective description at the top:

✅ Good:

> Mobile operating system for Apple phones and tablets.
> Prototyping interactive UI designs.

❌ Bad:

> Resources and tools for iOS development.
> The best collection of awesome Framer packages.

3. Table of Contents

• Named exactly "Contents"
• First section after description
• Links to all major categories
• Excludes "Contributing" and "Footnotes"
• Preferably one level deep

4. Categorized Entries

Organize entries into logical categories:

## Networking

- [Alamofire](https://github.com/Alamofire/Alamofire#readme) - Elegant HTTP networking in Swift.

## UI Components

- [SnapKit](https://github.com/SnapKit/SnapKit#readme) - A Swift Autolayout DSL.

5. Contributing Section

## Contributing

Please see [contributing.md](contributing.md)

• Links to separate CONTRIBUTING.md file
• Placed at top or bottom of content
• NOT in Table of Contents

6. LICENSE File

• Must use Creative Commons license (CC0 recommended)
• Code licenses (MIT, Apache, GPL) are NOT acceptable
• File named LICENSE or license in repo root
• Do NOT include license text in README

Optional Elements

Project Logo

> Description

<img src="logo.png" alt="Logo" width="400">

## Contents

• High-DPI image (max half original width)
• Links to project website
• Centered or right-aligned

Footnotes Section

## Footnotes

- Some entries may be archived but historically significant.
- Last updated: January 2025

• For ancillary information
• NOT in Table of Contents
• Placed at very bottom

---

Entry Quality Guidelines

Curation Principles

Core Philosophy: Awesome lists are curations of the best, not collections of everything.

Only Include Awesome Items

✅ Include:

• Projects you personally recommend
• Well-maintained, active projects
• Projects with clear documentation
• High-quality resources

❌ Exclude:

• Unmaintained or archived repos
• Projects without documentation
• Deprecated tools
• Everything you can find (be selective!)

Objective Descriptions

Describe what the project is, not how great it is:

✅ Good:

- [RxSwift](https://github.com/ReactiveX/RxSwift#readme) - Reactive programming in Swift.
- [Alamofire](https://github.com/Alamofire/Alamofire#readme) - Elegant HTTP networking.

❌ Bad:

- [RxSwift](https://github.com/ReactiveX/RxSwift#readme) - The best reactive programming library.
- [Alamofire](https://github.com/Alamofire/Alamofire#readme) - An amazing networking framework.

Entry Format

Standard format for all entries:

- [Project Name](https://github.com/user/project#readme) - Description ends with period.

Rules:

• Link text = project name (title case)
• GitHub URLs end with #readme
• Description starts with uppercase
• Description ends with period
• Separate link and description with dash
• One space on each side of dash

Consistent Naming

Use correct, consistent names:

• ✅ Node.js, ❌ NodeJS, ❌ node.js
• ✅ iOS, ❌ ios, ❌ IOS
• ✅ Swift, ❌ swift
• ✅ macOS, ❌ MacOS, ❌ Mac OS

---

Advanced Features

Progressive Disclosure

For detailed templates, examples, and official guidelines, see:

Templates:

• templates/awesome-readme-template.md - Base README structure
• templates/contributing-template.md - CONTRIBUTING.md template
• templates/license-template.txt - Full CC0 license text

References:

• references/awesome-manifesto.md - Official Awesome manifesto and philosophy
• references/awesome-guidelines.md - Complete submission requirements
• references/examples.md - Annotated examples from popular lists

Validation

Before submitting your list:

1. Run awesome-lint:

   npx awesome-lint
   

2. Check requirements:

   • Repo name: awesome-topic (lowercase)
   • Title: # Awesome Topic (title case)
   • Awesome badge present
   • Table of Contents named "Contents"
   • All entries end with periods
   • All GitHub links include #readme
   • LICENSE file (CC0)
   • CONTRIBUTING.md exists
   • No marketing language
   • No CI badges
   • No hard-wrapping

3. Age requirement: List must be 30+ days old before submission

Common Pitfalls

Avoid these frequent mistakes:

❌ Marketing Language

- The best library for X
- An amazing tool
- Revolutionary framework

Use objective descriptions instead.

❌ Missing #readme

- [Project](https://github.com/user/project) - Description.

Include #readme in GitHub URLs.

❌ Wrong License

MIT License

Use CC0 or Creative Commons, not code licenses.

❌ Self-Referential

> Resources and tools for X development

Describe the topic itself, not the list.

❌ CI Badges

[![CI](https://github.com/user/workflow/badge.svg)](https://github.com/user/actions)

Don't include CI badges in Awesome lists.

❌ Hard-Wrapping

- [Project](https://github.com/user/project#readme) - This is a
  description that wraps to the next line.

Let lines flow naturally without hard wraps.

---

Progressive Disclosure

Quick Reference

For rapid validation, use the Quick Start section above.

Detailed Guidance

For comprehensive information, consult:

Templates:

• templates/awesome-readme-template.md - Full README template with structure
• templates/contributing-template.md - Complete CONTRIBUTING.md guide
• templates/license-template.txt - CC0 license full text

Reference Documentation:

• references/awesome-manifesto.md - Official Awesome manifesto
• references/awesome-guidelines.md - Complete PR submission guidelines
• references/examples.md - Annotated real-world examples

Official Resources

• Official Awesome Manifesto
• Create List Guide
• awesome.re - Official Awesome hub

---

Best Practices Summary

Content Quality

• Curate, don't collect
• Only include items you recommend
• Research before adding
• Remove unmaintained projects

Writing Style

• Be objective, not promotional
• Use consistent formatting
• Check spelling and grammar
• Keep descriptions concise

Technical Standards

• Use CC0 license
• Include CONTRIBUTING.md
• Add Awesome badge
• Name repo correctly
• Run awesome-lint

Community

• Accept constructive feedback
• Respect other opinions
• Review other PRs
• Contribute back

---

Remember: Awesome lists are curations of the best resources. Quality over quantity. When in doubt, leave it out.