Auto Repo Setup — Self-Service Codebase Configuration and Troubleshooting

Overview

This skill turns Claude Code into an "environment doctor" for non-technical users: after users clone a repository or open a project and say "it won't run", Claude automatically diagnoses, repairs, and verifies following standard procedures, without requiring users to understand underlying technical details.

At the same time, this skill also standardizes the standard actions for technical users to build transferable repositories (ONBOARDING.md, SessionStart hook, PII security).

Target Users:

Primary: Non-technical personnel (video editors, business staff, operations staff) — they don't know what uv, ffmpeg, or whisper.cpp are
Secondary: Technical users — standardize repository setup processes and reduce downstream maintenance costs

Core Workflow

Step 0: Read Project Map

Upon entering any repository, the first thing to do is read the following files (in priority order):

```
ONBOARDING.md
```
— Project-specific setup guide (if exists)
```
README.md
```
— Fallback
```
CLAUDE.md
```
— Project-level rules (if exists)
```
.claude/settings.json
```
— Check for SessionStart hook

If ONBOARDING.md does not exist:

Ask the user if they need to create one (automatically generate a draft based on repository structure)
Do not blindly guess setup steps without a guide

Step 1: Environment Audit (Follow verification steps in ONBOARDING.md)

Execute each "Step X: Verify..." or similar section in ONBOARDING.md one by one. Must verify output after each execution, do not assume success.

Common check items (adjust based on project type):

Check Item	Command Example	Failure Handling
Git Status	`git status` / `git remote -v`	Prompt user to configure git identity
System Dependencies	`ffmpeg -version` / `which uv`	Install according to ONBOARDING.md
Python Environment	`uv --version` / `python --version`	Create venv using uv
Project Dependencies	`uv sync` / `uv pip install -e .`	Read pyproject.toml
Models/Binaries	`ls models/` / `whisper.cpp/whisper-cli -h`	Download/compile according to documentation
Environment Variables	`cat .env` to check if keys exist	Guide user to fill in or generate

Notes:

Use
```
uv
```
to manage Python, prohibit using system-provided Python
All Python executions must be in a virtual environment or via uv
Check the exit code and stderr of commands, do not only look at stdout

Step 2: Repair Iteration

Debug root cause first, then workaround (iron rule):

Collect evidence (read logs/stack traces/configurations, do not guess)
Locate root cause along the call chain
Fix targeting the root cause
(Optional) Mark "temporary" workaround and explain why it's insufficient

Prohibited:

Reinstall/restart directly upon seeing errors
Clean up with
```
rm -rf
```
(must analyze file usage, get user confirmation, create backup)
Silently bypass errors (
```
|| true
```
, empty except blocks)

Step 3: Run Verification (Self-verification loop)

Must verify after repair:

Run smoke test or test commands from ONBOARDING.md
If the project has pytest, run
```
uv run pytest
```
(minimum set)
If verification fails → return to Step 2, do not tell users "it should work now"

Step 4: Delivery Status Report

Tell users in concise non-technical language:

✅ What has been fixed
⚠️ What users still need to do manually (e.g., fill in personal API key)
📋 What command to run next (copied from ONBOARDING.md)

Security and Compliance Iron Rules

Repository Visibility Check (Push Safety)

Before any
git push
, must verify the actual visibility of the repository:

bash

gh repo view <owner>/<repo> --json visibility,isPrivate,stargazerCount,forkCount

Public + multiple stars/forks → Default to PR workflow (push feature branch +
```
gh pr create
```
)
Public + 0 stars/forks and user explicitly authorized → Can push to main, but content still needs audit
Private/internal → Pushing to main requires user confirmation, risk level is reduced
Prohibit inferring visibility from URL, do not write "private repo" in reports unless API confirms
```
isPrivate: true
```

PII Guard and Secret Management

Public repo (multi-layer scanning):

Layer 1 — Gitleaks standard secrets + private domains/IPs
Layer 2 — Path scanning (prohibit locally generated paths)
Layer 3 — Bash grep fallback (Chinese content, known identities)
Layer 4 — AI semantic reading (catch non-keyword semantic private information missed by the first three layers)

Private repo:

```
.env
```
can be submitted directly (project-isolated API keys)
Still need to clean up personal absolute paths (
```
/Users/<name>/
```
)

Git Hook Bypass Ban

❌ Claude prohibits actively using
```
--no-verify
```
/
```
--no-gpg-sign
```
✅ Only exception: User explicitly inputs
```
--no-verify
```
in the current session
Hook failure → Fix underlying issues, do not bypass

NO FALLBACK Principle

When the system cannot determine a value (key field obtained from external systems), must fail-fast:

