aboylabs/ai-agent-skills / skills/github/comprehensive-public-repo-setup
comprehensive-public-repo-setup
UnverifiedCreate production-ready public repos with complete documentation, automated setup, bundled dependencies, and user-friendly installation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.5 KB |
| references/CRITICAL_BASH_PITFALLS.md | markdown | 6.2 KB |
references/CRITICAL_BASH_PITFALLS.md
View on GitHub# Critical Bash Pitfalls in Setup Scripts
Common bugs found in production setup scripts that cause silent failures or duplicate configurations.
---
## 1. Token/Config Duplication in Bashrc
### Problem
Appending configuration to `~/.bashrc` without checking if it already exists.
**Impact:** Running setup script multiple times creates duplicate entries.
### Bad Code
```bash
echo "export GH_TOKEN='$GITHUB_TOKEN'" >> ~/.bashrc
```
**Result after 3 runs:**
```bash
export GH_TOKEN='ghp_abc123'
export GH_TOKEN='ghp_abc123'
export GH_TOKEN='ghp_abc123'
```
### Good Code
```bash
# Only add if not already present
if ! grep -q "export GH_TOKEN=" ~/.bashrc 2>/dev/null; then
echo "export GH_TOKEN='$GITHUB_TOKEN'" >> ~/.bashrc
echo "β
Token saved to ~/.bashrc"
else
# Update existing token
sed -i "s|export GH_TOKEN=.*|export GH_TOKEN='$GITHUB_TOKEN'|" ~/.bashrc
echo "β
Token updated in ~/.bashrc"
fi
```
**Benefits:**
- First run: adds new line
- Subsequent runs: updates existing line (no duplicates)
- User feedback: different messages for add vs update
### Real-World Impact
**Repo:** mnemosyne-obsidian
**Commit:** `9cfbf55` β "CRITICAL FIX: Prevent duplicate token in bashrc + fix date expansion in heredoc"
**Severity:** π΄ CRITICAL
**Found by:** Deep analysis (manual code review)
---
## 2. Variable Expansion in Single-Quoted Heredoc
### Problem
Using single-quoted heredoc delimiter (`<< 'EOF'`) prevents variable expansion.
**Impact:** Variables and command substitutions appear as literal strings in output files.
### Bad Code
```bash
cat > "Getting Started.md" << 'EOF'
---
title: Getting Started
date: $(date +%Y-%m-%d)
---
# Getting Started
Run: `obsidian`
EOF
```
**Output:**
```markdown
---
title: Getting Started
date: $(date +%Y-%m-%d) β LITERAL STRING!
---
# Getting Started
Run: `obsidian`
```
### Good Code
```bash
cat > "Getting Started.md" << EOF
---
title: Getting Started
date: $(date +%Y-%m-%d)
---
# Getting Started
Run: \`obsidian\`
EOF
```
**Output:**
```markdown
---
title: Getting Started
date: 2026-05-12 β ACTUAL DATE!
---
# Getting Started
Run: `obsidian`
```
**Key points:**
- Remove quotes from heredoc delimiter: `<< EOF` (not `<< 'EOF'`)
- Escape backticks in content: `` \`command\` ``
- Escape dollar signs if needed: `\$VAR`
### When to Use Single Quotes
Use `<< 'EOF'` when you want **literal** content (no expansion):
```bash
cat > script.sh << 'EOF'
#!/bin/bash
echo "Current user: $USER" # Literal $USER, not expanded
EOF
```
**Output:**
```bash
#!/bin/bash
echo "Current user: $USER" # Will expand when script runs
```
### Real-World Impact
**Repo:** mnemosyne-obsidian
**Commit:** `9cfbf55` β "CRITICAL FIX: Prevent duplicate token in bashrc + fix date expansion in heredoc"
**Severity:** π‘ MEDIUM
**Found by:** Deep analysis (manual code review)
**User impact:** Getting Started note showed literal `$(date +%Y-%m-%d)` instead of actual date
---
## 3. Missing Error Handling in Conditional Blocks
### Problem
Not checking exit codes in conditional blocks can hide failures.
### Bad Code
```bash
if git clone https://github.com/external/tool.git; then
echo "β
Installed from GitHub"
else
echo "β οΈ Using bundled copy"
cp -r bundled-tool/ /install/path/
fi
```
**Issue:** If `cp` fails, script continues silently.
### Good Code
```bash
if git clone --depth 1 https://github.com/external/tool.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)"
if ! cp -r "$SCRIPT_DIR/bundled-tool" "$INSTALL_DIR/"; then
echo "β Failed to copy bundled tool"
exit 1
fi
echo "β
Installed from bundle"
fi
```
**Improvements:**
- `--depth 1` for faster clone
- `2>/dev/null` to suppress error output
- Check `cp` exit code
- Exit on failure (with `set -e` at top)
---
## 4. Path Expansion Issues
### Problem
Not quoting paths with spaces causes word splitting.
### Bad Code
```bash
VAULT_PATH=$HOME/Documents/Obsidian Vault
mkdir -p $VAULT_PATH
```
**Result:** Creates 3 directories: `~/Documents/Obsidian`, `Vault`, and current directory.
### Good Code
```bash
VAULT_PATH="$HOME/Documents/Obsidian Vault"
mkdir -p "$VAULT_PATH"
```
**Rule:** Always quote variables that contain paths.
---
## 5. Unsafe User Input
### Problem
Not validating user input can cause command injection or path traversal.
### Bad Code
```bash
read -p "Project name: " PROJECT_NAME
mkdir "$PROJECT_NAME"
cd "$PROJECT_NAME"
```
**Attack:** User enters `../../etc` β creates directory outside intended location.
### Good Code
```bash
read -p "Project name: " PROJECT_NAME
# Validate: alphanumeric, dash, underscore only
if [[ ! "$PROJECT_NAME" =~ ^[a-zA-Z0-9_-]+$ ]]; then
echo "β Invalid project name. Use only letters, numbers, dash, underscore."
exit 1
fi
mkdir "$PROJECT_NAME"
cd "$PROJECT_NAME"
```
**Validation patterns:**
- Alphanumeric: `^[a-zA-Z0-9_-]+$`
- Email: `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`
- URL: `^https?://[a-zA-Z0-9.-]+`
---
## Testing Checklist
Before releasing setup script:
- [ ] Run script multiple times (check for duplicates)
- [ ] Check generated files for literal `$VAR` or `$(command)`
- [ ] Test with paths containing spaces
- [ ] Test with invalid user input
- [ ] Test with network disconnected (fallback logic)
- [ ] Test with missing prerequisites
- [ ] Run `bash -n script.sh` (syntax check)
- [ ] Run `shellcheck script.sh` (if available)
---
## Quick Reference
| Issue | Bad | Good |
|-------|-----|------|
| **Bashrc duplication** | `echo "..." >> ~/.bashrc` | `if ! grep -q "..."; then echo "..." >> ~/.bashrc; fi` |
| **Heredoc expansion** | `<< 'EOF'` | `<< EOF` (escape backticks: `` \` ``) |
| **Path with spaces** | `$VAULT_PATH` | `"$VAULT_PATH"` |
| **User input** | `mkdir "$INPUT"` | Validate first: `[[ "$INPUT" =~ ^[a-zA-Z0-9_-]+$ ]]` |
| **Error handling** | `cp file dest` | `if ! cp file dest; then exit 1; fi` |
---
## Real-World Example
**Repo:** https://github.com/kevinnft/mnemosyne-obsidian
**Bugs found:** 2 critical (token duplication, date expansion)
**Fixed in:** Commit `9cfbf55`
**Impact:** Setup script now idempotent (can run multiple times safely)
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 |