# Unity Asset

> Manage Unity AssetDatabase operations

- Skill: `datnt-cell/unity-asset` (Agent Skill)
- Install (CLI): `npx skillmds@latest add datnt-cell/unity-asset`
- Raw SKILL.md: https://api.skillmd.com/api/skills/datnt-cell/unity-asset/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: datnt-cell (https://skillmd.com/u/datnt-cell)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/datnt-cell/unity-asset

---


> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

## Triggers
- Organizing project assets
- Importing or relocating files
- Querying asset metadata
- Scripting AssetDatabase operations
- 整理工程资源、导入或移动文件、查询资源元数据、脚本化 AssetDatabase 操作

# Unity Asset Skills

> **BATCH-FIRST**: Use `*_batch` skills when operating on 2+ assets.

## Operating Mode

- **Approval**：本模块 Mixed —— `asset_find` / `asset_get_info` / `asset_get_labels` 标 `SkillMode.SemiAuto`，可直接执行；写类 skill (`asset_move` / `asset_move_batch` / `asset_duplicate` / `asset_create_folder` / `asset_create_folder_batch` / `asset_refresh` / `asset_reimport*` / `asset_set_labels`) 走默认 `SkillMode.FullAuto`，需 grant。
- **Auto / Bypass**：FullAuto 直接执行。
- **含 NeverInSemi 高危 skill**：`asset_import` / `asset_import_batch` (标 `RiskLevel = "high"` —— 写入项目)；`asset_delete` / `asset_delete_batch` (Operation.Delete)。这些在 Approval/Auto 下返 `MODE_FORBIDDEN`，仅 Bypass 或 Allowlist 命中可调。

**DO NOT** (common hallucinations):
- `asset_create` does not exist → use `asset_create_folder` (folders), `material_create` (materials), `script_create` (scripts)
- `asset_rename` does not exist → use `asset_move` with new path
- `asset_search` does not exist → use `asset_find` with searchFilter syntax (e.g. `t:Texture2D player`)
- `asset_copy` does not exist → use `asset_duplicate`

**Routing**:
- For texture/model/audio import settings → use `importer` module (SkillMode.FullAuto)
- For material creation → use `material` module (SkillMode.FullAuto)
- For script creation → use `script` module

## Skills Overview

| Single Object | Batch Version | Use Batch When |
|---------------|---------------|----------------|
| `asset_import` | `asset_import_batch` | Importing 2+ files |
| `asset_delete` | `asset_delete_batch` | Deleting 2+ assets |
| `asset_move` | `asset_move_batch` | Moving 2+ assets |
| `asset_create_folder` | `asset_create_folder_batch` | Creating 2+ folders |

**No batch needed**:
- `asset_duplicate` - Duplicate single asset
- `asset_find` - Search assets (returns list)
- `asset_refresh` - Refresh AssetDatabase
- `asset_get_info` - Get asset information
- `asset_reimport` - Force reimport asset
- `asset_reimport_batch` - Reimport multiple assets

---

## Skills

### asset_import
Import an external file into the project.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sourcePath` | string | Yes | External file path |
| `destinationPath` | string | Yes | Project destination |

### asset_import_batch
Import multiple external files.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `items` | json string | Yes | - | JSON array of per-item objects (see example below) |


`items` currently expects a JSON string, not a native array.

**Returns**: `{success, totalItems, successCount, failCount, results: [{success, sourcePath, destinationPath}]}`

```python
import json

unity_skills.call_skill("asset_import_batch", items=json.dumps([
    {"sourcePath": "C:/Downloads/tex1.png", "destinationPath": "Assets/Textures/tex1.png"},
    {"sourcePath": "C:/Downloads/tex2.png", "destinationPath": "Assets/Textures/tex2.png"}
]))
```

### asset_delete
Delete an asset from the project.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assetPath` | string | Yes | Asset path to delete |

### asset_delete_batch
Delete multiple assets.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `items` | json string | Yes | - | JSON array of per-item objects (see example below) |


`items` currently expects a JSON string, not a native array.

**Returns**: `{success, totalItems, successCount, failCount, results: [{success, path}]}`

```python
import json

unity_skills.call_skill("asset_delete_batch", items=json.dumps([
    {"path": "Assets/Textures/old1.png"},
    {"path": "Assets/Textures/old2.png"}
]))
```

### asset_move
Move or rename an asset.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `sourcePath` | string | Yes | Current asset path |
| `destinationPath` | string | Yes | New path/name |

### asset_move_batch
Move multiple assets.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `items` | json string | Yes | - | JSON array of per-item objects (see example below) |


`items` currently expects a JSON string, not a native array.

**Returns**: `{success, totalItems, successCount, failCount, results: [{success, sourcePath, destinationPath}]}`

