public-repo-creation skill

Public Repository Creation

Create production-ready public GitHub repositories with comprehensive documentation, automated setup scripts, templates, and quality assurance processes.

When to Use

• Creating new open-source projects
• Publishing tools, libraries, or frameworks
• Building educational resources or examples
• Sharing integrations or automation scripts
• Any public-facing repository that needs professional polish

Core Components

1. Documentation Files (Required)

README.md (comprehensive):

• Clear title with emoji
• Badges (license, stars, build status)
• "What is This?" section
• Features (with subsections)
• Quick start (5-10 minutes)
• Manual setup (step-by-step)
• Example workflows
• Architecture diagram (ASCII or image)
• Folder structure
• Use cases
• Advanced features
• Performance metrics (if applicable)

LICENSE (required):

• MIT recommended for maximum adoption
• Include copyright year and author

CONTRIBUTING.md:

• Quick start for contributors
• Code style guidelines
• Commit message format
• PR process
• Bug report template
• Feature request template

TROUBLESHOOTING.md:

• Installation issues (5+ solutions)
• Runtime issues (4+ solutions)
• Common errors with fixes
• Verification checklist

CHECKLIST.md (optional but recommended):

• Pre-installation checks
• Post-installation verification (10+ steps)
• Functional tests
• Success criteria

2. Automated Setup Script

setup.sh (or equivalent):

• Shebang (#!/bin/bash)
• Error handling (set -e)
• Prerequisites check
• Interactive prompts (with defaults)
• Conditional logic (skip if already installed)
• Fallback mechanisms
• Progress indicators
• Summary output
• Comments for each section

Critical Patterns:

# Prevent duplicate entries in config files
if ! grep -q "PATTERN" ~/.config 2>/dev/null; then
    echo "NEW_LINE" >> ~/.config
else
    sed -i "s|OLD_PATTERN|NEW_PATTERN|" ~/.config
fi

# Variable expansion in heredocs
cat > file.txt << EOF  # NO quotes for expansion
date: $(date +%Y-%m-%d)
EOF

# Fallback mechanism
if command_from_internet; then
    echo "✅ Installed from source"
else
    echo "⚠️  Source failed, using bundled copy..."
    cp -r bundled/ destination/
fi

3. Templates

templates/ directory:

• Getting started template
• Daily/project note templates (if applicable)
• Configuration file templates
• .gitignore template

4. Examples

EXAMPLE.md or examples/ directory:

• Real-world use case
• Step-by-step breakdown
• Code examples with syntax highlighting
• Expected output
• Benefits explanation

5. Quality Assurance

Pre-commit checks:

# Syntax validation
bash -n setup.sh

# Link validation
grep -o '\[.*\](.*\.md)' *.md | while read link; do
    file=$(echo "$link" | sed 's/.*(\\(.*\\))/\\1/')
    [ -f "$file" ] && echo "✅ $link" || echo "❌ Broken: $link"
done

# TODO/FIXME check
grep -ri "TODO\|FIXME\|XXX\|HACK" . --include="*.md" --include="*.sh"

# File permissions
ls -la setup.sh  # Should be executable

AUDIT.md (optional but professional):

• File inventory
• Quality checks performed
• Security analysis
• Performance metrics
• Recommendations

Workflow

Phase 1: Planning (5 minutes)

1. Define repository purpose (one sentence)
2. Identify target audience
3. List core features (3-5 main features)
4. Choose license (MIT recommended)
5. Plan folder structure

Phase 2: Core Setup (15 minutes)

1. Create GitHub repo (public)
2. Clone locally
3. Create README.md with title, description, badges
4. Create LICENSE file
5. Create .gitignore
6. Initial commit + push

Phase 3: Documentation (30 minutes)

1. Expand README.md:

• Features section
• Quick start
• Manual setup
• Examples
• Architecture

1. Create CONTRIBUTING.md
2. Create TROUBLESHOOTING.md
3. Create EXAMPLE.md

Phase 4: Automation (30 minutes)

1. Create setup.sh:

• Prerequisites check
• Interactive prompts
• Installation steps
• Configuration
• Summary output

1. Test setup.sh syntax: bash -n setup.sh
2. Make executable: chmod +x setup.sh
3. Test dry-run simulation

Phase 5: Templates & Examples (15 minutes)

1. Create templates/ directory
2. Add starter templates
3. Add example files
4. Document template usage in README

Phase 6: Quality Assurance (20 minutes)

1. Run syntax checks
2. Validate all links
3. Check file permissions
4. Test setup script (if possible)
5. Create CHECKLIST.md
6. Optional: Create AUDIT.md

Phase 7: Polish (10 minutes)

1. Add badges to README
2. Add architecture diagram
3. Add performance metrics (if applicable)
4. Add star history chart
5. Final commit + push

Total Time: ~2 hours for production-ready repo

Critical Pitfalls

1. Token/Config Duplication

Problem: Appending to config files without checking for duplicates.

Wrong:

echo "export TOKEN='xxx'" >> ~/.bashrc
# Run twice → duplicate entries!

Right:

if ! grep -q "export TOKEN=" ~/.bashrc 2>/dev/null; then
    echo "export TOKEN='xxx'" >> ~/.bashrc
else
    sed -i "s|export TOKEN=.*|export TOKEN='xxx'|" ~/.bashrc
fi

2. Heredoc Variable Expansion