| name | repo-init |
| description | Use when a local project directory has no GitHub repo and needs to be published — initializing git, creating the remote repo, adding a README, and converting a plan document into GitHub issues.
|
Repo Init
Overview
Use this skill to take a bare local project directory all the way to a fully scaffolded GitHub repo with a README and issues.
Core principle: Read the plan first -> git init -> push -> README -> issues, in that order.
Steps
1. Confirm inputs with the user
Confirm these inputs before any git or gh command runs:
- Repo visibility: public or private?
- Repo name (suggest the directory name as default)
- Target account/org (default: the authenticated
gh user)
2. Check prerequisites
gh auth status
ls -la <project-dir>
If .git already exists, skip step 4 (git init + first commit) and jump to step 5
(create the GitHub repo and push). Do not re-run git init on an existing repo.
3. Read the plan document
Before writing any git commits or the README, read plan.md (or equivalent) in
the project directory. This is required — the README and issues are derived from it.
4. Initialize git and make the first commit
cd <project-dir>
git init
git add .
git commit -m "Initial commit: <project-name> project scaffold
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
5. Create the GitHub repo and push
gh repo create <repo-name> --private --source=. --remote=origin --push
6. Write the README
Generate README.md from the plan. A good README includes:
- One-paragraph description of what the project does
- Stack table (tool + why)
- Prerequisites
- Setup steps (numbered, runnable)
- Key design decisions (brief)
- Data store or project structure diagram (if relevant)
Do not duplicate the full plan — summarize and surface what a new contributor needs to get started.
Commit and push:
git add README.md
git commit -m "Add README
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
git push
7. Create GitHub issues from the build steps
Read the build order section of the plan. Create one issue per step using gh issue create.
The plan typically labels build steps under a "Build Order" or "Steps" heading;
if no such section exists, ask the user how to slice the work before any issues are filed.
Issue body structure for each:
## Build step N of M### Files — list of files to produce### What to build — concrete description drawn from the plan### Quality gates — test/lint/typecheck commands### Notes — key constraints or gotchas from the plan
Create issues one at a time with separate gh issue create calls (not batched in a single shell command) to avoid quoting failures.
gh issue create --title "Step N: <title>" --body "<body>"
Constraints
- Always confirm visibility, name, and account with the user before any
git or gh command runs.
- Always read
plan.md (or equivalent) before writing the README or creating issues; both are derived from it.
- Always call
gh issue create once per issue; never stack multiple heredocs in one shell command.
- Always include a
Co-Authored-By: Claude trailer in the scaffold commit and the README commit.
- Skip
git init when .git already exists in the project directory.
Limitations
- Handles initial repo creation only; updating issues, labels, or milestones later needs separate tooling.
- Requires the
gh CLI authenticated with repo scope; org repos under restricted-policy may still reject the gh repo create call.
- Does not configure branch protection, default reviewers, labels, milestones, or GitHub Projects.
- Treats
plan.md as the single source for README and issues; multi-plan or wiki-style sources are out of scope.
Common Mistakes
Batching issue creates in one shell command
- Problem: Multi-heredoc quoting fails with EOF errors
- Fix: One
gh issue create call per issue, separate Bash tool calls
Writing the README before reading the plan
- Problem: Generic README that misses key design decisions
- Fix: Always read plan.md first
Skipping the inputs check
- Problem: Creating a public repo when the user wanted private (or wrong account)
- Fix: Confirm visibility, name, and account before any git or gh commands
