home / skills / chen19007 / my_skills / aseprite-frame-extract

aseprite-frame-extract skill

safe

This skill exports per-tag frames from Aseprite files into organized folders for engines like Godot, accelerating asset management.

npx playbooks add skill chen19007/my_skills --skill aseprite-frame-extract

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.2 KB

---
name: aseprite-frame-extract
description: Batch-export per-tag animation frames from .aseprite files into categorized folders; use when asked to extract frames, split tags, or organize Aseprite animations into folders for engines like Godot.
---

# Aseprite Frame Extraction

## Quick start
- Run `python scripts/extract_aseprite_frames.py <file-or-folder-or-glob> [...]`.
- Outputs to `assets/<sprite-name>/<tag>/<frame>.png` by default.

## Workflow
1. Point to `.aseprite` files or a folder.
2. Provide `--aseprite` if Aseprite is not on PATH.
3. Check results in the output folder.

## Notes
- Uses Aseprite CLI `--split-tags` and `{tag}/{frame}.png` to classify frames.
- Tag names and frames are exported as-is; tag names become folder names.
- If a sprite has no tags, no frames are exported.

## Examples
```bash
python scripts/extract_aseprite_frames.py d:\project\godot\blockking\aseprite_assets --aseprite "D:\tools\Aseprite-v1.3.15.3-Windows\aseprite.exe" --output d:\project\godot\blockking\assets
python scripts/extract_aseprite_frames.py "d:\project\godot\blockking\aseprite_assets\*.aseprite" --preview
```

## scripts/
- `scripts/extract_aseprite_frames.py`: Calls Aseprite CLI to export per-tag frames into folders.

Overview

This skill batch-exports per-tag animation frames from .aseprite files into organized folders, making it easy to integrate Aseprite animations with game engines like Godot. It runs the Aseprite CLI to split tags and write each frame into assets/<sprite-name>/<tag>/<frame>.png by default. Use it to quickly convert whole folders or globs of .aseprite files into a folder structure ready for engine import.

How this skill works

The script calls the Aseprite command-line tool with the --split-tags option and an export pattern that places frames into tag-named subfolders. You point the tool at a file, folder, or glob and it processes each .aseprite source, creating per-sprite and per-tag folders and saving frames as PNGs. If Aseprite is not on PATH, you supply the --aseprite path; a preview mode can show what would be exported without writing files.

When to use it

You need per-tag frame folders for an engine import (Godot, Unity, custom).
Batch-converting many .aseprite files or an entire asset folder at once.
Organizing exported frames into consistent paths for automated build pipelines.
Preparing animation sheets where each tag corresponds to an animation state.
Quickly verifying tag and frame layout before runtime consumption.

Best practices

Ensure Aseprite CLI version is compatible with the script and accessible via --aseprite if not on PATH.
Give clear, tag-based names in Aseprite so exported folders are meaningful and filesystem-friendly.
Run with --preview first to confirm which files and tags will be processed before writing output.
Use a dedicated output directory (default assets/) and include it in version control or your engine asset pipeline as needed.
Validate that sprites have tags; sprites without tags will not produce exported frames.

Example use cases

Export all project .aseprite files to assets for Godot and keep each animation tag in its own folder.
Run the script in CI to regenerate frame assets from source .aseprite files before building game packages.
Quickly pull frames from a designer’s .aseprite folder into a developer-friendly structure for animation state mapping.
Preview exports to confirm tag naming and frame counts before committing large asset changes.
Convert a glob of files (e.g., *.aseprite) into per-sprite folders for batch import into an animation tool.

FAQ

What if Aseprite is not installed or not on PATH?

Pass the --aseprite argument with the full path to the Aseprite executable so the script can invoke the CLI.

What happens to sprites that have no tags?

Sprites without tags are skipped and no frames are exported; add tags in Aseprite to enable frame export.