# Repo Bootstrap

> Scaffold a new open-source repository or bring an existing one up to community standard. Use when starting a project from scratch, open-sourcing internal code, or when a repo is missing baseline files (LICENSE, README, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue templates, CI, editorconfig, gitignore). Also use for "make this repo look professional", "what am I missing before I make this public", or GitHub community-standards checklists. Includes a pre-publication scrub for secrets and internal references.

- Skill: `the-open-agent/repo-bootstrap` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add the-open-agent/repo-bootstrap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/the-open-agent/repo-bootstrap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: the-open-agent (https://skillmd.com/u/the-open-agent)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/the-open-agent/repo-bootstrap

---


# Repo Bootstrap

Getting the substrate right once removes a hundred small frictions later. This skill
covers the baseline files, the ordering, and the pre-publication scrub that catches
what you cannot un-publish.

## Order of operations

Do these in order. Each unlocks the next.

1. **Name and one-liner** — you cannot write a README without them
2. **License** — before the first external contribution, not after (`license-and-legal`)
3. **`.gitignore` + `.editorconfig`** — before the first commit that leaks build artifacts
4. **README skeleton** — install → usage → why (`readme-that-converts`)
5. **CI** — a green check on the first PR sets the standard (`ci-pipelines`)
6. **CONTRIBUTING + CODE_OF_CONDUCT** — before you invite anyone
7. **Issue/PR templates** — before the issue tracker gets noisy (`issue-triage`)
8. **SECURITY.md** — before someone needs to report a vulnerability (`supply-chain-security`)
9. **First tagged release** — an untagged repo reads as unfinished (`release-engineering`)

## The baseline file set

| File | Non-negotiable? | Notes |
|---|---|---|
| `LICENSE` | Yes | Full text, exact SPDX-recognized copy. Not a link. |
| `README.md` | Yes | The whole project for 95% of visitors. |
| `.gitignore` | Yes | Start from `github/gitignore` for your language. |
| `CONTRIBUTING.md` | Yes once public | Setup, test, PR expectations. |
| `CODE_OF_CONDUCT.md` | Yes once public | Contributor Covenant 2.1 + a real contact address. |
| `SECURITY.md` | Yes once used | Reporting channel + supported versions. |
| `.github/workflows/ci.yml` | Yes | Even one job. Red/green is a social signal. |
| `.github/ISSUE_TEMPLATE/` | At stage 2+ | Forms (`.yml`) beat markdown templates. |
| `.github/PULL_REQUEST_TEMPLATE.md` | At stage 2+ | Short. Long ones get deleted by contributors. |
| `.editorconfig` | Yes | Kills the tabs/spaces PR diff noise permanently. |
| `CHANGELOG.md` | At first release | See `release-engineering`. |
| `CODEOWNERS` | At 3+ maintainers | Auto-assigns review. |
| `.github/dependabot.yml` | Yes | See `dependency-hygiene`. |
| `GOVERNANCE.md` | At stage 5 | Premature for solo projects. |

Templates for each live in `assets/` next to this skill. Read them with the Read tool
and adapt — never paste a template with `{{PLACEHOLDER}}` left in.

## Repository layout

Language communities have strong conventions; follow them over any generic advice.

```
.
├── src/ or lib/ or <pkgname>/   # the actual code, one obvious root
├── tests/                       # mirrors src/ structure
├── docs/                        # anything longer than the README
├── examples/                    # runnable, CI-tested, no pseudo-code
├── scripts/                     # dev tooling, not shipped
└── .github/                     # workflows, templates, CODEOWNERS
```

Rules that hold across languages:

- **One obvious entry point.** A newcomer should find "where does execution start" in
  under 30 seconds.
- **`examples/` must run.** Broken examples are worse than no examples — they signal
  the whole project is stale. Wire them into CI.
- **No `misc/`, `stuff/`, `new/`, `old/`, `temp/`, `v2/`.** These are unmerged decisions.
- **Tests mirror source paths.** `src/auth/token.ts` → `tests/auth/token.test.ts`.

## Pre-publication scrub

Run before the repo goes public. This is the irreversible step — Git history is
public forever, and GitHub caches deleted forks and dangling commits.

```bash
# Secrets across ALL history, not just HEAD
pip install detect-secrets 2>/dev/null; detect-secrets scan --all-files
gitleaks detect --source . --redact        # if available

# Manual sweep of high-signal patterns
git log -p --all | grep -nEi 'api[_-]?key|secret|password|BEGIN [A-Z ]*PRIVATE KEY|xox[baprs]-|ghp_|AKIA[0-9A-Z]{16}'

# Internal references that shouldn't ship
grep -rniE 'internal\.|\.corp|jira\.|confluence|@yourcompany\.com|TODO\(.*@' \
  --exclude-dir=.git . | head -40

# Large files that bloat every clone forever
git rev-list --objects --all \
  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
  | awk '$1=="blob" && $3>1000000 {print $3, $4}' | sort -rn | head -20
```

Non-negotiables:

- **A leaked credential in history is leaked.** Rotate it. Rewriting history with
  `git filter-repo` or BFG is cleanup, not remediation — assume it was scraped.
- **Decide history strategy before publishing.** Keeping internal history is honest
  and preserves attribution; squashing to one commit is safer if the history contains
  employer-internal discussion. Squashing after publication is pointless.
- **Check employer IP policy** before open-sourcing work code. This is a real legal
  question and you should tell the user to get a real answer, not guess for them.

## Naming and positioning

The name is the most-repeated string in the project's life. Test it:

- **Pronounceable** in one try, over a video call, by a non-native speaker
- **Searchable** — not a common English word; "search `<name> github`" should find you
- **Available** — GitHub org/repo, package registry (npm/PyPI/crates), domain, and the
  social handle you will eventually want
- **Not trademarked** in your space, and not `<BigCorpProduct>JS`

The one-liner matters more than the name. Under 12 words, no adjectives, states the
category and the differentiator:

- Bad: "A modern, blazing-fast, developer-friendly toolkit for the next generation of apps"
- Good: "A build tool for JavaScript that skips bundling in development"

If you cannot write that sentence, the project scope is not settled yet. Fix that
before writing any docs.

## Anti-patterns

- **Publishing without a license.** Legally, "no license" means nobody may use it.
  This is the single most common fatal mistake.
- **`README.md` containing only the project name.** Ship even three sentences.
- **Copying a CoC without setting the contact address.** `[INSERT EMAIL]` in a live
  repo signals the whole thing is decoration.
- **Committing secrets, then deleting them in a follow-up commit.** They stay in history.
- **Ten templates before one user.** Baseline files, then real work, then process.