Skip to content

aboylabs/ai-agent-skills / skills/github/comprehensive-public-repo-setup

comprehensive-public-repo-setup

Unverified

Create production-ready public repos with complete documentation, automated setup, bundled dependencies, and user-friendly installation.

FileKindSize
SKILL.mdskill md13.5 KB
references/CRITICAL_BASH_PITFALLS.mdmarkdown6.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)
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexUnverifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall