# Project Artifact Cleanup

> Manage AI-created temporary files and retained artifacts, preview expired groups, and clean only explicitly authorized disposable outputs. Use for agent clutter and task-end cleanup, not source refactoring or whole-disk cleaning.

- Skill: `shiyupro/project-artifact-cleanup` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add shiyupro/project-artifact-cleanup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shiyupro/project-artifact-cleanup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ShiYuPro (https://skillmd.com/u/shiyupro)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shiyupro/project-artifact-cleanup

---


# Project Artifact Cleanup

Make agents responsible for the files they create. Python 3.9+ on macOS/Linux
(or WSL); native Windows is not supported because locking uses `fcntl`.
Read [setup and lifecycle examples](references/setup.md) on first use.

## Establish the project's policy once

Ask the user to select the project, what counts as disposable, retention days,
and whether task-end and scheduled deletion are authorized. Reuse an existing
explicit policy; do not ask again for each covered operation. Installing this
skill grants no deletion authority. Default to previews when authority is absent.
Seven days is an example/default, not a universal rule.

- Keep source, current scripts, deliverables, required docs, databases, uploads,
  credentials, Git history, active work and unique rollback assets in place.
- Write disposable scratch to `.agent-artifacts/tmp/<task>/payload/`.
- Close completed review material into `.agent-artifacts/recent/<task>/payload/`.
  Retention begins at closure, not the age of the original file.
- Pin anything still needed. Never classify something as disposable just because
  it is old, untracked, large, named `tmp`, or generated by AI.

Exclude the store from Git AND the actual publish/package process before placing
private logs there. A Git ignore alone does not prove deployment exclusion.
If exclusion is unknown, use a private temporary directory instead.

## Managed lifecycle

Use `scripts/artifacts.py`; a task slug must be unique among current groups.
Use the actual task ID or a user-chosen unique owner token; the token records
ownership, not an authentication or security boundary.

```text
begin --project PROJECT --task TASK --owner OWNER --reason REASON
finish --project PROJECT --task TASK --owner OWNER --keep-days 7
finish --project PROJECT --task TASK --owner OWNER --keep-days 0
finish --project PROJECT --task TASK --owner OWNER --keep-days 0 --apply
sweep --project PROJECT
sweep --project PROJECT --apply
status --project PROJECT
pin --project PROJECT --task TASK --owner OWNER
restore --project PROJECT --task TASK --owner OWNER --destination NEW_DIRECTORY
```

Zero-day finish previews unless `--apply` is supplied. Positive retention moves
this task's payload into recent storage; report the new path. Before closure,
confirm no process, unfinished work, source/build, deliverable or rollback depends
on it. Ordinary task closure touches only this task, not historical groups.

Sweep defaults to a preview. Apply only under the user's policy. It removes only
completed, unpinned, expired groups whose contents still match their closure
fingerprint. Changed groups, unsafe entries and invalid metadata are skipped.
The script cannot determine whether a source file depends on an artifact; this
classification is the agent's responsibility before closure.

Restore copies a retained payload to a new, absent destination and pins the original.
It cannot restore anything already deleted. No unpin shortcut is provided: review
and re-adopt intentionally if the user's retention decision changes.

## Existing project clutter

Inspect named candidate families once using contents, Git state, current manifests
and references, including directory/glob packaging. Do not crawl dependencies or
read secrets. Leave uncertain material in place. For proven obsolete items and
with authorization, preserve exact current bytes and relative paths in a managed
retention group; record origins in its reason. Do not discard uncommitted edits,
change the Git index, or claim Git can restore bytes that were never committed.

## Scheduling and limits

No scheduler is installed. If requested, connect the preview/apply command to the
user's chosen scheduler after the policy is approved. Preview first. A weekly sweep
with seven-day retention deletes at the next sweep, usually 7–14 days after closure.
Scheduling availability depends on the host; this skill alone cannot guarantee
Agent compliance or unattended execution. Active groups are never age-expired.

Report candidates/deletions, measured payload bytes, skipped reasons and recovery
paths. Moving files on the same filesystem does not free disk space. This is a
trusted local workflow, not a defense against malicious concurrent writers; stop
writers before cleanup and do not use it on untrusted shared directories.