/comprehensive-public-repo-setup

name: comprehensive-public-repo-setup
description: "Create production-ready public repos with complete documentation, automated setup, bundled dependencies, and user-friendly installation."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [GitHub, Documentation, Setup Scripts, Open Source, Repository Management]
    related_skills: [github-repo-management, github-pr-workflow, writing-plans]
origin: original
source_repo: kevinnft/ai-agent-skills
source_url: https://github.com/kevinnft/ai-agent-skills
source_license: MIT
language: en

Comprehensive Public Repository Setup

Pattern for creating production-ready public repositories that others can clone and use immediately.

When to Use

Creating a public repo that needs:

• Comprehensive documentation
• Automated setup (one-command install)
• Bundled dependencies (no external failures)
• Templates and examples
• Troubleshooting guide
• Installation verification

Repository Structure

repo-name/
├── README.md (10-15KB, comprehensive)
├── setup.sh (automated installation)
├── LICENSE (MIT recommended)
├── CONTRIBUTING.md
├── TROUBLESHOOTING.md (20+ solutions)
├── CHECKLIST.md (20+ verification steps)
├── EXAMPLE.md (real-world workflow)
├── templates/
│   ├── template1.md
│   └── template2.md
└── bundled-dependencies/ (if applicable)
    └── external-tool/

README.md Structure

Essential sections (in order):

1. **Title + Tagline** — with badges 2. **What is This?** — 2-3 sentence overview 3. **Features** — bullet points with emojis 4. **Quick Start** — 5-minute install 5. **Manual Setup** — step-by-step 6. **Workflow Example** — real-world use case 7. **Architecture** — ASCII diagram 8. **Use Cases** — when to use this 9. **Advanced Features** — optional capabilities 10. **Performance** — comparison if applicable 11. **Contributing** — link to CONTRIBUTING.md 12. **License** — MIT recommended 13. **Credits** — acknowledgments

Example template:

# 🧠 Project Name

**One-line description highlighting key benefits.**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## 🎯 What is This?

Brief overview (2-3 sentences).

## ✨ Features

- ⚡ **Feature 1** — description
- 🧠 **Feature 2** — description

## 🚀 Quick Start

\`\`\`bash
git clone https://github.com/user/repo.git
cd repo
./setup.sh
\`\`\`

## 📖 Manual Setup

Step-by-step instructions...

setup.sh Pattern

Structure:

#!/bin/bash
set -e  # Exit on error

# Header
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "🎯 Project Setup"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""

# 1. Check prerequisites
echo "🔍 Checking prerequisites..."
if ! command -v tool &> /dev/null; then
    echo "❌ Tool not found. Installing..."
    # Install command
fi
echo "✅ Prerequisites OK"
echo ""

# 2. Get user input (interactive)
echo "📋 Configuration:"
read -p "Username: " USERNAME
read -sp "Token: " TOKEN
echo ""
echo ""

# 3. Install dependencies with fallback
echo "📦 Installing dependencies..."
if git clone --depth 1 https://github.com/external/dep.git 2>/dev/null; then
    echo "✅ Installed from GitHub (latest)"
else
    echo "⚠️  GitHub clone failed, using bundled copy..."
    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
    cp -r "$SCRIPT_DIR/bundled-dep" "$INSTALL_DIR/"
    echo "✅ Installed from bundle"
fi
echo ""

# 4. Configure
echo "⚙️ Configuring..."
# Configuration steps
echo "✅ Configuration complete"
echo ""

# 5. Summary
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "✅ SETUP COMPLETE!"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "📊 Summary:"
echo "   • Component 1: ✅"
echo "   • Component 2: ✅"
echo ""
echo "🎯 Next Steps:"
echo "   1. Step one"
echo "   2. Step two"
echo ""

**Key principles:**

• Use `set -e` (exit on error)
• Check prerequisites before proceeding
• Interactive prompts only for user-specific values
• Fallback logic for external dependencies
• Clear progress indicators (emojis + messages)
• Summary at end with next steps

Bundling External Dependencies

**Problem:** External repos can disappear, change, or be rate-limited.

**Solution:** Bundle critical dependencies with GitHub fallback.

**Pattern:**

# Try GitHub first (latest version)
if git clone --depth 1 https://github.com/external/tool.git 2>/dev/null; then
    echo "✅ Installed from GitHub (latest)"
else
    # Fallback: use bundled copy
    echo "⚠️  GitHub clone failed, using bundled copy..."
    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
    cp -r "$SCRIPT_DIR/bundled-tool" "$INSTALL_DIR/"
    echo "✅ Installed from bundle"
fi

**When to bundle:**

• Critical dependencies (setup fails without them)
• Small size (<1MB preferred, <5MB acceptable)
• Stable APIs (won't break with old version)
• External repos with uncertain longevity

**When NOT to bundle:**

• Large dependencies (>10MB)
• Frequently updated tools
• OS packages (use package manager)

TROUBLESHOOTING.md Structure

Sections:

1. **Installation Issues** — errors during setup 2. **Runtime Issues** — problems after installation 3. **Sync/Network Issues** — connectivity problems 4. **Performance Issues** — slow operations 5. **Security Issues** — token/permission problems 6. **Verification Checklist** — confirm installation

Format:

### **"Error message"**

**Problem:** Brief description.

**Solution:**
\`\`\`bash
# Fix command
\`\`\`

Aim for 20-30 solutions covering common issues.

CHECKLIST.md Pattern

Structure:

1. **Pre-installation** (5-10 checks) 2. **Post-installation** (10-15 verifications) 3. **Functional tests** (3-5 tests) 4. **Optional features** 5. **Success criteria**

Format:

### **1. Component Installed**

\`\`\`bash
command --version
# Expected: version x