| name | repo-bootstrap |
| description | 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. |
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.
- Name and one-liner — you cannot write a README without them
- License — before the first external contribution, not after (
license-and-legal)
.gitignore + .editorconfig — before the first commit that leaks build artifacts- README skeleton — install → usage → why (
readme-that-converts)
- CI — a green check on the first PR sets the standard (
ci-pipelines)
- CONTRIBUTING + CODE_OF_CONDUCT — before you invite anyone
- Issue/PR templates — before the issue tracker gets noisy (
issue-triage)
- SECURITY.md — before someone needs to report a vulnerability (
supply-chain-security)
- 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.
pip install detect-secrets 2>/dev/null; detect-secrets scan --all-files
gitleaks detect --source . --redact
git log -p --all | grep -nEi 'api[_-]?key|secret|password|BEGIN [A-Z ]*PRIVATE KEY|xox[baprs]-|ghp_|AKIA[0-9A-Z]{16}'
grep -rniE 'internal\.|\.corp|jira\.|confluence|@yourcompany\.com|TODO\(.*@' \
--exclude-dir=.git . | head -40
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.