python

# ❌ Prohibited
apiKey: process.env.KIMI_API_KEY || 'sk-kimi-...'

# ✅ Correct
import os
api_key = os.environ["KIMI_API_KEY"]  # KeyError if missing

Placeholders (
```
"your-key-here"
```
) can only be in
```
.env.example
```
, never in real code
After writing LLM/API client initialization, self-check: What happens if
```
.env
```
is not loaded? Can plaintext be seen?

Standard Modes

ONBOARDING.md Mode

Transferable repositories must include

ONBOARDING.md

with the following structure:

markdown

# Project Name Setup Guide

## Step 1: Verify System Dependencies
- [ ] git is installed
- [ ] ffmpeg is installed (`ffmpeg -version`)
- [ ] uv is installed (`uv --version`)

## Step 2: Initialize Python Environment
```bash
uv sync

Step 3: Verify Installation

bash

uv run pytest tests/test_smoke.py -v

Step 4: Configure Environment Variables

Copy placeholders in

.env

to real values (private repo can be edited and submitted directly)

Step 5: Run Project

[Specific command]


**Requirements**:
- All commands can be copied and executed directly (no personal paths, no assumptions)
- Use relative paths or placeholders (`<REPO_ROOT>`)
- Include "verification" steps, not just "installation" steps

### SessionStart Hook Mode

Let Claude Code automatically check the environment when opening a repository:

**`.claude/settings.json`**:
```json
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/session-start-check.sh"
          }
        ]
      }
    ]
  }
}

.claude/hooks/session-start-check.sh
:

bash

#!/usr/bin/env bash
CACHE_DIR="$HOME/.claude/cache/env-check"
mkdir -p "$CACHE_DIR"
REPO_HASH=$(cd "$(dirname "$0")/../.." && pwd | sha256sum | cut -d' ' -f1)
CACHE_FILE="$CACHE_DIR/$REPO_HASH"
if [ -f "$CACHE_FILE" ] && [ "$(find "$CACHE_FILE" -mtime -1 2>/dev/null)" ]; then
    exit 0
fi
touch "$CACHE_FILE"
echo "【Environment Self-Check】You just entered the [Project Name] repository. Please read ONBOARDING.md and verify the environment according to Steps 1-3 before performing any tasks."

One-click Initialization Script:

The skill comes with

scripts/init_session_start_hook.py

, which can automatically generate configurations for any project:

bash

# Basic usage (automatically infer project name, default to reading ONBOARDING.md)
python scripts/init_session_start_hook.py --repo /path/to/project

# Full usage
python scripts/init_session_start_hook.py \
  --repo /path/to/project \
  --guide ONBOARDING.md \
  --update-gitignore

Script Behavior:

Create
```
.claude/settings.json
```
(SessionStart hook configuration)
Create
```
.claude/hooks/session-start-check.sh
```
(24h cache + self-check prompt)
When
```
--update-gitignore
```
is used, append rules to allow
```
.claude/settings.json
```
and
```
hooks/
```
to be included in git
Automatically infer project name from git remote or directory name
Skip by default if configuration already exists (use
```
--force-overwrite
```
to overwrite)

Design Principles:

Hook only responsible for prompting the agent to check (output prompt), not responsible for complex script checks
24h TTL cache to reduce frequency (use repo path sha256 as cache key)
Project-level configuration, deep merged with global settings

Counter-Review Workflow

When needing to create new files, modify core configurations, add external dependencies, modify CI/CD, change security policies, start multi-agent review:

Start 4 lenses in parallel (one subagent each):
- security-lens: PII/secret leakage, injection risks, excessive permissions
- devops-lens: Deployment impact, dependency conflicts, hardcoded paths
- code-quality-lens: Readability, exception handling, test coverage
- doc-consistency-lens: Documentation-code synchronization, ONBOARDING.md updates
Judge agent filtering:
- Filter each finding using three dimensions: "probability × cost × real scenario"
- Real + low cost → Fix immediately
- Real + high cost → Tell user to weigh trade-offs
- Fictional / over-concerned → Clearly state "This is over-defense, rejected"
Classified report to user: ✅ Real issue / ⚠️ Partially correct / ❌ Fictional / 🚫 Counterproductive

Git Operation Specifications

Committing Code (Non-technical User Scenario)

When users say "help me commit" or "save it":

```
git status
```
to check changes
```
git diff
```
to confirm change content (explain to user what was changed)
```
git add
```
(selective, do not mindlessly use
```
git add .
```
)
```
git commit -m "..."
```
- Use Chinese for the message, describe what was changed and why
- Add
```
Co-Authored-By: Claude <noreply@anthropic.com>
```
  at the end
