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 + CODEOFCONDUCT — 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 /   # 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.

# 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 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 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: the-open-agent
• Source: the-open-agent/oss-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.