Workflow & Core Tools · daymade/claude-code-skills

auto-repo-setup

Name: auto-repo-setup
Author: daymade/claude-code-skills

Diagnose, repair, and standardize repository setup and safe Git workflows for Claude Code or Codex. Use when a repository will not run, a collaborator is onboarding, dependencies or credentials are missing, the user wants startup sync, SessionStart output is duplicated, project instructions or hooks need auditing, or commit/push/conflict/history-cleanup needs a guarded workflow. Route ordinary startup behavior through project instructions or a natural language request; use lifecycle hooks only when behavior must occur before the first prompt and the target runtime has been verified.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Environment repair is 'evidence-driven' rather than 'reinstall everything': read AGENTS.md/CLAUDE.md/ONBOARDING/README/manifest/CI in a fixed order, infer the actual technology stack using read-only inventory scripts, and then apply minimal remediation.

auto-repo-setup/SKILL.md

Use the bundled scripts/check_env.py against the repository root when a Python 3.10+ runner is already available. It detects the declared ecosystem and checks only the relevant toolchain; it does not install dependencies or read secret values.

What is being done here: Narrowing down vague issues like 'the repository won't run' into verifiable inventory gaps. check_env only checks whether the toolchains declared in manifests exist on PATH, using exit codes 0/1/2 (available/missing/cannot safely check) as a baseline for subsequent repair and verification.

The detection logic of check_env.py infers package managers and runtimes from explicit lockfiles/manifests (uv.lock, package-lock.json, go.mod, etc.), and then executes read-only commands preserving exit codes and stdout/stderr.

auto-repo-setup/scripts/check_env.py

def detect_toolchains(repo: Path) -> list[ToolRequirement]: """Infer package managers and runtimes from explicit manifests/lockfiles."""

The docstring of run_cmd states 'Run one read-only command and preserve its three observable outputs.' All detection commands enforce a 15-second timeout, hard termination via check=False, and capture of all three outputs, ensuring the script itself performs no installation, synchronization, or modifications.

'Minimal mechanism' hierarchy + hook gating: routine startup sync belongs in AGENTS.md/CLAUDE.md or natural language instructions; SessionStart hooks are installed only when execution 'must occur before the first prompt' and the host has been verified, always requiring a dry-run preview first.

auto-repo-setup/SKILL.md

Prefer, in order: direct Agent instruction → project instruction → explicit command → lifecycle hook. A hook is not a more professional version of a sentence.

Workflow D adds two layers of protection: 'Diagnose repeated output first' (count registrations and triggering sessions first; do not assume three registrations from three output lines) and 'Install only after the hook gate passes' (Preview first → --dry-run → remove --dry-run from the same command after user confirmation).

init_session_start_hook.py is a managed and idempotent hook installer: it adds only a single SessionStart entry tagged with [auto-repo-setup] (matcher startup + echo guidance), validates guide paths, preserves unrelated settings, writes atomically, and supports --remove.

auto-repo-setup/SKILL.md

The bundled initializer is Claude Code-specific and installs only a lightweight startup context nudge. It preserves unrelated settings, adds matcher startup, validates the guide path, writes atomically, and is idempotent.

The same discipline is evident in the script: MANAGED_MARKER = "[auto-repo-setup]" tags managed entries; validate_guide rejects absolute paths and '..', raising ConfigError on '"'$;&|<>!()% and backticks (FORBIDDEN_GUIDE_CHARS)—preventing injection from interpolating user paths into hook commands at the source.

Git workflows follow 'rule-based gates + state explanation' rather than automatic execution: perform ff-only pull only when clean; when local changes or diverged history exist, automatic stash/merge/rebase/force is forbidden in favor of explaining the state.

auto-repo-setup/SKILL.md

If the working tree is clean, run git pull --ff-only.

Operating principles enforce matching constraints: 'Never auto-stash, merge, rebase, force, discard, or overwrite local changes to make setup look successful.' Destructive or public operations (public push, force push, history rewrite) all require explicit approval.

Sensitive history cleanup performs read-only candidate scanning only, leaving remediation to humans: sanitize_history.sh describes itself as an 'assistive check only', and SKILL.md requires scan results to be treated as candidates, never executing rewrite commands without authorization.

auto-repo-setup/scripts/sanitize_history.sh

# 注意：此脚本只辅助检查，最终修复（orphan branch / BFG）需要人工确认后执行。

The script scans four areas: common secret patterns (e.g., sk- prefix), personal absolute paths, private domains, and the current workspace, outputting issue counts and remediation advice with --check-only providing a read-only exit.

2Core Capabilities

01Read-only, stack-aware repository capability inventory (check_env.py, exit codes 0/1/2 indicating available/missing/cannot check)

02Root-cause repair closed loop: record three outputs of failed commands → trace back to declaration source → minimal fix → rerun verification → execute real smoke/startup commands

03Standard Git synchronization (pull --ff-only only when clean; dirty trees/divergences are explained rather than automatically resolved)

