---
name: asset-management
description: "Asset and file management workflow: placement → naming → versioning → ledger → archiving, including an executable audit (version pile-up / semantic suffixes / version numbers inside directory names / missing cost ledger / leftovers in the default cwd). Used to answer three questions: which copy is the current version? how much was spent? which assets are reusable? Use when the user asks to save / archive / tidy files, wants a naming convention, version management or asset reuse, says the files are too messy, asks where to store something, asks to clean up files, or asks whether a copy is the final version."
---

> Original skill · commissioned by the user · English edition, 2026-11-12

# Asset Management

## 0. Positioning and boundaries

**Goal**: be able to answer three questions at any time — **which copy is the current version? how much was spent? which assets are reusable?**

| Skill | Boundary |
|---|---|
| **this skill** | structure (placement), naming, versioning, ledger, archiving — **project-agnostic** |
| `save-to-desktop` | only handles "the user says save it to the desktop" → `<DESKTOP_DIR>/<project>/` (**not re-implemented here**) |
| `workspace-hygiene` | session level: process files vs delivery files, `outputs/<date>-<topic>/` naming and INDEX registration (**its convention governs deliverable naming**) |
| `video-production-pipeline` §9 | that pipeline's own `01_script/05_assets-and-outputs/…` (the two may coexist) |
| `clip-skills` references/12 | naming and archiving of editing exports (video-specific, local) |

## 1. Five-step workflow (details in `references/02-five-step-workflow.md`)

```
① placement → ② naming → ③ versioning → ④ ledger → ⑤ archiving
```

| Step | One line | Hard requirement |
|---|---|---|
| ① **placement** | project root + fixed subdirectories (`outputs/ assets/ review/ work/ _deprecated/`) | ⛔ **important deliverables must not stay in the default cwd** (`Documents/Codex/<date>/<name>`) |
| ② **naming** | `type_project_shot_version_spec.extension` | ⛔ **the version goes into the file name, not the directory name**; `-fixed` / `-submit-package` / `preview_v12b` are banned |
| ③ **versioning** | a new version takes `vN+1`, the old one **moves into `_deprecated/`** | ⛔ **move, never delete** (deletion is irreversible; a past run lost the evidence of 21 projects) |
| ④ **ledger** | three ledgers: `cost_ledger.json` (money) / `asset_index.md` (assets) / `provenance.csv` (licensing) | a missing ledger = un-auditable |
| ⑤ **archiving** | 5 minutes at wrap-up: audit + no leftovers in the default cwd + record the convention in `AGENTS.md` | no version in directory names |

## 2. Audit (turning "messy files" into something measurable)

```powershell
python <SKILL_DIR>/scripts/assets_audit.py --project <project-root> --json review/assets.json
python <SKILL_DIR>/scripts/assets_audit.py --default-cwd          # any leftovers in the default cwd
```

Detects six classes: **multiple versions of the same prefix / stacked semantic suffixes / version number inside a directory name / missing cost ledger / unarchived deliverables / hard naming defects**.
Exit code `1` = problems found (usable as a process gate).

**Measured once (on `<DESKTOP_DIR>/<PROJECT>`)**: across 1270 files, 4 classes of problems were reported (including a `preview_v12` directory name carrying a version, a `<deliverable>.docx` existing side by side with `<deliverable>_V1.2.docx`, and no cost ledger at all).

## 3. Hard gates (five)

1. **The default cwd is not a repository**: important deliverables must land in the project directory; before a project ends, run `--default-cwd` to confirm there are no leftovers.
2. **The version goes into the file name, not the directory name.**
3. **Move, never delete**: old versions go into `_deprecated/`; a real deletion requires **a list + the user's approval**.
4. **Only all three ledgers complete** makes a delivery complete (money / assets / licensing).
5. **An asset with unknown licensing must not enter a delivery.**

## 4. Anti-patterns

| Anti-pattern | Consequence (measured) |
|---|---|
| Writing the version into the directory name | one directory per version → doubled disk usage, fragmented structure (`DeskPulse-v2.0.4-hotfix`) |
| Expressing state with `-fixed` / `-submit-package` | cannot be sorted, cannot determine the current version (**<N> version files**) |
| Doing the project inside the default cwd | one cleanup → **21 projects lost any chance of a retrospective** |
| Deleting the old version in place | irreversible (in one run a directory was emptied) |
| Storing assets without metadata | not reusable (the prompt / licensing / source is unknown) |

## 5. Sources

| Source | What was borrowed |
|---|---|
| the local `save-to-desktop` skill | the placement convention `<DESKTOP_DIR>/<project>/` (**this skill does not re-implement it**) |
| the existing practice in the local `<TOOLS_DIR>/audio/assets/bgm/` | the asset-library paradigm of "asset + a same-named json metadata file" (**the only good example that already exists**) |
| a past cross-project audit across <N> projects + the `assets_audit.py` run | all the evidence in `references/01` |

> No external repository was borrowed from; every rule comes from measured audits and existing skill conventions.

---

## Working discipline (three hard rules, **read before changing anything**)

**① Research first** — before creating or substantially changing a skill or workflow, first look for existing solutions in **the locally installed skills** and **online**, and give "what you found → adopt / do not adopt → why". **② Do not expand scope on your own** — unrequested extensions are proposed only, never executed, and a proposal must state the cost (skill table +N / context +X per turn). **③ Budget first** — plan / report / plan against the amount / keep the ledger / reconcile, a five-step closed loop.