Skip to content

HOW_IT_WORKS.md

Latest commit

 

History

History
338 lines (250 loc) · 10.4 KB

HOW_IT_WORKS.md

File metadata and controls

338 lines (250 loc) · 10.4 KB

How Awesome Claude Code Works

This document provides technical details about the repository structure, automated systems, and processes that power Awesome Claude Code.

Repository Architecture

Core Files

  • THE_RESOURCES_TABLE.csv - The single source of truth for all resources
  • README.md - Generated automatically from the CSV and templates
  • templates/ - Contains templates for README generation
    • README.template.md - Main template structure
    • categories.yaml - Single source of truth for all categories
    • resource-overrides.yaml - Manual overrides for specific resources

Scripts Directory

The scripts/ directory contains all automation:

  • parse_issue_form.py - Parses GitHub issue form submissions
  • create_resource_pr.py - Creates PRs from approved submissions
  • generate_readme.py - Generates README from CSV data
  • validate_single_resource.py - Validates individual resources
  • validate_links.py - Bulk validation of all resources
  • badge_issue_notification.py - Creates notification issues on featured repos
  • quick_id.py - Generates unique resource IDs

GitHub Actions Workflows

Located in .github/workflows/:

  • validate-resource-submission.yml - Runs on issue creation/edit
  • approve-resource-submission.yml - Runs on maintainer commands
  • protect-labels.yml - Prevents unauthorized label changes
  • validate-links.yml - Scheduled validation of all resource links
  • Additional workflows for CI/CD and maintenance

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

Label Protection

All submission-related labels are protected from unauthorized changes. The protect-labels.yml workflow automatically reverts any label changes made by non-maintainers (users without OWNER, MEMBER, or COLLABORATOR permissions).

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)

CSV Structure

Field Description Required Auto-populated
ID Unique identifier Yes Yes
Display Name Resource name Yes No
Category Main category Yes No
Sub-Category Optional subcategory No No
Primary Link Main URL Yes No
Secondary Link Additional URL No No
Author Name Creator name Yes No
Author Link Creator profile Yes No
Active TRUE/FALSE status Yes Yes (via validation)
Date Added Addition date No Yes
Last Modified GitHub last commit No Yes (from API)
Last Checked Validation timestamp Yes Yes
License SPDX identifier Recommended Yes (from GitHub)
Description Brief description Yes No

README Generation

The README is generated from templates using:

# templates/categories.yaml
categories:
  - id: workflows
    name: "Workflows & Knowledge Guides"
    prefix: wf
    icon: "🧠"
    order: 1
    
  - id: statusline
    name: "Status Lines"
    prefix: status
    icon: "📊"
    order: 3

Generation process:

  1. Load CSV data
  2. Apply any overrides from resource-overrides.yaml
  3. Group by category/subcategory
  4. Format using templates
  5. Write final README

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.)
  • API Endpoint: https://github-readme-stats-plus-theta.vercel.app/api/pin/?repo=REPO&username=USER&all_stats=true&stats_only=true

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>

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

Validation System

Link Validation

  • Checks HTTP status (200-299 = valid)
  • Handles redirects
  • Respects rate limits
  • Caches results for efficiency

GitHub-Specific Features

For GitHub links:

  • Fetches repository metadata
  • Extracts license information
  • Gets last commit date
  • Checks if repository exists/is public

Override System

The templates/resource-overrides.yaml allows:

  • Locking specific fields from updates
  • Skipping validation for special cases
  • Manual corrections to auto-detected data

Security Considerations

  1. Input Validation - All user input is sanitized
  2. URL Validation - Only HTTPS URLs accepted
  3. GitHub Token Scoping - Minimal permissions required
  4. Review Process - Human review before code changes
  5. Automated Checks - No direct CSV manipulation by users

Environment Variables

  • GITHUB_TOKEN - For API access (provided by Actions)
  • AWESOME_CC_PAT_PUBLIC_REPO - For creating notification issues
  • CREATE_ISSUES - Enable/disable notification system

Local Development

To test locally:

# Install dependencies
pip install -r requirements.txt

# Test validation
python scripts/validate_single_resource.py "https://example.com"

# Generate README
python scripts/generate_readme.py

# Parse a test issue
ISSUE_BODY="..." python scripts/parse_issue_form.py --validate

Maintenance Tasks

Regular Tasks

  • Monitor validation failures
  • Update templates as needed
  • Review and merge PRs
  • Handle edge cases with overrides

Bulk Operations

# Validate all links
make validate

# Sort resources
make sort

# Regenerate README
make generate

Contributing to the System

To improve the automation:

  1. Test changes locally first
  2. Update relevant documentation
  3. Consider backward compatibility
  4. Add tests if applicable
  5. Submit PR with clear description

For questions about the technical implementation, please open an issue with the "enhancement" label.