04Registration, diagnosis, and removal of managed SessionStart hooks (idempotent, atomic writes, --dry-run preview, --remove)

05Repository handover/onboarding audit: complete missing operational contracts using onboarding_template.md as a checklist

06Read-only scanning of Git history for sensitive data (sanitize_history.sh) and public release review guidelines (pii_guard.md)

07Counter-review boundary: dispatch counter-reviews only when impacting security policies, shared hooks, CI, dependencies, or destructive Git actions; standard setups do not dispatch team reviews

3External Dependencies

Kind	Dependency / Endpoint
cli	git
cli	python3 / uv
cli	sh/bash

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local scripts or commands: auto-repo-setup/scripts/check_env.py
本地工作目录: File I/O and artifact output: init_session_start_hook.py writes to .claude/settings.json within the repository upon user confirmation (managed SessionStart)

Audit Notes: Includes built-in stdlib/local scripts (check_env read-only detection, sanitize_history read-only scan) + writes to local configuration (.claude/settings.json, .gitignore), with zero outbound network calls and zero credential access (check_env docstring explicitly specifies it never reads secret values). Hook registration modifies user configuration, but provides dry-run previews, idempotent atomic writes, and --remove, with SKILL.md requiring diagnosis and user confirmation prior to installation. Note: SKILL allows agents to execute Git commit/push operations, but destructive actions require explicit approval; heuristic matches in sanitize_history may produce false positives/negatives and should only be treated as candidates.

5Second-Pass Verification

[ok] check_env.py 只读且不碰 secret — docstring 含『reads secret values』否定句 + 代码仅 git rev-parse/which/shutil.which 探测 + token 扫描零命中。
[ok] init_session_start_hook.py 行为与 SKILL.md 描述一致（幂等/保留无关设置/原子写） — 脚本 load_settings 校验 JSON 结构并保留 hooks 其余键；update_settings/atomic_write 存在；SKILL.md 原文含『preserves unrelated settings … writes atomically, and is idempotent』同义描述。
[ok] sanitize_history.sh 永不改写历史 — 脚本头注释『此脚本只辅助检查，最终修复（orphan branch / BFG）需要人工确认后执行』；修复建议仅 echo 输出。
[ok] Git 门禁（ff-only/不自动 stash/显式批准）有源码依据 — SKILL.md Workflow B 逐条原文存在；Operating principle 4『Never auto-stash, merge, rebase, force, discard, or overwrite local changes…』存在。
[ok] 无网络外发声明 — scripts/ 三文件 token 扫描仅命中 BFG 文档 URL（输出文案），无任何 fetch/request/curl 调用点。
[ok] 外部依赖清单（git/python/uv/sh）真实存在 — git：check_env run_cmd 数组含 git；python/uv：SKILL.md 命令与脚本 shebang；sh：sanitize_history.sh shebang。
[ok] 功能声明 vs 夸大检查 — description 承诺的『Diagnose, repair, and standardize repository setup and safe Git workflows』全部由路由表+脚本+门禁兑现；反例扫描未见越界承诺（无自动破坏性操作、无网络工具）。
[ok] 元数据（license/stars/commit） — 仓库根 LICENSE 为 MIT (c) 2025 daymade；GitHub API stars=1385、pushed_at=2026-09-09T12:33:29Z；本地 HEAD==pin d5c4678cb5d4fd6acc9c922690df035dbd33d247。

6Verdict & Scenarios

Evidence-driven repair loop: inventory gap → minimal fix → real smoke verification, defining a falsifiable standard of success rather than assuming 'installation equals success'.

Minimal mechanism and read-only-first principles prevent harm: no monolithic reinstalls, no automatic modification of user working trees, and hooks are installed only when strictly necessary and confirmed by the user.

Git safety gates prevent self-inflicted damage: ff-only pull only when clean, explain dirty trees/divergences, and require explicit approval for destructive actions.

Engineered hook governance: managed markers, dry-run, atomic writes, idempotency, and --remove, while forbidding blind cross-host porting (preventing Codex pollution).

Treats 'setup' as a repository task rather than a persona task: avoids inventing tools based on job titles, handling requests according to actual user-expressed needs and technical scope.

Best for: Suitable for: Claude Code or Codex users whose repositories will not run on a new machine, teams needing reproducible handovers for onboarding colleagues, users diagnosing duplicate startup outputs from hooks, or those needing a controlled workflow for commit/push/conflict/history cleanup. Also suitable for teams wanting to consolidate routine startup actions like 'sync before work' into AGENTS.md/CLAUDE.md instead of accumulating hooks.

Not for: Not suitable for repositories already fully covered by AGENTS.md/CLAUDE.md (the skill recommends following project instructions directly); not suitable for users seeking fully automated, unprompted CI-style fixes (it enforces read-only diagnosis, explicit approval, and state explanation); not suitable for directly copying Claude hook configurations into Codex (expressly forbidden by the skill; Codex users should inspect startup_automation first to verify host semantics).

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload auto-repo-setup.tar.gz

sha256: f95bf84548251fa7…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.