# Image-Gen Storage Policy

This skill intentionally stores generated artifacts and local preference data, but keeps them separate from the tracked skill package.

## Research Summary

The Agent Skills convention standardizes a skill as a directory with `SKILL.md` plus optional `scripts/`, `references/`, and `assets/`. The public docs describe `assets/` as static resources such as templates, images, lookup tables, schemas, and other files used by the skill. They do not define a standard place for mutable runtime outputs, local history, rankings, or generated media.

For mutable app/tool data, the closest established convention is XDG-style separation:

- user data: durable user-specific data
- user state: history, logs, recently used files, and restartable state
- cache: non-essential generated data
- runtime: temporary per-session objects

`image-gen` uses a repo-local, gitignored version of that separation because the skill is personal, the files are useful during local review, and the paths should be stable for scripts and agents. Environment variables let the user move those roots elsewhere when privacy, disk usage, or portability matters.

Sources:

- Agent Skills specification: https://agentskills.io/specification
- Claude custom skills guide: https://claude.com/docs/skills/how-to
- Claude skill authoring best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
- Claude skills overview: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
- OpenAI Codex skill-creator sample: https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/skill-creator/SKILL.md
- XDG Base Directory Specification: https://specifications.freedesktop.org/basedir/latest/

## Directory Roles

| Path | Git status | Role |
|------|------------|------|
| `scripts/` | tracked | Executable provider, comparison, review, and evaluation tools. |
| `references/` | tracked | Human and agent documentation loaded only when needed. |
| `assets/` | tracked | Stable reusable inputs: gallery templates, prompt packs, masks, reference assets, style boards. |
| `outputs/` | ignored except `README.md` | Generated images, comparison runs, manifests, winner copies, evaluation screenshots, and paid test outputs. |
| `data/` | ignored except `README.md` | Local durable history such as generations, rankings, and regeneration events. |

## Rules

1. Do not commit generated images, generated manifests, local rankings, regeneration logs, or prompt history.
2. Do not use `assets/` as a dump for generated outputs. `assets/` is for reusable source material that should travel with the skill.
3. Keep ignored roots discoverable by committing a `README.md` in each root.
4. Scripts must tolerate missing `outputs/` and `data/` directories and create them when needed.
5. Sensitive prompts should opt out of local history with `IMAGE_GEN_DISABLE_HISTORY=1`.
6. Use `IMAGE_GEN_OUTPUT_DIR` to move generated images outside the repo.
7. Use `IMAGE_GEN_DATA_DIR` to move JSONL history outside the repo.
8. If this skill becomes a shared/public tool rather than a personal repo-local skill, reconsider defaulting mutable data to an XDG-style external state/data directory instead of the skill directory.

## Current Local Files

- `data/generations.jsonl`: one entry per successful provider generation.
- `data/rankings.jsonl`: saved review-gallery rankings, winner choices, and comments.
- `data/regenerations.jsonl`: review-gallery regeneration events.
- `outputs/examples/<timestamp>/`: generated comparison examples and reviewable manifests.
- `outputs/comparisons/<run-id>/`: ad hoc comparison runs.
- `outputs/evaluations/<run-id>/<timestamp>/`: Playwright screenshots and checks for gallery review.
- `outputs/test-runs/<timestamp>/`: paid provider test outputs.

## Why This Is Acceptable Here

This is not a universal Agent Skills convention. It is a documented local convention for this skill.

It is acceptable because:

- the roots are gitignored and documented;
- the data is generated by the skill, not part of the reusable package;
- the paths are stable enough for scripts and agents;
- the user can opt out or move storage with environment variables;
- the tracked skill remains portable without the local outputs or history.