aboylabs/ai-agent-skills / skills/github/public-repo-creation
public-repo-creation
UnverifiedCreate production-ready public GitHub repositories with comprehensive documentation, automated setup, and quality assurance
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)
- Contributing section
- License section
- Credits
- Support section
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)
- Define repository purpose (one sentence)
- Identify target audience
- List core features (3-5 main features)
- Choose license (MIT recommended)
- Plan folder structure
Phase 2: Core Setup (15 minutes)
- Create GitHub repo (public)
- Clone locally
- Create README.md with title, description, badges
- Create LICENSE file
- Create .gitignore
- Initial commit + push
Phase 3: Documentation (30 minutes)
- Expand README.md:
- Features section
- Quick start
- Manual setup
- Examples
- Architecture
- Create CONTRIBUTING.md
- Create TROUBLESHOOTING.md
- Create EXAMPLE.md
Phase 4: Automation (30 minutes)
- Create setup.sh:
- Prerequisites check
- Interactive prompts
- Installation steps
- Configuration
- Summary output
- Test setup.sh syntax:
bash -n setup.sh - Make executable:
chmod +x setup.sh - Test dry-run simulation
Phase 5: Templates & Examples (15 minutes)
- Create templates/ directory
- Add starter templates
- Add example files
- Document template usage in README
Phase 6: Quality Assurance (20 minutes)
- Run syntax checks
- Validate all links
- Check file permissions
- Test setup script (if possible)
- Create CHECKLIST.md
- Optional: Create AUDIT.md
Phase 7: Polish (10 minutes)
- Add badges to README
- Add architecture diagram
- Add performance metrics (if applicable)
- Add star history chart
- 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
Problem: Using single-quoted heredoc prevents variable expansion.
Wrong:
cat > file.txt << 'EOF'
date: $(date +%Y-%m-%d)
EOF
# Output: date: $(date +%Y-%m-%d) ← LITERAL!
Right:
cat > file.txt << EOF # No quotes!
date: $(date +%Y-%m-%d)
EOF
# Output: date: 2026-05-12 ← EXPANDED!
3. Hardcoded Paths
Problem: Hardcoding paths that may vary across systems.
Consider:
- Use
$HOMEinstead of/home/username - Use
$(dirname "${BASH_SOURCE[0]}")for script directory - Make paths configurable via prompts or environment variables
4. Missing Fallback Mechanisms
Problem: Single point of failure (e.g., GitHub clone only).
Solution:
if git clone https://github.com/repo.git 2>/dev/null; then
echo "✅ Cloned from GitHub"
else
echo "⚠️ GitHub failed, using bundled copy..."
cp -r bundled/ destination/
fi
5. Incomplete Documentation
Problem: Missing critical sections in README.
Must-have sections:
- What is This?
- Features
- Quick Start
- Installation
- Examples
- Troubleshooting
- Contributing
- License
6. No Quality Checks
Problem: Pushing without validation.
Always check:
- Syntax:
bash -n setup.sh - Links: Validate all internal links
- Permissions: Ensure setup.sh is executable
- TODOs: No TODO/FIXME in production
7. Character Count Confusion
Problem: Misunderstanding "260 kata" (words) vs "260 karakter" (characters).
Context: Indonesian "kata" = word, "karakter" = character.
Check:
# Word count
wc -w post.txt
# Character count (excluding newlines)
cat post.txt | tr -d '\n' | wc -c
Limits:
- Twitter/X: 280 characters (use 260 for safety)
- LinkedIn: 3,000 characters
- Reddit title: 300 characters
- Blog post: No strict limit (aim for 500-1000 words)
Always clarify with user: "260 words or 260 characters?"
8. Broken Internal Links
Problem: Referencing files that don't exist.
Check:
grep -o '\[.*\](.*\.md)' README.md | while read link; do
file=$(echo "$link" | sed 's/.*(\\(.*\\))/\\1/')
[ -f "$file" ] || echo "❌ Broken: $link"
done
Title Consistency
When creating repos with multiple components (e.g., "Tool A + Tool B + Feature C"):
-
Update ALL titles to include all components:
- README.md title
- setup.sh comment header
- EXAMPLE.md title
- CONTRIBUTING.md title
- GitHub repo description
-
Check consistency:
grep -h "^#.*Tool.*Feature" README.md EXAMPLE.md CONTRIBUTING.md setup.sh
Bundling Dependencies
When including third-party code (e.g., skills, libraries):
- Bundle in repo (don't rely on external availability)
- Remove nested .git directories
- Implement fallback logic:
- Try fetching latest from source
- Fall back to bundled copy if source unavailable
- Document in README:
- Mention bundled version
- Explain fallback mechanism
Security Considerations
-
Credentials:
- Never commit tokens/passwords
- Use
read -spfor sensitive input (no echo) - Store in user-only readable files (~/.bashrc, ~/.config)
- Add to .gitignore:
*.secret.md,*.private.md
-
Permissions:
- setup.sh: 755 (executable)
- Templates: 644 (readable)
- No world-writable files
-
Token Scopes:
- Use minimal scopes (e.g.,
repoonly) - Provide token generation link with pre-selected scopes
- Document required scopes in README
- Use minimal scopes (e.g.,
User Experience
Good UX:
- 5 or fewer user actions required
- Clear prompts with defaults
- Progress indicators
- Summary output at end
- Helpful error messages
- Verification checklist
Bad UX:
- 20+ manual steps
- No defaults (user must type everything)
- Silent failures
- Cryptic errors
- No way to verify success
Quality Metrics & Maximization
Quality Scoring Framework (7/10 → 10/10)
Scoring Categories (10 points each):
| Category | 7/10 (Good) | 10/10 (Perfect) |
|---|---|---|
| Documentation | README + basic docs | README + CHANGELOG + FAQ + 10+ docs |
| Installers | Working setup script | Multiple installers + smart detection |
| Templates | Basic templates | Complete template set |
| CI/CD | None | GitHub Actions + automated tests |
| Examples | Basic examples | Screenshots + demos + videos |
| Badges | License only | CI + License + Version + Stars + Forks |
| Changelog | None | Semantic versioning + release notes |
| Releases | None | Tagged releases + GitHub releases |
| Issue Templates | None | Bug report + feature request + PR template |
| Tests | None | Comprehensive test suite + passing CI |
Total Score Calculation:
- Sum all categories (max 100 points)
- Divide by 10 for final score
- 7/10 = Good (production-ready but basic)
- 10/10 = Perfect (world-class open source)
Production-Ready Checklist (7/10)
Minimum requirements:
- ✅ Comprehensive README (10KB+)
- ✅ Automated setup script (5KB+)
- ✅ Real-world examples
- ✅ Troubleshooting guide (20+ solutions)
- ✅ Installation checklist (20+ checks)
- ✅ Templates (3+ files)
- ✅ License (MIT recommended)
- ✅ Contributing guide
- ✅ All syntax valid
- ✅ All links working
- ✅ No TODOs in production
Perfect Repo Checklist (10/10)
Additional requirements for 10/10:
1. CI/CD (GitHub Actions)
# .github/workflows/ci.yml
name: github-public-repo-creation
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Validate syntax
run: bash -n setup.sh
- name: Run tests
run: ./tests/test-suite.sh
2. Comprehensive Test Suite
# tests/test-suite.sh
#!/bin/bash
set -e
echo "🧪 Running tests..."
# Test 1: Syntax validation
bash -n setup.sh && echo "✅ Syntax OK"
# Test 2: File existence
test -f README.md && echo "✅ README exists"
test -f CHANGELOG.md && echo "✅ CHANGELOG exists"
# Test 3: Documentation completeness
grep -q "Quick Start" README.md && echo "✅ Has Quick Start"
grep -q "FAQ" README.md && echo "✅ Has FAQ"
# Test 4: Installer detection (if applicable)
# ... custom tests ...
echo "✅ ALL TESTS PASSED!"
3. Issue Templates
Bug Report (.github/ISSUE_TEMPLATE/bug_report.md):
---
name: Bug report
about: Create a report to help us improve
---
## Bug Description
Clear description of the bug.
## To Reproduce
Steps to reproduce.
## Expected Behavior
What you expected.
## Environment
- OS: [e.g. Ubuntu 24.04]
- Version: [e.g. 1.0.0]
Feature Request (.github/ISSUE_TEMPLATE/feature_request.md):
---
name: Feature request
about: Suggest an idea
---
## Feature Description
Clear description of the feature.
## Motivation
Why is this needed?
## Proposed Solution
How should it work?
4. PR Template
.github/pull_request_template.md:
## Description
Brief description of changes.
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests pass
5. CHANGELOG.md
Format: Keep a Changelog
# Changelog
## [1.1.0] - 2026-05-12
### Added
- New feature X
- Improvement Y
### Fixed
- Bug Z
## [1.0.0] - 2026-05-11
### Added
- Initial release
6. GitHub Releases
# Create release
git tag -a v1.1.0 -m "Version 1.1.0"
git push origin v1.1.0
gh release create v1.1.0 --title "v1.1.0 - Feature Name" --notes "Release notes here"
7. Badges
[](https://github.com/user/repo/actions)
[](https://opensource.org/licenses/MIT)
[](https://github.com/user/repo/releases)
[](https://github.com/user/repo/stargazers)
[](https://github.com/user/repo/network/members)
8. FAQ Section
Add to README.md:
## ❓ FAQ
### Q: Common question 1?
**A:** Answer with details.
### Q: Common question 2?
**A:** Answer with details.
... (10+ questions)
Maximization Workflow (7/10 → 10/10)
Time: 1.5-2 hours
Phase 1: CHANGELOG + Release (15 min)
- Create CHANGELOG.md with version history
- Tag current version:
git tag -a v1.0.0 -m "Initial release" - Create GitHub release:
gh release create v1.0.0
Phase 2: Badges + FAQ (20 min)
- Add 5 badges to README (CI, License, Version, Stars, Forks)
- Add FAQ section with 10+ common questions
Phase 3: CI/CD + Tests (40 min)
- Create
.github/workflows/ci.yml - Create
tests/test-suite.shwith 6+ tests - Verify CI passes
Phase 4: Issue Templates (15 min)
- Create bug report template
- Create feature request template
- Create PR template
Phase 5: Verification (10 min)
- Run test suite locally
- Check CI status on GitHub
- Verify all badges display correctly
- Final quality score: 10/10 ✅
Quality Verification Commands
# 1. Check file count
find . -type f ! -path './.git/*' | wc -l
# 2. Check repo size
du -sh . --exclude=.git
# 3. Run tests
./tests/test-suite.sh
# 4. Check CI status
gh run list --limit 1
# 5. Verify badges
curl -s https://github.com/user/repo | grep -o 'img.shields.io' | wc -l
# 6. Count documentation
ls -1 *.md | wc -l
# 7. Verify release
gh release list
# 8. Check templates
ls -1 .github/ISSUE_TEMPLATE/ .github/pull_request_template.md
Critical Success Factors
For 10/10 Perfect Score:
- ✅ CI/CD: GitHub Actions workflow + passing tests
- ✅ Tests: Comprehensive test suite (6+ tests)
- ✅ Templates: Bug report + feature request + PR template
- ✅ CHANGELOG: Semantic versioning + release notes
- ✅ Release: Tagged release + GitHub release page
- ✅ Badges: 5+ badges (CI, License, Version, Stars, Forks)
- ✅ FAQ: 10+ common questions answered
- ✅ Documentation: 12+ comprehensive docs
User Preference (from session):
- User says "gas maksimalkan" → Do full 10/10 transformation, not incremental
- User says "pastikan perfect" → Test everything, verify thoroughly
- User expects immediate action → No hesitation, execute workflow
- User wants comprehensive results → Not minimal viable, but production-ready excellence
Example Structure
repo-name/
├── README.md # Comprehensive guide (10KB+)
├── setup.sh # Automated setup (executable)
├── LICENSE # MIT or other
├── CONTRIBUTING.md # Contribution guidelines
├── TROUBLESHOOTING.md # Common issues + fixes
├── CHECKLIST.md # Verification steps
├── EXAMPLE.md # Real-world use case
├── AUDIT.md # Quality audit (optional)
├── templates/
│ ├── getting-started.md
│ ├── config-template.yml
│ └── gitignore
├── examples/ # Additional examples (optional)
│ └── advanced-usage.md
└── bundled-deps/ # Bundled dependencies (if any)
└── third-party-lib/
Post-Creation Checklist
- All titles consistent (include all components)
- README comprehensive (10+ sections)
- setup.sh syntax valid (
bash -n setup.sh) - setup.sh executable (
chmod +x setup.sh) - All internal links valid
- No TODO/FIXME comments
- License file present
- .gitignore excludes secrets
- Templates included
- Examples included
- Troubleshooting guide present
- Installation checklist present
- Quality audit performed (optional)
- GitHub repo description updated
- All commits pushed
- Ready to share
References
- repo-maximization-checklist.md — Complete checklist for transforming 7/10 repo → 10/10 perfect (CI/CD, tests, templates, badges, FAQ)
- critical-bugs-mnemosyne-obsidian.md — Critical bugs found and fixed: token duplication + heredoc expansion
- setup-script-patterns.md — Complete patterns for robust setup scripts with examples
- deep-analysis-workflow.md — Comprehensive deep analysis checklist (10 checks + simulation + quality scoring)
See Also
github-pr-workflow— For contributing to existing reposcomprehensive-public-repo-setup— Alternative approach (may overlap)github-repo-management— For managing existing repos
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |