How Awesome Claude Code Works

How Awesome Claude Code Works

This document provides assorted technical details about the repository structure, automated systems, and processes that power Awesome Claude Code. It's mostly superceded by README-GENERATION, but, for one reason or another, it's still here, for now.

GitHub Labels

The submission system uses several labels to track issue state:

Resource Submission Labels

• resource-submission - Applied automatically to issues created via the submission form
• validation-passed - Applied when submission passes all validation checks
• validation-failed - Applied when submission fails validation
• approved - Applied when maintainer approves submission with /approve
• pr-created - Applied after PR is successfully created
• error-creating-pr - Applied if PR creation fails
• rejected - Applied when maintainer rejects with /reject
• changes-requested - Applied when maintainer requests changes with /request-changes

Other Labels

• broken-links - Applied by scheduled link validation when resources become unavailable
• automated - Applied alongside broken-links to indicate automated detection
• do-not-disturb - Apply to a resource PR before merging to skip the badge notification to the resource author's repository

Label State Transitions

1. New submission → resource-submission
2. After validation → adds validation-passed OR validation-failed
3. If changes requested → adds changes-requested
4. When user edits and validation passes → removes changes-requested
5. On approval → adds approved + pr-created (or error-creating-pr)
6. On rejection → adds rejected

The Submission Flow

1. User Submits Issue

When a user submits a resource via the issue form:

# .github/ISSUE_TEMPLATE/submit-resource.yml
- Structured form with all required fields
- Auto-labels with "resource-submission"
- Validates input formats

2. Automated Validation

The validation workflow triggers immediately:

# Simplified validation flow
1. Parse issue body → extract form data
2. Validate required fields
3. Check URL accessibility
4. Verify no duplicates exist
5. Post results as comment
6. Update issue labels

Validation includes:

• URL validation (200 OK response)
• License detection from GitHub API
• Duplicate checking against existing CSV
• Field format validation

3. Maintainer Review

Once validation passes, maintainers can:

• /approve - Triggers PR creation
• /request-changes [reason] - Asks for modifications
• /reject [reason] - Closes the submission

Notification System:

• When changes are requested, the maintainer is @-mentioned in the comment
• When the user edits their issue, the maintainer receives a notification if:
  • It's the first edit after requesting changes
  • The validation status changes (pass→fail or fail→pass)
• Multiple rapid edits won't spam the maintainer with notifications

4. Automated PR Creation

Upon approval:

1. Checkout fresh main branch
2. Create unique branch: add-resource/category/name-timestamp
3. Add resource to CSV with generated ID
4. Run generate_readme.py
5. Commit changes
6. Push branch
7. Create PR via GitHub CLI
8. Link back to original issue
9. Close submission issue

5. Final Steps

• Maintainer merges PR
• Badge notification system runs (if enabled)
• Submitter receives GitHub notifications

Resource ID Generation

IDs follow the format: {prefix}-{hash}

prefixes = {
    "Agent Skills": "skill",
    "Slash-Commands": "cmd",
    "Workflows & Knowledge Guides": "wf",
    "Tooling": "tool",
    "CLAUDE.md Files": "claude",
    "Hooks": "hook",
    "Official Documentation": "doc",
}

# Hash is first 8 chars of SHA256(display_name + primary_link)

Collapsible Sections

The generated README uses HTML <details> elements for improved navigation:

• Categories without subcategories: Wrapped in <details open> (fully collapsible)
• Categories with subcategories: Regular headers (subcategories are collapsible)
• All subcategories: Wrapped in <details open> elements
• Table of Contents: Collapsible with nested sections for categories with subcategories
• All collapsible sections are open by default for easy browsing

Design Note: Initially attempted to make all categories collapsible with nested subcategories, but this caused anchor link navigation issues - links from the Table of Contents couldn't reach subcategories when their parent category was collapsed. The current design balances navigation functionality with collapsibility.

GitHub Stats Integration

Each GitHub resource in the README automatically includes a collapsible statistics section:

• Automatic Detection: The parse_github_url function from validate_links.py identifies GitHub repositories
• Stats Display: Uses the GitHub Stats API to generate an SVG badge with repository metrics
• Collapsible Design: Stats are hidden by default in a <details> element to keep the main list clean
• Universal Support: Works with all GitHub URL formats (repository root, blob URLs, tree URLs, etc.)

Example output for a GitHub resource:

