Skip to content
Back to search

vrchat-avatar-modding-skills

Battle-tested Agent Skills + Unity MCP + Blender MCP toolkit for safe, non-destructive VRChat avatar modding

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/asmrawa--vrchat-avatar-modding-skills/badge.svg)](/listings/asmrawa--vrchat-avatar-modding-skills)

HTML

<a href="/listings/asmrawa--vrchat-avatar-modding-skills"><img src="/api/listings/asmrawa--vrchat-avatar-modding-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Clone the repository (or download individual skill ZIPs from [GitHub Releases](https://github.com/asmrawa/vrchat-avatar-modding-skills/releases)) into a fixed folder such as `C:/Tools/vrchat-avatar-modding-skills`. Run commands below from the repo root.

Step 1: Install the Skills

**Windows (PowerShell):**

# Choose: codex | antigravity | cursor | all
.\install.ps1 -Client codex

# Optional: also install Unity MCP Node dependencies and the Blender add-on
.\install.ps1 -Client all -InstallUnityMcpDeps -InstallBlenderAddon

**macOS / Linux:**

chmod +x install.sh
./install.sh codex   # or: antigravity | cursor | all

Step 2: Connect Unity MCP

1. Open your VRChat Unity project with its matching Unity version. 2. Go to `Window -> Package Manager -> + -> Add package from disk...` and select [`unity-mcp/unity-mcp-plugin/package.json`](unity-mcp/unity-mcp-plugin/package.json). 3. After compilation, open `Window -> AB Unity MCP` and confirm `Server Running` (default port range `7890-7899`). 4. Install locked Node.js server dependencies:

   $toolkit = (Get-Location).Path
   $unityDir = Join-Path $toolkit 'unity-mcp/unity-mcp-server'
   $nodeExe = (Get-Command node.exe -ErrorAction Stop).Source
   $unityEntry = Join-Path $unityDir 'src/index.js'
   Push-Location -LiteralPath $unityDir
   try { npm.cmd ci --omit=dev --ignore-scripts } finally { Pop-Location }

5. Register the server in your client: - **Codex CLI**: `codex mcp add unity_mcp -- "$nodeExe" "$unityEntry"` (or merge [`config/codex.config.example.toml`](config/codex.config.example.toml)) - **Antigravity / Cursor / JSON MCP clients**: Merge the `unity-mcp` block from [`config/antigravity_mcp.example.json`](config/antigravity_mcp.example.json) with your local paths. 6. Restart your client and verify with `unity_list_instances`.

Step 3: Connect Blender MCP (Optional)

