repo-setup

intent

automate the full pipeline for setting up a local development environment on a github repository. this skill handles forking (if needed), cloning with authentication, configuring upstream remotes, creating feature branches from the latest upstream state, and installing language-specific dependencies. use this when starting work on an open-source project, setting up a multi-repo development environment, onboarding to a new codebase, or exploring unfamiliar projects locally.

inputs

required parameters:

• owner/repo: github repository identifier (e.g., torvalds/linux, nodejs/node)
• github_username: your github account username, used for fork urls and clone paths
• gh_token: github personal access token, obtained via gh auth login. store as export GH_TOKEN=<token> in your shell profile or .env. required for: forking private repos, cloning private forks, pushing commits back to your fork. without it, git push and gh repo fork will fail with auth errors.

optional parameters:

• branch_name: name for your feature branch (default: stay on upstream default branch). follow naming conventions: fix/description, feat/description, refactor/description
• working_directory: local path where repo clones (default: ~/prs/{repo_name}). useful for multi-repo setups or non-standard directory layouts

external connections:

• github cli (gh): must be installed and authenticated. check with gh auth status
• git: must be installed and in $PATH. check with git --version
• language runtime(s): python, node, go, rust, java, kotlin, or others matching detected project type

edge cases to handle:

• github api rate limits: 60 requests unauthenticated, 5000 authenticated per hour. forking + fetch operations count against this
• network timeouts: cloning large repos over slow connections may timeout (git default is 5 min). increase with git config http.postBuffer 524288000
• auth expiry: tokens expire if set to non-infinite lifetime. skill will fail at fork or push step. user must refresh token and rerun
• ssh vs https: token auth uses https clone urls. if user prefers ssh, skip token injection and use ssh key auth instead
• repository already owned: if user already owns the repo (e.g., their own fork exists), gh repo fork is a no-op, which is correct behavior

procedure

step 1: validate prerequisites

input: system state

• run gh auth status and confirm output shows "logged in to github.com as {username}"
• run git --version and confirm git is installed
• confirm GH_TOKEN environment variable is set (or token is in gh config)

output: confirmation that tooling is available, or explicit error asking user to run gh auth login

step 2: resolve repository ownership and fork decision

input: owner/repo, github_username

• query github api (via gh repo view owner/repo) to get repo metadata
• check if user already owns a fork (i.e., does username/repo exist and is it a fork of owner/repo?)

decision: go to step 3 (fork) if user does not own the repo. skip to step 4 (clone user's fork) if fork exists. if user owns the original repo, skip forking entirely and clone their own repo.

output: boolean flag (fork_exists) and actual fork url to use

step 3: fork repository (conditional)

input: fork_exists flag, owner/repo, gh_token

• if fork_exists is true, skip this step
• if fork_exists is false, run gh repo fork owner/repo --clone=false

handle errors:

• if fork already exists (race condition), treat as success
• if rate limit hit, fail with message directing user to wait or use personal token
• if repo is not public and user lacks access, fail with explicit auth error

output: confirmation that fork exists at https://github.com/{github_username}/{repo_name}

step 4: clone or fetch

input: working_directory, github_username, repo_name, gh_token

• if directory already exists at working_directory, cd into it and run git fetch --all to refresh
• if directory does not exist:
  • create parent directories: mkdir -p "$(dirname "$working_directory")"
  • clone using token auth: git clone "https://${GH_TOKEN}@github.com/${github_username}/${repo_name}.git" "$working_directory"
  • alternatively (if user prefers ssh): git clone "git@github.com:${github_username}/${repo_name}.git" "$working_directory"
  • cd into cloned directory

handle errors:

• if clone fails with "authentication failed", confirm GH_TOKEN is set and valid
• if clone fails with "repository not found", confirm fork was created and user has push access
• if network timeout, retry once after 10 seconds or fail with guidance on increasing git http.postBuffer
• if directory exists but is corrupted (e.g., .git folder missing), offer to remove and re-clone

output: repo cloned and ready at working_directory, with origin remote pointing to user's fork

step 5: configure upstream remote

input: repo already cloned at working_directory, owner, repo_name

• cd into working_directory
• check if upstream remote exists: git remote get-url upstream
• if upstream does not exist, add it: git remote add upstream "https://github.com/${owner}/${repo_name}.git"
• fetch upstream refs: git fetch upstream

handle errors:

• if upstream already points to wrong url, remove and re-add: git remote remove upstream && git remote add upstream ...
• if fetch fails due to repo deletion or access loss, fail with clear message

output: upstream remote configured, all upstream refs available locally

step 6: create and checkout feature branch (conditional)

input: branch_name (optional), upstream remote, repo default branch

• detect upstream default branch: git remote show upstream 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}', fallback to main if not found
• if branch_name is provided:
  • create branch from latest upstream: git checkout -b {branch_name} upstream/{DEFAULT_BRANCH}
  • output: on new feature branch, ready for commits
