# Unity Project Hygiene

> Keep Unity repos stable for CI/CD with proper gitignore, LFS, and project settings

- Skill: `majiayu000/unity-project-hygiene` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/unity-project-hygiene`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/unity-project-hygiene/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/unity-project-hygiene

---


# Unity Project Hygiene Skill

Maintain a clean, CI-friendly Unity repository.

> **See also**: [Shared Conventions](../shared/CONVENTIONS.md) | [Safety Guidelines](../shared/SAFETY.md)

## Purpose

Keep the repository stable, fast to clone, and ready for automated builds.

## Git LFS

### When to Use LFS

Large binary files that change infrequently:
- Textures (`.png`, `.jpg`, `.psd`, `.tga`)
- Audio (`.wav`, `.mp3`, `.ogg`)
- 3D models (`.fbx`, `.obj`, `.blend`)
- Video (`.mp4`, `.mov`)

### Setup LFS

```bash
# Install LFS
git lfs install

# Track file types
git lfs track "*.png"
git lfs track "*.jpg"
git lfs track "*.psd"
git lfs track "*.wav"
git lfs track "*.mp3"
git lfs track "*.fbx"
git lfs track "*.blend"

# Commit .gitattributes
git add .gitattributes
git commit -m "Configure Git LFS for binary assets"
```

### Verify LFS

```bash
# List tracked patterns
git lfs track

# List LFS files
git lfs ls-files

# Check file is LFS-tracked
git lfs pointer --check Assets/Textures/large.png
```

## .gitignore

### Required Unity Ignores

```gitignore
# Unity generated
/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Bb]uild/
/[Bb]uilds/
/[Ll]ogs/
/[Uu]ser[Ss]ettings/

# Memory captures
/[Mm]emoryCaptures/

# Asset meta data should be committed (don't ignore .meta)

# Autogenerated VS/Rider files
.vs/
.idea/
*.csproj
*.unityproj
*.sln
*.suo
*.tmp
*.user
*.userprefs
*.pidb
*.booproj

# Build results
*.apk
*.aab
*.unitypackage
*.app

# Crashlytics
crashlytics-build.properties

# OS files
.DS_Store
Thumbs.db
```

### Verify .gitignore Working

```bash
# Check if ignored
git check-ignore -v Library/
git check-ignore -v Temp/

# List untracked files (should not show Library, Temp, etc.)
git status --porcelain
```

## ProjectSettings Sanity

### Key Files to Track

```
ProjectSettings/
  ProjectSettings.asset      # Most settings
  EditorBuildSettings.asset  # Build scenes
  TagManager.asset           # Tags and layers
  InputManager.asset         # Input settings
  QualitySettings.asset      # Quality levels
  GraphicsSettings.asset     # Rendering
```

### Verify No Local-Only Settings

```bash
# Check for user-specific paths or settings
grep -r "Users/\|C:\\\|/home/" ProjectSettings/
```

### Required Settings for CI

In `ProjectSettings/ProjectSettings.asset`:

```yaml
# Enable visible meta files
  externalVersionControlSupport: Visible Meta Files

# Force text serialization
  serializationMode: 2  # 2 = Force Text

# Set scripting backend for target platform
  scriptingBackend:
    Standalone: 1  # 1 = IL2CPP, 0 = Mono
```

## Packages/manifest.json

### Verify Package Versions

```bash
cat Packages/manifest.json | python3 -c "import json,sys; d=json.load(sys.stdin); print('\n'.join(f'{k}: {v}' for k,v in sorted(d.get('dependencies',{}).items())))"
```

### Lock File

`Packages/packages-lock.json` should be committed for reproducible builds.

### Common Issues

```bash
# Check for git URLs (may need auth in CI)
grep "git+" Packages/manifest.json

# Check for local paths (won't work in CI)
grep "file:" Packages/manifest.json
```

## CI Gates

### Build Script Check

Verify build script exists and is callable:
```bash
grep -r "static void.*Build\|static void.*CI" Assets/Editor/
```

### Test Script Check

```bash
grep -r "UnityTest\|\[Test\]" Assets/Tests/
```

### Pre-commit Checklist

```bash
# 1. No uncommitted changes to critical files
git diff --name-only | grep -E "manifest.json|ProjectSettings"

# 2. Library not committed
git ls-files | grep -i "^Library/" && echo "ERROR: Library committed!"

# 3. Meta files present for all assets
find Assets -type f ! -name "*.meta" -exec sh -c 'test -f "$1.meta" || echo "Missing: $1.meta"' _ {} \;
```

## Workflow: New Project Setup

```bash
# 1. Initialize repo
git init
git lfs install

# 2. Add .gitignore
# (copy from above)

# 3. Configure LFS
git lfs track "*.png" "*.jpg" "*.psd" "*.wav" "*.mp3" "*.fbx"
git add .gitattributes

# 4. Verify settings
grep "serializationMode: 2" ProjectSettings/ProjectSettings.asset || echo "WARNING: Not force text!"

# 5. Initial commit
git add -A
git commit -m "Initial Unity project setup"
```

## Workflow: Pre-PR Check

```bash
# 1. Verify clean state
git status

# 2. Check no binaries without LFS
git diff --cached --name-only | xargs -I{} sh -c 'file -b "{}" | grep -q "data\|image" && echo "Binary: {}"'

# 3. Verify project compiles
unity -quit -batchmode -nographics -projectPath . -logFile /tmp/check.log
echo "Exit: $?"
```

## Policies

- **Always commit .meta files** - Unity needs them for asset references
- **Never commit Library/** - it's regenerated
- **Use LFS for binaries** - keeps repo fast
- **Force text serialization** - enables meaningful diffs
- **Lock package versions** - reproducible builds