```python
import json

unity_skills.call_skill("asset_move_batch", items=json.dumps([
    {"sourcePath": "Assets/Old/mat1.mat", "destinationPath": "Assets/New/mat1.mat"},
    {"sourcePath": "Assets/Old/mat2.mat", "destinationPath": "Assets/New/mat2.mat"}
]))
```

### asset_duplicate
Duplicate an asset.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assetPath` | string | Yes | Asset to duplicate |

### asset_find
Find assets by search filter.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `searchFilter` | string | Yes | - | Search query |
| `limit` | int | No | 50 | Max results to return |

**Search Filter Syntax**:
| Filter | Example | Description |
|--------|---------|-------------|
| `t:Type` | `t:Texture2D` | By type |
| `l:Label` | `l:Architecture` | By label |
| `name` | `player` | By name |
| Combined | `t:Material player` | Multiple filters |

**Returns**: `{count, totalFound, assets: [{path, name, type}]}`

### asset_create_folder
Create a folder in the project.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `folderPath` | string | Yes | Full folder path |

### asset_create_folder_batch
Create multiple folders.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `items` | json string | Yes | - | JSON array of per-item objects (see example below) |


`items` currently expects a JSON string, not a native array. The parent folder of each entry must already exist, so order nested folders outermost-first within one call.

**Returns**: `{success, totalItems, successCount, failCount, results: [{target, success, path, guid}]}`

```python
import json

unity_skills.call_skill("asset_create_folder_batch", items=json.dumps([
    {"folderPath": "Assets/Art"},
    {"folderPath": "Assets/Art/Textures"}
]))
```

### asset_refresh
Refresh the AssetDatabase after external changes.

No parameters.

### asset_get_info
Get information about an asset.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assetPath` | string | Yes | Asset path |

### asset_reimport
Force reimport of an asset.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assetPath` | string | Yes | Asset path to reimport |

### asset_reimport_batch
Reimport multiple assets matching a pattern.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `searchFilter` | string | No | AssetDatabase search filter (default `*`) |
| `folder` | string | No | Folder root to search (default `Assets`) |
| `limit` | int | No | Max assets to reimport (default `100`) |

### asset_set_labels
Set labels on an asset (overwrites existing labels).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assetPath` | string | Yes | Asset path |
| `labels` | string | Yes | Comma-separated labels (e.g. `"ui,icon,hud"`). Empty entries are dropped |

**Returns**: `{success, assetPath, labels: [...]}`

### asset_get_labels
Get the labels currently attached to an asset.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assetPath` | string | Yes | Asset path |

**Returns**: `{success, assetPath, labels: [...]}`

---

## Minimal Example

```python
import unity_skills

# GOOD: 1 API call instead of 4
unity_skills.call_skill("asset_move_batch", items=[
    {"sourcePath": "Assets/tex1.png", "destinationPath": "Assets/Textures/tex1.png"},
    {"sourcePath": "Assets/tex2.png", "destinationPath": "Assets/Textures/tex2.png"},
    {"sourcePath": "Assets/tex3.png", "destinationPath": "Assets/Textures/tex3.png"},
    {"sourcePath": "Assets/tex4.png", "destinationPath": "Assets/Textures/tex4.png"}
])
```

## Best Practices

1. Organize assets in logical folders
2. Use consistent naming conventions
3. Refresh after external file changes
4. Use search filters for efficiency
5. Backup before bulk delete operations

---
## Exact Signatures

Exact names, parameters, defaults, and returns are defined by `GET /skills/schema` or `unity_skills.get_skill_schema()`, not by this file.

## Common Errors

Full transport-level codes (COMPILING/RATE_LIMIT etc.) are in the unity-core plugin (optional), references/protocol-error-codes.md.

| Error | Trigger | Fix |
|---|---|---|
| `TARGET_NOT_FOUND` | The source file, asset path, or target asset could not be found. | Verify the path with `asset_find` / `asset_get_info`, ensure the file exists, and retry with the exact project-relative path. |
| `MISSING_PARAM` | A required path parameter is empty or not provided (caught by path validation). | Provide the required `assetPath`, `sourcePath`, `destinationPath`, or `folderPath`. |
| `SEMANTIC_INVALID` | The path is invalid (e.g., contains `..`, does not start with `Assets/`/`Packages/`, or the folder already exists). | Use a normalized project-relative path under `Assets/` or `Packages/`; choose a different folder name if it already exists. |
| `SKILL_ERROR` | A low-level AssetDatabase or filesystem operation failed, such as `Failed to delete asset`, `AssetDatabase.MoveAsset` returned an error, or folder creation failed. | Resolve the issue described in the message (e.g., close locked files, fix parent path) and retry. |