1. Install **Blender** and **[uv](https://docs.astral.sh/uv/getting-started/installation/)**. 2. Install the bundled Blender add-on:

   $toolkit = (Get-Location).Path
   $uvxExe = (Get-Command uvx.exe -ErrorAction Stop).Source
   $wheel = Join-Path $toolkit 'blender-mcp/mcp_for_blender-2.3.1-py3-none-any.whl'
   & $uvxExe --from $wheel mcp-for-blender install-addon

*(Or install [`blender-mcp/mcp_for_blender_addon.py`](blender-mcp/mcp_for_blender_addon.py) via Blender `Preferences -> Add-ons -> Install from Disk`.)* 3. Enable `MCP for Blender` in Blender Preferences, press `N` in the 3D Viewport, and click `Start MCP Server` (or launch headless with [`blender_mcp_headless.py`](skills/vrchat-clothing-rebuild/scripts/blender_mcp_headless.py)). 4. Register in your client: - **Codex CLI**: `codex mcp add blender --env BLENDER_MCP_SAFE_MODE=1 --env DISABLE_TELEMETRY=true -- "$uvxExe" --from "$wheel" mcp-for-blender` - **Antigravity / Cursor / JSON MCP clients**: Merge the `blender` block from [`config/antigravity_mcp.example.json`](config/antigravity_mcp.example.json).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 221 lines
  1. # VRChat Avatar Modding Skills & MCP Toolkit
  2. [![Toolkit QA & Tests](https://github.com/asmrawa/vrchat-avatar-modding-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/asmrawa/vrchat-avatar-modding-skills/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. [![VRChat SDK3](https://img.shields.io/badge/VRChat-SDK3%20%7C%20MA%20%7C%20NDMF-purple.svg)](https://creators.vrchat.com/avatars/)
  5. **English** | [简体中文](README_CN.md) | [日本語](README_JA.md)
  6. An end-to-end **Agent Skills + Unity MCP + Blender MCP** toolkit that turns AI coding assistants (**Codex**, **Antigravity**, **Cursor**, and any Agent Skills / MCP client) into a structured, non-destructive VRChat avatar modding workflow.
  7. Instead of letting an AI guess Unity YAML or overwrite vendor prefabs, this toolkit gives it **live Unity & Blender control**, **deterministic C#/Python helpers**, and **modular VRChat engineering playbooks**.
  8. ---
  9. ## What It Can Do
  10. | Area | Capabilities |
  11. | --- | --- |
  12. | **Outfits, Hair & Multi-Outfit Wardrobes** | Attach adapted outfits and hairstyles via Modular Avatar / NDMF, wire mutually exclusive `Int` wardrobes, split shared skinned meshes (e.g., shoes & socks), relocate shared accessories across outfits with rest-pose-preserving bind-pose math, and fix AFK/action visibility issues. |
  13. | **Expression Menus, Parameters & FX Toggles** | Build independent `Bool` toggles, `Int` selectors, linked rules (e.g., hiding ears when a hat is active and restoring them cleanly), hand-prop exclusions, label translations without breaking parameters, and enforce VRChat's 8-controls/page & 256-bit synced limits. |
  14. | **Texture & PSD Editing (Photoshop + Pillow + GPT Image)** | Edit layered `.psd` files non-destructively (preserving author groups/masks for future manual editing), recolor UV islands via grayscale masks, add transparent decals/lettering, or repaint irises/hair streaks/embroidery with GPT Image and composite them back pixel-locked onto the original UV atlas. |
  15. | **Props, Lighting, Fit & Optimization** | Align handheld props, Contacts, and constraints to real poses; unify material lighting and `probeAnchor` references across worlds; audit PhysBones, particle capacities, Mip Streaming, Write Defaults, and SDK build/upload errors. |
  16. | **Blender Garment Rebuild** | Reconstruct torso-fitted clothing meshes in Blender for modified body shapes while preserving original UVs, materials, and skin weights, render 3-angle orthographic previews, and import back into Unity automatically. |
  17. | **Read-Only Project Audit & Safe Repair** | Inspect any VRChat Unity project without modifying files—tracing scenes, prefabs, `{fileID, guid}` references, Animator curves, and post-NDMF build output—and perform minimal, scoped repairs only when explicitly requested. |
  18. ---
  19. ## How Each Workflow Works Under The Hood
  20. ```mermaid
  21. flowchart LR
  22. User["Your Request"] --> Client["AI Client (Codex / Antigravity / Cursor)"]
  23. Client --> S1["Skill 1: vrchat-avatar-modding"]
  24. Client --> S2["Skill 2: vrchat-project-audit-and-repair"]
  25. Client --> S3["Skill 3: vrchat-clothing-rebuild"]
  26. S1 --> UMCP["Unity MCP Bridge"]
  27. S2 --> UMCP
  28. S1 --> CLI["Python & C# Helpers"]
  29. S3 --> BMCP["Blender MCP / Background Python"]
  30. S3 --> UMCP
  31. UMCP --> Work["Versioned Assets/VRCWork/ + NDMF Verification"]
  32. CLI --> Work
  33. BMCP --> Work
  34. ```
  35. ### 1. Safe Non-Destructive Unity Automation
  36. - **Live Editor Control**: The bundled **AnkleBreaker Unity MCP** bridges your AI client directly to the running Unity Editor (supporting multi-instance discovery and dynamic port selection). The AI inspects real `VRCAvatarDescriptor`, Modular Avatar components, renderers, materials, and Animator states instead of guessing from text files.
  37. - **Strict Isolation**: Vendor assets (`Assets/<Vendor>/`) are never edited. Every modification creates a versioned work scene and asset folder under `Assets/VRCWork/` and saves only owned dirty assets (`AssetDatabase.SaveAssetIfDirty`), keeping prior versions intact for instant rollback.
  38. - **3-Layer Verification**: Every check distinguishes between **(1) static YAML/GUID files**, **(2) Unity Editor resolved state**, and **(3) NDMF / Modular Avatar / AAO build-resolved output**. Animation/pose checks run on temporary clones so the work scene's rest skeleton is never altered.
  39. - **Bundled C# Primitives**: Reusable helpers ([`VrcAvatarIntegration.cs`](skills/vrchat-avatar-modding/scripts/VrcAvatarIntegration.cs), [`VrcMaterialSwap.cs`](skills/vrchat-avatar-modding/scripts/VrcMaterialSwap.cs)) handle clip/controller cloning, float-allowlist lighting copies, rest-pose-invariant skin rebinding, and safe material swaps.
  40. ### 2. How Texture & PSD Editing Works (PSD-First Pipeline)
  41. Texture changes follow one unified pipeline in [`psd-texture-workflow.md`](skills/vrchat-avatar-modding/references/psd-texture-workflow.md):
  42. 1. **Locate the true texture in Unity**: Identify the exact renderer, submesh, material slot, shader properties (`_MainTex`, `_EmissionMap`, overlays), and any FX animation curves swapping materials on that slot.
  43. 2. **PSD First (when a matching `.psd` exists)**: Copy the registered `.psd` into a versioned work file and edit via independent layers and masks—**never flattening author groups, line art, or shading**—so you can always open the PSD in Photoshop later and keep tweaking it yourself.
  44. 3. **Flattened PNG / AI-Assisted Editing (when no PSD exists, or when painting new motifs)**:
  45. - **Color / palette shift**: [`vrc_texture_tool.py`](skills/vrchat-avatar-modding/scripts/vrc_texture_tool.py) `recolor` maps source luminance to a new shadow/midtone/highlight ramp inside a grayscale mask.
  46. - **Transparent decals & lettering**: `vrc_texture_tool.py composite --decal` blends a source-sized RGBA layer through the island mask without creating opaque backing boxes.
  47. - **New painted art (irises, hair highlights, embroidery)**: [`vrc_gpt_texture_edit.py`](skills/vrchat-avatar-modding/scripts/vrc_gpt_texture_edit.py) (or a host image tool / prompt-only ChatGPT workflow) edits the original atlas using dual masks (an API guidance mask + a pixel-exact delivery mask). The result can be placed onto a new masked PSD layer or composited onto the PNG after `clean-bg` gutter cleanup.
  48. 4. **Automated Pixel & Unity Verification**: `vrc_texture_tool.py compare` verifies exact dimensions, `outside_mask=0`, `alpha_changed=0`, visible RGB change, and PNG ICC/sRGB metadata before binding via `VrcMaterialSwap.cs` and testing on the avatar's attached `Animator` in Unity.
  49. ### 3. How Blender Clothing Rebuild Works
  50. For outfits that no longer match a modified torso silhouette ([`vrchat-clothing-rebuild`](skills/vrchat-clothing-rebuild/SKILL.md)):
  51. 1. [`fit_clothing.py`](skills/vrchat-clothing-rebuild/scripts/fit_clothing.py) runs in Blender background mode, projects the garment's main shell onto the evaluated target body mesh via ray casting with smoothstep collar/sleeve/waist falloff, transfers displacement to attached ornaments via KD-tree weighting, and renders 3 orthographic previews (front, side, quarter) while preserving vertex order, UVs, materials, and vertex groups.
  52. 2. After you inspect and approve the previews, [`install_unity.py`](skills/vrchat-clothing-rebuild/scripts/install_unity.py) backs up the work scene and stages a verified one-shot Unity C# importer that maps vertex deltas onto the original Unity FBX mesh, clones its UVs, bone weights, and bind poses into a new work mesh asset, assigns it, and reports completion.
  53. 3. Optional headless Blender MCP support is included via [`blender_mcp_headless.py`](skills/vrchat-clothing-rebuild/scripts/blender_mcp_headless.py).
  54. ### 4. Account & Upload Safety
  55. - SDK builds, previews, and online uploads are strictly separated and only run on explicit request.
  56. - VRChat SDK login, passwords, 2FA, CAPTCHA, and ownership agreements are **always handled manually by you** in Unity's visible SDK Control Panel—credentials are never stored, logged, or typed by scripts.
  57. ---
  58. ## Prerequisites: What You Need
  59. | Component | Status | Why It Is Needed |
  60. | --- | --- | --- |
  61. | **AI Client** (Codex / Antigravity / Cursor / compatible client) | Required | Loads the 3 Agent Skills and connects to MCP servers. |
  62. | **Unity Editor + VRChat SDK3 (Avatars)** | Required | Your VRChat project (exact Unity version in `ProjectSettings/ProjectVersion.txt`). Modular Avatar, NDMF, lilToon/Poiyomi, Gesture Manager, and Avatar Optimizer are recommended. |
  63. | **Node.js >= 18** | Required for Unity MCP | Runs the bundled `unity-mcp/unity-mcp-server` Node bridge (verified on Node.js 24). |
  64. | **Python >= 3.10** | Required for CLI tools | Runs offline Blueprint/budget/log audits, texture tools, clothing scripts, and `doctor.py`. |
  65. | **Pillow (`pip install pillow`)** | Optional (Texture editing) | Required by `vrc_texture_tool.py` (`recolor`, `composite`, `clean-bg`, `compare`). |
  66. | **Photoshop / PSD editor (or `psd-tools`)** | Optional (PSD editing) | Recommended for interactive layered `.psd` editing and exporting. |
  67. | **OpenAI-compatible Images API Key** | Optional (Mode A AI art) | Only needed for direct API calls via `vrc_gpt_texture_edit.py`; Mode B (host image tool) and Mode C (prompt-only) need no API key. |
  68. | **Blender + `uv` (`uvx`)** | Optional (Mesh/clothing) | Required only for Blender MCP and `vrchat-clothing-rebuild`. |
  69. Check everything installed on your machine in one command:
  70. ```powershell
  71. python -X utf8 scripts/doctor.py
  72. ```
  73. ---
  74. ## Included Skills & Repository Layout
  75. | Skill | When To Use | Entry File |
  76. | --- | --- | --- |
  77. | **`vrchat-avatar-modding`** | Main modding: outfits, wardrobes, menus/FX, props, PSD/AI textures, lighting/fit, optimization, SDK build triage | [`skills/vrchat-avatar-modding/SKILL.md`](skills/vrchat-avatar-modding/SKILL.md) |
  78. | **`vrchat-project-audit-and-repair`** | Read-only project inspection (static YAML/GUID, live Unity MCP, `-batchmode`, NDMF build) + explicit-only safe repair & cleanup | [`skills/vrchat-project-audit-and-repair/SKILL.md`](skills/vrchat-project-audit-and-repair/SKILL.md) |
  79. | **`vrchat-clothing-rebuild`** | Blender torso-fit mesh reconstruction, 3-angle previews, and verified Unity re-import preserving weights & UVs | [`skills/vrchat-clothing-rebuild/SKILL.md`](skills/vrchat-clothing-rebuild/SKILL.md) |
  80. ```text
  81. vrchat-avatar-modding-skills/
  82. ├── skills/
  83. │ ├── vrchat-avatar-modding/ # Main workflow + 10 references + 7 C#/Python scripts
  84. │ ├── vrchat-project-audit-and-repair/ # 3-layer audit + symptom triage + safe repair
  85. │ └── vrchat-clothing-rebuild/ # Blender rebuild pipeline + Unity importer + headless MCP
  86. ├── unity-mcp/ # Bundled AnkleBreaker Unity MCP plugin (2.32.0) & server (2.30.0)
  87. ├── blender-mcp/ # Bundled MCP for Blender (2.3.1 wheel + add-on)
  88. ├── config/ # MCP config examples (Codex TOML, generic JSON)
  89. ├── templates/ # Sanitized multi-session handoff template
  90. ├── scripts/ # doctor.py, validate_toolkit.py, package_skills.py
  91. ├── tests/ # 20 automated unit tests
  92. ├── install.ps1 / install.sh # One-click installers (Windows / macOS / Linux)
  93. └── THIRD_PARTY_NOTICES.md # Full upstream attributions & licenses
  94. ```
  95. > All `SKILL.md` and `references/` files are written in concise English to save tokens and maximize cross-client accuracy; you can still chat and give instructions in Chinese, Japanese, English, or any language.
  96. ---
  97. ## Quick Start
  98. Clone the repository (or download individual skill ZIPs from [GitHub Releases](https://github.com/asmrawa/vrchat-avatar-modding-skills/releases)) into a fixed folder such as `C:/Tools/vrchat-avatar-modding-skills`. Run commands below from the repo root.
  99. ### Step 1: Install the Skills
  100. **Windows (PowerShell):**
  101. ```powershell
  102. # Choose: codex | antigravity | cursor | all
  103. .\install.ps1 -Client codex
  104. # Optional: also install Unity MCP Node dependencies and the Blender add-on
  105. .\install.ps1 -Client all -InstallUnityMcpDeps -InstallBlenderAddon
  106. ```
  107. **macOS / Linux:**
  108. ```bash
  109. chmod +x install.sh
  110. ./install.sh codex # or: antigravity | cursor | all
  111. ```
  112. ### Step 2: Connect Unity MCP
  113. 1. Open your VRChat Unity project with its matching Unity version.
  114. 2. Go to `Window -> Package Manager -> + -> Add package from disk...` and select [`unity-mcp/unity-mcp-plugin/package.json`](unity-mcp/unity-mcp-plugin/package.json).
  115. 3. After compilation, open `Window -> AB Unity MCP` and confirm `Server Running` (default port range `7890-7899`).
  116. 4. Install locked Node.js server dependencies:
  117. ```powershell
  118. $toolkit = (Get-Location).Path
  119. $unityDir = Join-Path $toolkit 'unity-mcp/unity-mcp-server'
  120. $nodeExe = (Get-Command node.exe -ErrorAction Stop).Source
  121. $unityEntry = Join-Path $unityDir 'src/index.js'
  122. Push-Location -LiteralPath $unityDir
  123. try { npm.cmd ci --omit=dev --ignore-scripts } finally { Pop-Location }
  124. ```
  125. 5. Register the server in your client:
  126. - **Codex CLI**: `codex mcp add unity_mcp -- "$nodeExe" "$unityEntry"` (or merge [`config/codex.config.example.toml`](config/codex.config.example.toml))
  127. - **Antigravity / Cursor / JSON MCP clients**: Merge the `unity-mcp` block from [`config/antigravity_mcp.example.json`](config/antigravity_mcp.example.json) with your local paths.
  128. 6. Restart your client and verify with `unity_list_instances`.
  129. ### Step 3: Connect Blender MCP (Optional)
  130. 1. Install **Blender** and **[uv](https://docs.astral.sh/uv/getting-started/installation/)**.
  131. 2. Install the bundled Blender add-on:
  132. ```powershell
  133. $toolkit = (Get-Location).Path
  134. $uvxExe = (Get-Command uvx.exe -ErrorAction Stop).Source
  135. $wheel = Join-Path $toolkit 'blender-mcp/mcp_for_blender-2.3.1-py3-none-any.whl'
  136. & $uvxExe --from $wheel mcp-for-blender install-addon
  137. ```
  138. *(Or install [`blender-mcp/mcp_for_blender_addon.py`](blender-mcp/mcp_for_blender_addon.py) via Blender `Preferences -> Add-ons -> Install from Disk`.)*
  139. 3. Enable `MCP for Blender` in Blender Preferences, press `N` in the 3D Viewport, and click `Start MCP Server` (or launch headless with [`blender_mcp_headless.py`](skills/vrchat-clothing-rebuild/scripts/blender_mcp_headless.py)).
  140. 4. Register in your client:
  141. - **Codex CLI**: `codex mcp add blender --env BLENDER_MCP_SAFE_MODE=1 --env DISABLE_TELEMETRY=true -- "$uvxExe" --from "$wheel" mcp-for-blender`
  142. - **Antigravity / Cursor / JSON MCP clients**: Merge the `blender` block from [`config/antigravity_mcp.example.json`](config/antigravity_mcp.example.json).
  143. ---
  144. ## Example Prompts
  145. **1. First-time read-only project inspection:**
  146. > Use `vrchat-project-audit-and-repair`. List Unity instances, verify the active project, scene, and avatar root, then inspect Expression Menus, synced parameter cost, and FX controllers. Read-only this turn—do not modify or save anything.
  147. **2. Add a new outfit with wardrobe toggles:**
  148. > Use `vrchat-avatar-modding`. Save a new versioned work scene under `Assets/VRCWork/`, integrate the imported outfit prefab with Modular Avatar while keeping original toggles working, check NDMF baked bones and the 256-bit parameter budget, and summarize what was verified.
  149. **3. Edit avatar textures (PSD-first):**
  150. > Use `vrchat-avatar-modding` (`psd-texture-workflow.md`). Locate the active renderer, material slot, and texture in Unity first. If a matching `.psd` exists, edit a versioned PSD copy using non-destructive layers and masks without flattening; otherwise use `vrc_texture_tool.py` / GPT Image local edit with masked compositing, verify pixels and color metadata, and preview on a work material in Unity.
  151. **4. Rebuild torso-fitted clothing in Blender:**
  152. > Use `vrchat-clothing-rebuild`. Inspect the target body and garment islands in Blender, configure a torso-fit rebuild with 3-angle orthographic previews, and wait for my review before importing into Unity.
  153. > **Long multi-session projects?** Copy [`templates/AVATAR_HANDOFF_TEMPLATE.md`](templates/AVATAR_HANDOFF_TEMPLATE.md) into your private workspace to track scene versions, wardrobe parameters, and rollback points across sessions.
  154. ---
  155. ## Development & Verification
  156. ```bash
  157. python -X utf8 scripts/doctor.py
  158. python -X utf8 scripts/validate_toolkit.py
  159. python -X utf8 -m unittest discover -s tests -v
  160. python -X utf8 scripts/package_skills.py
  161. ```
  162. ---
  163. ## Licenses & Attribution
  164. - Original skills, scripts, templates, and documentation: **MIT License** ([`LICENSE`](LICENSE)).
  165. - `skills/vrchat-avatar-modding/`: Derived from [felixchaos/vrchat-avatar-modding-skill](https://github.com/felixchaos/vrchat-avatar-modding-skill) (**MIT License**).
  166. - `blender-mcp/`: Bundled from [mcp-for-blender 2.3.1](https://pypi.org/project/mcp-for-blender/2.3.1/) by Siddharth Ahuja (**MIT License**).
  167. - `unity-mcp/`: **Powered by AnkleBreaker MCP** ([unity-mcp-plugin](https://github.com/AnkleBreaker-Studio/unity-mcp-plugin) `2.32.0` · [unity-mcp-server](https://github.com/AnkleBreaker-Studio/unity-mcp-server) `2.30.0`), licensed under **AnkleBreaker Open License v1.0** (free distribution permitted; commercial resale prohibited). See [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) for complete notices.
  168. <img src="unity-mcp/unity-mcp-plugin/icon.png" alt="Powered by AnkleBreaker MCP" width="96" />
  169. > **Note**: Always use legally obtained avatar bases, outfits, shaders, and VRChat SDK packages. Never commit commercial assets, Blueprint IDs, or account credentials.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.