Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

oss-setup-dev-env

Set up a complete development environment for an unfamiliar OSS repo. Handles dependency installation, building, running tests, and configuring dev tooling. Use when cloning a new OSS repo and setting up for development, when the repo's setup instructions don't work, or when you need to debug environment issues. Not for setting up your own project — this is for getting someone else's repo running.

chiruu12 · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add chiruu12/OSS-Skills --skill oss-setup-dev-env

About this skill


name: oss-setup-dev-env description: | Set up a complete development environment for an unfamiliar OSS repo. Handles dependency installation, building, running tests, and configuring dev tooling. Use when cloning a new OSS repo and setting up for development, when the repo's setup instructions don't work, or when you need to debug environment issues. Not for setting up your own project — this is for getting someone else's repo running.

Setup Dev Env

Get an unfamiliar repo building, running, and testing on your machine. Setup instructions are often outdated or assume knowledge you don't have. This skill systematically works through the actual requirements — not just what the README says.

Purpose

The #1 reason contributors abandon their first OSS contribution isn't the code — it's the setup. Outdated README instructions, missing system dependencies, version mismatches, and Docker configurations that assume Linux all stop contributors cold. This skill teaches you to read the repo's actual build system, identify real requirements, and get a working development environment — even when the README is wrong.

When to Use

  • Cloning an OSS repo for the first time and setting up to develop
  • The repo's setup instructions didn't work
  • You need to debug why tests pass in CI but fail locally
  • Setting up a repo that uses tools/build systems you're unfamiliar with
  • NOT for setting up your own project
  • NOT for CI debugging — use oss-debug-ci for that

Prerequisites

  • Repo forked and cloned
  • Basic familiarity with your OS's package manager (brew, apt, etc.)
  • gh CLI authenticated (to check CI configuration for hints)

Process

1. Read the setup instructions (but don't trust them)

Start with the official instructions, but verify as you go.

# Find setup documentation
cat README.md | head -100
cat CONTRIBUTING.md docs/DEVELOPMENT.md docs/setup.md INSTALL.md 2>/dev/null | head -100

# Check when setup docs were last updated vs when code was last changed
git log --oneline -1 -- README.md CONTRIBUTING.md docs/DEVELOPMENT.md 2>/dev/null
git log --oneline -1 -- .

If the setup docs are 6+ months older than the latest code changes, they may be stale. Continue reading them, but verify each step against the actual build configuration.

2. Identify the build system and requirements

Read the actual build configuration — this is the source of truth, not the README.

# Language and package manager detection
ls package.json pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null  # Node.js
ls pyproject.toml setup.py setup.cfg requirements*.txt Pipfile 2>/dev/null  # Python
ls go.mod go.sum 2>/dev/null  # Go
ls Cargo.toml Cargo.lock 2>/dev/null  # Rust
ls Gemfile Gemfile.lock 2>/dev/null  # Ruby
ls pom.xml build.gradle build.gradle.kts 2>/dev/null  # Java/Kotlin
ls Makefile CMakeLists.txt 2>/dev/null  # Native/C/C++

# Version requirements
cat .node-version .nvmrc .python-version .ruby-version .tool-versions .mise.toml 2>/dev/null
cat package.json 2>/dev/null | grep -A 2 '"engines"'
cat pyproject.toml 2>/dev/null | grep -A 2 "python"
cat go.mod 2>/dev/null | head -3
cat rust-toolchain.toml rust-toolchain 2>/dev/null

# Docker-based development?
ls Dockerfile docker-compose.yml docker-compose.yaml .devcontainer/ 2>/dev/null

# System dependency hints
cat Makefile 2>/dev/null | head -50
cat Brewfile 2>/dev/null

Document:

  • Runtime: what language, what version?
  • Package manager: npm/pnpm/yarn? pip/uv/poetry? cargo?
  • System deps: databases, native libraries, tools?
  • Docker: is development Docker-based or Docker-optional?

3. Check CI for the real environment

CI configuration reveals what actually works — it's tested on every commit.

# Read the CI configuration
cat .github/workflows/ci.yml .github/workflows/test.yml 2>/dev/null

# What versions does CI use?
grep -A 3 "node-version\|python-version\|go-version\|rust-version" .github/workflows/*.yml 2>/dev/null

# What setup steps does CI run?
grep -A 5 "run:" .github/workflows/ci.yml 2>/dev/null | head -40

# What services does CI use? (databases, caches, etc.)
grep -A 10 "services:" .github/workflows/ci.yml 2>/dev/null

If the README says "use Node 18" but CI uses Node 22, use Node 22.

4. Install dependencies

Follow the build system, not the README.

# Node.js (detect the right package manager)
# Check for lockfiles to determine which manager
ls pnpm-lock.yaml 2>/dev/null && echo "Use: pnpm install"
ls yarn.lock 2>/dev/null && echo "Use: yarn install"
ls package-lock.json 2>/dev/null && echo "Use: npm install"

# Python
ls pyproject.toml 2>/dev/null && echo "Check: uv, pip, or poetry"
ls requirements.txt 2>/dev/null && echo "Use: pip install -r requirements.txt"

# Go
ls go.mod 2>/dev/null && echo "Use: go mod download"

# Rust
ls Cargo.toml 2>/dev/null && echo "Use: cargo build"

Common failure points:

  • Wrong runtime version → use version manager (nvm, pyenv, rustup)
  • Missing native dependencies → check Makefile, CI, or issue tracker for hints
  • Network issues → check if the repo uses private registries
  • Lockfile conflicts → use the exact package manager version CI uses

5. Build and run

# Find the build command
cat package.json 2>/dev/null | grep -A 10 '"scripts"' | head -15
cat Makefile 2>/dev/null | grep -E "^[a-zA-Z].*:" | head -10
cat pyproject.toml 2>/dev/null | grep -A 10 '\[tool\.' | head -15

# Common build commands
# npm run build / pnpm build / yarn build
# make build / make all
# cargo build
# go build ./...
# python -m build

Verify the build succeeds. If it fails, read the error carefully — most build failures are missing dependencies or version mismatches, not code issues.

6. Run the tests

This is the real proof that your environment works.

# Find the test command
cat package.json 2>/dev/null | grep "test"
cat Makefile 2>/dev/null | grep -E "^test.*:"
cat pyproject.toml 2>/dev/null
Read the complete source ↗