version: "1.0.1" name: repo-init description: Initialize a new repository with standard scaffolding - git, gitignore, CLAUDE.md, justfile, mise, and beads. Use when starting a new project or setting up an existing repo for Claude Code workflows.

Repository Initialization

Scaffold a new or existing repository with standard project infrastructure.

Related skills:

• just-pro - Build system patterns and templates
• mise - Tool version management
• go-pro, rust-pro, typescript-pro - Language-specific setup (run after repo-init)

What This Skill Does

Creates universal scaffolding that works across all project types:

Flow

1. Gather context (language, project type)
2. Create scaffolding
3. Initialize beads
4. Point to language skill for next steps

Step 1: Gather Context

Before scaffolding, clarify:

1. Project language(s): Go, Rust, TypeScript, Python, or multi-language?
2. Project type: Library, CLI, web app, API, monorepo?
3. Existing files: Is this a fresh repo or adding to existing code?

Use AskUserQuestion if unclear from context.

Step 2: Git Setup

# Initialize git if needed
git init
 
# Create .gitignore with common patterns

.gitignore Templates

Each language skill provides a comprehensive .gitignore in its references/ directory. These include common patterns (.env, .envrc, .DS_Store, Thumbs.db, IDE files) plus language-specific ignores.

Copy from the appropriate language skill:

For multi-language repos: Start with the primary language's gitignore, then merge patterns from others as needed.

Minimal fallback (if language skill unavailable):

# Environment
.env
.env.local
.env.*.local
.envrc
 
# OS
.DS_Store
Thumbs.db
 
# IDE
.idea/
.vscode/
 
# Build (customize per language)
dist/
build/
target/
node_modules/
__pycache__/

Step 3: CLAUDE.md

Create project conventions file for Claude Code:

# Project Name - Claude Instructions
 
## Overview
 
Brief description of what this project does.
 
## Development
 

just setup # First-time setup just check # Run all quality gates

 
## Conventions
 
- [Add project-specific patterns here]
- [Coding standards, naming conventions, etc.]
 
## Architecture
 
- [Key directories and their purposes]
- [Important abstractions]

Keep it minimal initially. Add conventions as they emerge.

Step 4: Justfile Skeleton

# Project Build System
# Usage: just --list
 
default:
    @just --list
 
# First-time setup
setup:
    mise trust
    mise install
    @echo "Ready. Run 'just check' to verify."
 
# Quality gates - add language-specific checks
check:
    @echo "Add fmt, lint, test recipes"
 
# Remove build artifacts
clean:
    @echo "Add clean commands"

For language-specific recipes, see:

• just-pro skill references (package-go.just, package-rust.just, etc.)

Step 5: Mise Configuration

Create empty .mise.toml ready for tool pinning:

[tools]
# Add tools with: mise use <tool>@<version>
# Examples:
# node = "22"
# go = "1.25"
# rust = "1.83"
# just = "latest"

Step 6: Beads Initialization

bd init -q

This creates .beads/ directory with issue tracking database.

For teams, consider:

• bd init --team - Interactive team workflow setup
• bd init --stealth - Personal use without affecting collaborators

Step 7: Environment Template

Create .envrc.example (committed) as template for .envrc (gitignored):

# Copy to .envrc and fill in values
# cp .envrc.example .envrc && direnv allow
 
# Mise integration
if command -v mise &> /dev/null; then
  eval "$(mise hook-env -s bash)"
fi
 
# Project-specific environment
# export DATABASE_URL="postgres://localhost/myapp"
# export API_KEY=""

Step 8: Next Steps

After scaffolding, point user to language-specific setup:

Quick Reference

# Full init sequence
git init
# Create .gitignore, CLAUDE.md, justfile, .mise.toml, .envrc.example
bd init -q
mise use just@latest
# Then follow language skill for specifics

Monorepo Variant

For monorepos, the root gets:

• Root justfile with module imports (see just-pro monorepo patterns)
• Root .mise.toml with shared tooling
• Single .beads/ at root

Each package gets:

• Package-local justfile
• Language-specific configs (Cargo.toml, package.json, etc.)