Go through Push Safety verification before
```
git push
```

Handling Conflicts

When users say "there's a conflict":

```
git status
```
to locate conflict files
Read the
```
<<<<<<<
```
/
```
=======
```
/
```
>>>>>>>
```
blocks in conflict files
Do not automatically choose one side — explain the differences to the user and let them decide (or judge based on business logic)
After fixing, run
```
git add
```
+
```
git commit
```

History Sanitization (After Sensitive Information Leakage)

If sensitive information exists in repository history (personal paths, secrets, internal domains):

Assess impact scope: Which commits contain sensitive information? Has it been pushed to remote?

Orphan branch + force push (if history can be completely discarded):

bash

git checkout --orphan new-history
git add -A
git commit -m "Initial commit: sanitized history"
git push --force origin new-history:main

BFG Repo-Cleaner (if part of history needs to be retained): Used to replace sensitive strings in files
Notify user: Force push will interrupt other collaborators, need coordination

Project Isolation Specifications

API Key Isolation

Each project uses an independent API key, prohibit reusing personal/production keys:

Create independent keys for each project in the provider backend
Only place project-specific keys in
```
.env
```
Name keys to reflect usage (e.g.,
```
video-rough-cut-dev
```
)
Rotate regularly (can be revoked individually if leaked)

Path Cleanup

Prohibited in repositories:

Personal absolute paths (
```
/Users/<name>/
```
,
```
/home/<name>/
```
)

Internal domains/IPs (

<private-domain>.dev

<private-domain>.pro

, etc.)

Real Chinese names/project names (replace with placeholders)

Cleanup Methods:

Replace with placeholders (
```
<REPO_ROOT>
```
,
```
<USER_HOME>
```
,
```
<YOUR_NAME>
```
)
Replace absolute paths with relative paths
Store environment-related values in
```
.env
```
or configuration files

Common Troubleshooting Manual

"uv command not found"

Check if
```
~/.local/bin
```
is in PATH

Reinstall:

curl -LsSf https://astral.sh/uv/install.sh | sh

"ffmpeg command not found"

macOS:
```
brew install ffmpeg
```
Or install
```
ffmpeg-full
```
according to project documentation

"whisper.cpp compilation failed"

Check Xcode Command Line Tools:
```
xcode-select --install
```
Check Metal support (Apple Silicon)

"pytest has many failures"

Run minimal smoke test first, do not run full set at once
Check if
```
.env
```
has necessary API keys configured
Check if tests rely on local file system paths (should use temporary directories)

"git push rejected"

Check remote repository permissions
Check if branch protection is enabled
Go through Push Safety process to confirm repository visibility

Next Step: Code Review and Delivery

After completing environment configuration and basic repairs, recommended next steps:

Options: A) Run Counter-Review — If user is preparing for major changes, start multi-agent security review (Recommended) B) Generate Operation Documentation — Generate concise operation guide for user (what to click/run next) C) No thanks — Current state is sufficient, user can start using directly

Resource Directory

references/

```
git_safety.md
```
— Git operation safety details (Push Safety, Hook Bypass, history sanitization)
```
pii_guard.md
```
— PII Guard rule summary and emergency handling
```
onboarding_template.md
```
— ONBOARDING.md standard template

scripts/

```
check_env.py
```
— Environment check script (ffmpeg, uv, python, git status)
```
sanitize_history.sh
```
— History sanitization auxiliary script (check sensitive information, generate orphan branch)

auto-repo-setup

NPX Install

Tags

SKILL.md Content (Chinese)

Auto Repo Setup — Self-Service Codebase Configuration and Troubleshooting

Overview

Core Workflow

Step 0: Read Project Map

Step 1: Environment Audit (Follow verification steps in ONBOARDING.md)

Step 2: Repair Iteration

Step 3: Run Verification (Self-verification loop)

Step 4: Delivery Status Report

Security and Compliance Iron Rules

Repository Visibility Check (Push Safety)

PII Guard and Secret Management

Git Hook Bypass Ban

NO FALLBACK Principle

Standard Modes

ONBOARDING.md Mode

Step 3: Verify Installation

Step 4: Configure Environment Variables

Step 5: Run Project

Counter-Review Workflow

Git Operation Specifications

Committing Code (Non-technical User Scenario)

Handling Conflicts

History Sanitization (After Sensitive Information Leakage)

Project Isolation Specifications

API Key Isolation

Path Cleanup

Common Troubleshooting Manual

"uv command not found"

"ffmpeg command not found"

"whisper.cpp compilation failed"

"pytest has many failures"

"git push rejected"

Next Step: Code Review and Delivery

Resource Directory

references/

scripts/