Add comprehensive metrics tracking system

[mattpodwysocki]

Summary

Adds automated tracking for GitHub traffic and skills.sh adoption metrics in a single unified report.

Features

Data Sources

• ✅ GitHub Traffic - Views, clones, referrers, popular paths (14-day history)
• ✅ Repository Stats - Stars, forks, watchers, open issues
• ✅ Skills.sh Metrics - Install counts (scraped from search results, ready when published)

Output Formats

• Markdown () - Human-readable reports with tables
• JSON () - Machine-readable for dashboards/analysis
• CSV () - Spreadsheet-compatible for charting

Automation

• GitHub Actions - Runs daily at 2 AM UTC, uploads artifacts (90-day retention)
• Manual Execution - npm run metrics, npm run metrics:json, npm run metrics:csv
• Local Scheduling - Can be added to cron for local tracking

Components

scripts/generate-metrics-report.js  - Main metrics generator
.github/workflows/metrics.yml       - Daily automation workflow  
metrics/README.md                   - Documentation & usage guide

Usage

Generate Reports Locally

npm run metrics          # Markdown report
npm run metrics:json     # JSON format
npm run metrics:csv      # CSV format

Reports generated in metrics/ directory:

• metrics-YYYY-MM-DD.md - Timestamped
• metrics-latest.md - Most recent

Access Historical Data

1. Go to Actions
2. Click any workflow run
3. Download metrics-* artifact

Example Output

# Mapbox Agent Skills - Metrics Report

**Generated:** February 18, 2026

## Repository Stats
- ⭐ **Stars:** 10
- 🍴 **Forks:** 0
- 👀 **Watchers:** 1

## Traffic (Last 14 Days)
- **Total Views:** 824
- **Unique Visitors:** 181
- **Total Clones:** 2,295
- **Unique Cloners:** 605

## Top Referrers
1. **Google** - 107 views (48 unique)
2. **github.com** - 63 views (28 unique)
...

Skills.sh Integration

The script includes web scraping logic to extract mapbox skill install counts from skills.sh search results. When mapbox skills are published to skills.sh, they will automatically appear in the metrics reports.

Current status: No mapbox skills found on skills.sh (ready to track once published)

Long-term Tracking Options

Since metrics aren't committed to the repo:

• Download workflow artifacts periodically
• Create separate data repository
• Upload to cloud storage (S3, GCS)
• Send to analytics platform (DataDog, CloudWatch)

See metrics/README.md for detailed tracking strategies.

Testing

✅ Tested locally - generates all three report formats
✅ GitHub API integration working
✅ Skills.sh scraper ready (will activate when skills published)
✅ All CI checks passing

---

Addresses: Request to track GitHub traffic and skills.sh downloads in a single report for monitoring adoption over time.

🤖 Generated with Claude Code

[mattpodwysocki]

Fixed: Skills.sh Scraper Now Working! 🎉

You were absolutely right - the mapbox skills ARE published on skills.sh! The initial scraper wasn't finding them because skills.sh loads search results dynamically via JavaScript, so simple HTML fetching doesn't work.

Solution

Switched from HTML scraping to using the skills.sh API:

https://skills.sh/api/search?q=mapbox

Current Metrics

✅ 16 unique mapbox skills found
✅ 833 total installs across all skills

Skill	Installs
mapbox-web-performance-patterns	108
mapbox-style-patterns	99
mapbox-web-integration-patterns	97
mapbox-cartography	71
mapbox-style-quality	66
mapbox-token-security	58
mapbox-integration-patterns	55
mapbox-search-integration	50
mapbox-android-patterns	38
mapbox-google-maps-migration	34
mapbox-ios-patterns	34
mapbox-maplibre-migration	32
mapbox-search-patterns	31
mapbox-store-locator-patterns	29
mapbox-geospatial-operations	29
mapbox-automation	2

The metrics report now accurately tracks both GitHub traffic AND skills.sh adoption data in a single unified report!