• if branch_name is not provided:
  • skip branch creation, stay on current branch (usually upstream default)
  • output: user should create a branch manually before committing

handle errors:

• if branch name already exists locally, fail with message "branch {branch_name} already exists, use git checkout to switch or git branch -d to delete"
• if upstream/{DEFAULT_BRANCH} does not exist, pull all tags and retry: git fetch upstream --all

output: on feature branch, synced to latest upstream state

step 7: detect project type and install dependencies

input: repo at working_directory, directory listing

scan for language indicators in this order (stop at first match):

• pyproject.toml (python, modern): pip install -e ".[dev]" or fallback to pip install -e .
• setup.py (python, legacy): pip install -e ".[dev]" or fallback to pip install -e .
• requirements.txt (python): pip install -r requirements.txt
• package.json (node): npm install
• go.mod (go): go mod download
• Cargo.toml (rust): cargo build
• pom.xml (java/maven): mvn install -DskipTests
• build.gradle (java/kotlin/gradle): ./gradlew build -x test

if dev install fails (common with native dependencies or missing system libs):

• attempt install of core dependencies only (skip optional extras)
• skip gpu/native acceleration packages
• ensure test framework is installed (pytest, jest, etc.) at minimum
• log warnings but do not fail entirely

if no indicators found, output message: "no recognized dependency manager found. skipping dependency installation. verify manually if needed."

output: dependencies installed or skipped with clear explanation

step 8: verify setup

input: repo at working_directory

• cd into working_directory
• print current directory: pwd
• print current branch: git branch --show-current
• print upstream url: git remote get-url upstream
• print origin url: git remote get-url origin
• run language-specific build/import test:
  • python: python -c "import {inferred_package_name}" (check if main module imports cleanly)
  • node: npm run build (if build script exists) or npm test --dry-run
  • go: go build ./...
  • rust: cargo check
  • java: mvn compile (without install to skip tests)

output: summary of repo state and confirmation that code compiles/imports

decision points

fork creation: if user already owns a fork of the target repo, skip fork step (no-op). if user owns the original repo, skip forking and clone their own repo directly.

clone method: if gh_token is set, use https clone with token injected into url. if user specifies ssh preference, use ssh clone url instead (requires ssh key configured).

branch creation: if branch_name is provided, create feature branch from latest upstream default. if not provided, stay on the upstream default branch (typically main). user must manually create and checkout a branch before committing.

dependency installation: if project type is detected (pyproject.toml, package.json, go.mod, etc.), run appropriate install command. if install fails partway through, attempt to install core deps only and continue. if no project type is detected, skip dependency installation and warn user. if no language runtime is available (e.g., python not installed), fail with message directing user to install runtime.

retry on failure: if network timeout occurs during clone or fetch, retry once after 10 seconds. if auth fails, prompt user to refresh GH_TOKEN and rerun. if branch creation fails due to existing branch, prompt user to rename or delete the existing branch.

output contract

success state:

• local repository cloned at {working_directory} (default: ~/prs/{repo_name})
• user's fork set as origin remote
• upstream repository set as upstream remote with all refs fetched
• current branch is {branch_name} (if provided), tracking upstream default branch, or current upstream default (if no branch provided)
• dependencies installed and verified (or explicitly skipped with explanation)
• no uncommitted changes
• all remotes and branch config is correct and printable via git remote -v and git branch -vv

file/directory structure:

~/prs/{repo_name}/
├── .git/
│   ├── refs/remotes/
│   │   ├── origin/
│   │   └── upstream/
│   └── config (contains origin and upstream urls)
├── {project files}
└── node_modules/ or .venv/ or other language-specific artifacts (if installed)

data format: all output is text-based. final verification prints human-readable summary of git config and branch state.

outcome signal

user knows the skill worked when:

1. terminal shows "branch: {branch_name}" or "branch: {upstream_default_branch}" (correct branch checked out)
2. git remote -v shows two remotes: origin (user's fork) and upstream (original repo)
3. git log upstream/{default_branch} -1 shows recent commits from the original repo
4. language-specific import/build test passes (python import works, npm runs, go builds, etc.)
5. no uncommitted changes or merge conflicts (git status shows "nothing to commit")
6. user can immediately start editing code and committing to their feature branch

if any of these fail, the skill prints explicit error with remediation steps.