# GitHub Catalogue Skill
Automatically inventory, categorize, and document GitHub repositories with intelligent analysis and organized reporting.
## Purpose
This skill enables AI agents to:
1. **Inventory** all repositories from a GitHub account
2. **Categorize** repos by type, language, and purpose
3. **Analyze** commit activity, staleness, and importance
4. **Generate** organized reports (Markdown, CSV, JSON)
5. **Export** to cloud storage (Google Drive, iCloud, etc.)
## Trigger Conditions
Invoke this skill when user asks:
- "Catalogue my GitHub repos"
- "Inventory my repositories"
- "Analyze my GitHub account"
- "Create a report of all my repos"
- "Organize my GitHub projects"
## Execution Flow
```
User Intent
↓
[1] Fetch all repos via GitHub API
↓
[2] Categorize (AI/Skill, App, Tool, Library, etc.)
↓
[3] Analyze (activity, size, language, staleness)
↓
[4] Generate reports (Markdown + CSV + JSON)
↓
[5] Optional: Upload to cloud storage
↓
Return organized catalogue to user
```
## Tool Requirements
| Tool | Purpose |
|------|---------|
| `gh` CLI | List repositories, get metadata |
| `curl`/`gh api` | Fetch detailed repo data |
| `jq` | Parse JSON responses |
| `python3` | Generate reports, analysis |
| `rclone` | Upload to cloud storage (optional) |
## Command Reference
### List All Repositories
```bash
gh repo list {OWNER} --limit {MAX} --json "name,description,url,createdAt,pushedAt,primaryLanguage,stargazersCount,forkCount,isPrivate,topics"
```
### Get Repo Details
```bash
gh api repos/{OWNER}/{REPO} --jq '{...}'
```
### Get Recent Commits (activity)
```bash
gh api repos/{OWNER}/{REPO}/commits?per_page=1 --jq '.[0].commit.committer.date'
```
## Categorization Rules
Auto-detect category based on name/content:
| Pattern | Category |
|---------|----------|
| `-skill`, `skill-` | AI Agent Skill |
| `ai-`, `-ai` | AI/ML Project |
| `app-`, `-app`, `mobile` | Application |
| `api-`, `-api`, `backend` | Backend/API |
| `lib-`, `-lib`, `sdk` | Library/Framework |
| `tool-`, `-tool`, `cli` | Developer Tool |
| `web-`, `-web`, `site` | Website |
| `demo`, `example`, `template` | Template/Demo |
| `infra`, `deploy`, `terraform` | Infrastructure |
| `doc`, `guide`, `wiki` | Documentation |
## Report Templates
### Markdown Report Structure
```markdown
# GitHub Repository Catalogue
**Account:** {OWNER}
**Generated:** {DATE}
**Total Repos:** {COUNT}
## Summary Statistics
| Category | Count | % of Total |
|----------|-------|------------|
...
## Repository Details
### Category: {CATEGORY}
| Repo | Description | Stars | Language | Updated |
|------|-------------|-------|----------|---------|
...
## Activity Analysis
- Active (last 30 days): X repos
- Stale (6+ months): Y repos
- Archived: Z repos
```
## Python Report Generator
```python
#!/usr/bin/env python3
"""GitHub Catalogue Report Generator"""
import json
import csv
from datetime import datetime
from pathlib import Path
def categorize_repo(name, description, topics):
"""Auto-categorize repo based on signals."""
name_lower = name.lower()
desc_lower = (description or "").lower()
if "skill" in name_lower or "ai-" in name_lower:
return "AI Agent Skill"
elif any(t in name_lower for t in ["app", "mobile", "react", "vue"]):
return "Application"
elif any(t in name_lower for t in ["api", "backend", "service"]):
return "Backend/API"
elif any(t in name_lower for t in ["lib", "sdk", "framework"]):
return "Library/Framework"
elif any(t in name_lower for t in ["tool", "cli", "script"]):
return "Developer Tool"
elif any(t in name_lower for t in ["website", "web", "landing"]):
return "Website"
elif any(t in name_lower for t in ["infrastructure", "terraform", "deploy"]):
return "Infrastructure"
else:
return "Project/Other"
def calculate_staleness(last_push):
"""Calculate staleness in days."""
if not last_push:
return 999
last_date = datetime.fromisoformat(last_push.replace('Z', '+00:00'))
return (datetime.now().astimezone() - last_date).days
def generate_markdown_report(repos, output_path, owner):
"""Generate organized Markdown report."""
# Categorize
categorized = {}
for repo in repos:
cat = categorize_repo(repo['name'], repo.get('description'), repo.get('topics', []))
categorized.setdefault(cat, []).append(repo)
# Build report
report = f"""# GitHub Repository Catalogue
**Owner:** {owner}
**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M')}
**Total Repositories:** {len(repos)}
## Summary Statistics
| Category | Count | % |
|----------|-------|---|
"""
for cat, items in sorted(categorized.items(), key=lambda x: -len(x[1])):
pct = len(items) / len(repos) * 100
report += f"| {cat} | {len(items)} | {pct:.1f}% |\n"
report += f"""
## Activity Overview
| Status | Count | Description |
|--------|-------|-------------|
| Active (< 30 days) | {sum(1 for r in repos if calculate_staleness(r.get('pushedAt')) < 30)} | Recent activity |
| Stale (30-90 days) | {sum(1 for r in repos if 30 <= calculate_staleness(r.get('pushedAt')) < 90)} | Needs attention |
| Dormant (90+ days) | {sum(1 for r in repos if calculate_staleness(r.get('pushedAt')) >= 90)} | Archive candidate |
## Repositories by Category
"""
for cat, items in sorted(categorized.items(), key=lambda x: -len(x[1])):
report += f"### {cat} ({len(items)})\n\n"
report += "| Repository | Description | Language | Stars | Updated |\n"
report += "|------------|-------------|----------|-------|---------|\n"
for repo in sorted(items, key=lambda x: x.get('stargazersCount', 0), reverse=True):
desc = (repo.get('description') or "")[:40] + "..." if len(repo.get('description') or "") > 43 else (repo.get('description') or "-")
lang = repo.get('primaryLanguage', {}).get('name', '-')
stars = repo.get('stargazersCount', 0)
updated = repo.get('pushedAt', '-')[:10]
report += f"| [{repo['name']}]({repo['url']}) | {desc} | {lang} | {stars} | {updated} |\n"
report += "\n"
with open(output_path, 'w') as f:
f.write(report)
return output_path
def generate_csv(repos, output_path):
"""Generate CSV for spreadsheet import."""
with open(output_path, 'w', newline='') as f:
writer = csv.writer(f)
writer.writerow(['Name', 'Category', 'Description', 'URL', 'Language',
'Stars', 'Forks', 'Created', 'Last Push', 'Is Private'])
for repo in repos:
writer.writerow([
repo['name'],
categorize_repo(repo['name'], repo.get('description'), repo.get('topics', [])),
repo.get('description', ''),
repo['url'],
repo.get('primaryLanguage', {}).get('name', ''),
repo.get('stargazersCount', 0),
repo.get('forkCount', 0),
repo.get('createdAt', '')[:10],
repo.get('pushedAt', '')[:10],
repo.get('isPrivate', False)
])
return output_path
def generate_json(repos, output_path, owner):
"""Generate JSON with full metadata."""
data = {
'generated_at': datetime.now().isoformat(),
'owner': owner,
'total_repos': len(repos),
'repositories': [
{
**repo,
'category': categorize_repo(repo['name'], repo.get('description'), repo.get('topics', [])),
'staleness_days': calculate_staleness(repo.get('pushedAt'))
}
for repo in repos
]
}
with open(output_path, 'w') as f:
json.dump(data, f, indent=2)
return output_path
```
## Execution Script
```python
#!/usr/bin/env python3
"""GitHub Catalogue - Main execution"""
import subprocess
import json
import sys
from pathlib import Path
from datetime import datetime
REPORT_GENERATOR = '''
{Paste the Python report generator code here}
'''
def main():
owner = sys.argv[1] if len(sys.argv) > 1 else input("GitHub username: ")
output_dir = Path(sys.argv[2]) if len(sys.argv) > 2 else Path.home() / "Desktop"
# Fetch repos
print(f"Fetching repositories for {owner}...")
result = subprocess.run(
['gh', 'repo', 'list', owner, '--limit', '1000',
'--json', 'name,description,url,createdAt,pushedAt,primaryLanguage,stargazersCount,forkCount,isPrivate,topics'],
capture_output=True, text=True
)
if result.returncode != 0:
print(f"Error: {result.stderr}")
return
repos = json.loads(result.stdout)
print(f"Found {len(repos)} repositories")
# Generate reports
timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
md_path = output_dir / f"{owner}_github_catalogue_{timestamp}.md"
csv_path = output_dir / f"{owner}_github_catalogue_{timestamp}.csv"
json_path = output_dir / f"{owner}_github_catalogue_{timestamp}.json"
# Save report generator
generator_path = output_dir / f"report_generator_{timestamp}.py"
with open(generator_path, 'w') as f:
f.write(REPORT_GENERATOR)
# Run generation
print("Generating reports...")
exec(compile(REPORT_GENERATOR, '<string>', 'exec'))
generate_markdown_report(repos, md_path, owner)
generate_csv(repos, csv_path)
generate_json(repos, json_path, owner)
print(f"\nReports generated:")
print(f" Markdown: {md_path}")
print(f" CSV: {csv_path}")
print(f" JSON: {json_path}")
# Upload to Google Drive if available
if (Path.home() / 'Library/CloudStorage/GoogleDrive-*').exists():
print("\nUploading to Google Drive...")
for f in [md_path, csv_path, json_path]:
subprocess.run(['cp', str(f), str(Path.home() / 'Desktop')])
print("Copied to Desktop for cloud sync")
if __name__ == '__main__':
main()
```
## Cloud Storage Integration
### Google Drive (macOS)
```bash
# Destination path
"$HOME/Library/CloudStorage/GoogleDrive-{EMAIL}/My Drive/GitHub Catalogue/"
```
### iCloud
```bash
"$HOME/Library/Mobile Documents/com~apple~CloudDocs/GitHub Catalogue/"
```
## Output Files
| File | Format | Purpose |
|------|--------|---------|
| `{USER}_github_catalogue_{DATE}.md` | Markdown | Human-readable report |
| `{USER}_github_catalogue_{DATE}.csv` | CSV | Spreadsheet/analysis |
| `{USER}_github_catalogue_{DATE}.json` | JSON | Machine-readable data |
| `report_generator_{DATE}.py` | Python | Reusable script |
## Usage Examples
### Basic Usage
```
@github-catalogue-skill
Catalogue my GitHub repos
```
### With Custom Output
```
@github-catalogue-skill
Inventory repos for user "acmecorp" and save to ~/projects/analysis/
```
### Include Archived/Private
```
@github-catalogue-skill
Full catalogue including private and archived repos
```
## CLI Command
Once skill is installed, run via:
```bash
# Interactive
python3 ~/.hermes/skills/github-catalogue/github_catalogue.py
# With args
python3 ~/.hermes/skills/github-catalogue/github_catalogue.py diamitani ~/Desktop
```
## Extension Points
1. **Custom categorization rules** - Add patterns to `categorize_repo()`
2. **Additional analytics** - Code complexity, dependency analysis
3. **Visualization** - Generate graphs/charts (PNG/SVG)
4. **Comparisons** - Track catalogue changes over time
5. **Auto-archival** - Suggest repos to archive based on staleness
## Validation
Verify report completeness:
- [ ] All repos accounted for (compare with `gh repo list --limit 9999 | wc -l`)
- [ ] Categories sum to total
- [ ] Dates parsed correctly (ISO 8601)
- [ ] Links are clickable in Markdown
- [ ] CSV opens correctly in spreadsheet
## Metadata
```json
{
"skill_version": "1.0.0",
"requires_auth": true,
"language": "python",
"external_deps": ["gh CLI", "jq"],
"output_formats": ["markdown", "csv", "json"],
"estimated_runtime": "30-60s per 100 repos"
}
```
Github Catalogue Skill
LLM-agnostic data engineering and analytics skill that instructs any AI model (Claude, GPT-4o, Gemini, Cursor) to work with Automatically inventory GitHub repositories, categorize…
Datav1.0.0UniversalFreeAgent Skills spec