[`resource-name`](https://github.com/owner/repo)
Description of the resource

<details>
<summary>📊 GitHub Stats</summary>
<br>

![GitHub Stats for repo](https://github-readme-stats-plus-theta.vercel.app/api/pin/?repo=repo&username=owner&all_stats=true&stats_only=true)

</details>

Alternative README Views

The repository offers multiple README styles to suit different preferences, all generated from the same CSV source of truth.

Style Options

Users can switch between four presentation styles via navigation badges at the top of each page:

File Structure

Alternative views are in the README_ALTERNATIVES/ folder to keep the root clean:

README.md                                      # Root README (root_style)
README_ALTERNATIVES/
├── README_EXTRA.md                            # Extra visual view
├── README_CLASSIC.md                          # Classic markdown view
├── README_AWESOME.md                          # Awesome list view
├── README_FLAT_ALL_AZ.md                      # Flat: All resources, A-Z
├── README_FLAT_ALL_UPDATED.md                 # Flat: All resources, by updated
├── README_FLAT_ALL_CREATED.md                 # Flat: All resources, by created
├── README_FLAT_ALL_RELEASES.md                # Flat: All resources, recent releases
├── README_FLAT_TOOLING_AZ.md                  # Flat: Tooling only, A-Z
├── README_FLAT_HOOKS_UPDATED.md               # Flat: Hooks only, by updated
└── ... (44 flat views total: 11 categories × 4 sort types)

Flat List System

The flat view provides a searchable table with dual navigation:

Sort Options

• A-Z - Alphabetical by resource name
• Updated - By last modified date (most recent first)
• Created - By repository creation date (newest first)
• Releases - Resources with releases in past 30 days

Category Filters

• All - All 164+ resources
• Tooling, Commands, CLAUDE.md, Workflows, Hooks, Skills, Styles, Status, Docs, Clients

Table Format

Resources are displayed with stacked name/author format to maximize description space:

| Resource | Category | Sub-Category | Description |
|----------|----------|--------------|-------------|
| [**Resource Name**](link)<br>by [Author](link) | Category | Sub-Cat | Full description... |

Release Detection

The "Releases" sort option shows resources with published releases in the past 30 days. Release information is fetched from GitHub Releases only.

Generator Architecture

The generate_readme.py script uses generator classes under scripts/readme/generators/:

ReadmeGenerator (ABC)
├── VisualReadmeGenerator            # README_ALTERNATIVES/README_EXTRA.md
├── MinimalReadmeGenerator           # README_ALTERNATIVES/README_CLASSIC.md
├── AwesomeReadmeGenerator           # README_ALTERNATIVES/README_AWESOME.md
└── ParameterizedFlatListGenerator   # README_ALTERNATIVES/README_FLAT_*.md

The ParameterizedFlatListGenerator takes category_slug and sort_type parameters, enabling generation of all 44 combinations from a single class. The configured root_style is additionally generated as README.md.

Navigation Badges

SVG badges are generated dynamically in assets/:

• badge-style-*.svg - Style selector (Extra, Classic, Awesome, Flat)
• badge-sort-*.svg - Sort options (A-Z, Updated, Created, Releases)
• badge-cat-*.svg - Category filters (All, Tooling, Hooks, etc.)

Current selections are highlighted with colored borders matching each badge's theme color.

Adding/Removing Flat List Categories

To add a new category filter to flat list views:

1. Update FLAT_CATEGORIES in scripts/readme/generators/flat.py:

   FLAT_CATEGORIES = {
       # ... existing categories ...
       "new-category": ("CSV Category Value", "Display Name", "#hexcolor"),
   }
   

   • First value: Exact match for the Category column in CSV (or None for "all")
   • Second value: Display name shown on badge
   • Third value: Hex color for badge accent and selection border

2. Regenerate READMEs: Run python scripts/readme/generate_readme.py

   • Creates new files: README_ALTERNATIVES/README_FLAT_NEWCATEGORY_*.md
   • Generates badge: assets/badge-cat-new-category.svg
   • Updates navigation in all 44+ flat views

To remove a category: Delete its entry from FLAT_CATEGORIES and run the generator. Manually delete the orphaned .md files from README_ALTERNATIVES/.

Adding/Removing Sort Types

To add a new sort option:

1. Update FLAT_SORT_TYPES in scripts/readme/generators/flat.py:

   FLAT_SORT_TYPES = {
       # ... existing sorts ...
       "newsort": ("DISPLAY", "#hexcolor", "description for status text"),
   }
   

2. Implement sorting logic in ParameterizedFlatListGenerator.sort_resources():

   elif self.sort_type == "newsort":
       # Custom sorting logic
       return sorted(resources, key=lambda x: ...)
   

3. Regenerate READMEs: Creates new views for all categories × new sort type.

Adding/Removing README Styles

The main README styles are defined as generator classes:

The configured root_style is additionally written to README.md.

To add a new README style:

1. Create a generator class extending ReadmeGenerator under scripts/readme/generators/:

   class NewStyleReadmeGenerator(ReadmeGenerator):
       @property
       def template_filename(self) -> str:
           return "README_NEWSTYLE.template.md"
   
       @property
       def output_filename(self) -> str:
           return "README_ALTERNATIVES/README_NEWSTYLE.md"
   
       # Implement abstract methods...
   

2. Create template in templates/README_NEWSTYLE.template.md (include {{STYLE_SELECTOR}}).

3. Register the generator in STYLE_GENERATORS inside scripts/readme/generate_readme.py.

4. Create style badge assets/badge-style-newstyle.svg.

5. Update config in acc-config.yaml:

   • add a new entry under styles:
   • append the style ID to style_order:

To remove a style: Delete the generator class, template, badge asset, and config entry, then remove the style from STYLE_GENERATORS and style_order.

Announcements System

Announcements are stored in templates/announcements.yaml:

• YAML format for structured data
• Renders as nested collapsible sections
• Each date group is collapsible
• Individual items can be simple text or collapsible with summary/text
• Falls back to .md file if YAML doesn't exist