Index of every page on this site: llms.txt
All skills
paulrberg avatar

/ai-prune

@c9e5a34
by Paul Bergpaulrberg/agent-skills106 stars
11
Run it yourself

Prune agent scratch directories on macOS. Move clearly outdated `.ai/` files into `.ai/archive/YYYY-MM-DD/` and trash clearly outdated `.cache/` entries. Leave `.ai/todos` untouched.

Use this Skill: https://skilld.dev/gh/paulrberg/agent-skills/ai-prune

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈48 tokens for metadata: the name and description. ≈1.3k when used: this file. ≈11 more on demand in 1 file.

How this Skill uses context

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

This Skill turns off automatic use in Claude Code. Its description stays out of the automatic Skill list by default.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

AI Prune

If a slash or dollar invocation already added these instructions to the conversation, follow them directly. In that case, do not invoke this skill again through a skill tool.

Review everything under .ai/ and .cache/. Decide which entries are clearly outdated relative to the repository's current state. Archive the matching .ai/ entries. Move the matching .cache/ entries to the macOS Trash. Prefer to keep entries. Change only entries with concrete evidence that they are outdated.

This skill runs only on macOS. If uname -s is not Darwin or /usr/bin/trash is missing, stop and report.

Arguments

  • path (optional): Repository root or any path inside the repository. Default to the current directory.
  • --dry-run (optional): Report the planned moves and deletions without changing the filesystem.

Never Touch

  • .ai/todos/ and .ai/archive/ (including everything beneath them).
  • TODO.md and PROMPT.md files anywhere: they are user-owned notes. Do not read or move them.
  • Live agent state: coordination ledgers, leases, locks, inboxes, and notification queues (for example .ai/coord/, .cache/job-leases/). If another agent may currently write to a directory, treat it as live, not outdated.
  • Tool-managed caches that the repository's configuration still uses (prettier, ruff, pytest, uv, vitest, coverage, bundler and package-manager caches). Tools regenerate them on demand. They are never "outdated".
  • Anything modified within the last 24 hours, unless it is unambiguously a leftover of finished work.

Workflow

  1. Resolve the root. For a supplied file, use its containing directory. For a supplied directory, use that directory. Inside Git, resolve the Git root with git -C "$start_dir" rev-parse --show-toplevel. Outside Git, use the directory itself.

    Store the root as repo_root. Compute today=$(date +%Y-%m-%d). If neither .ai/ nor .cache/ exists, stop.

  2. Inventory both trees with modification times, excluding the protected paths:

    fd -H -I -l -t f -E todos -E archive -E TODO.md -E PROMPT.md . "$repo_root/.ai"
    fd -H -I -l -t f . "$repo_root/.cache"

    Keep -I because these trees are usually Git-ignored. Without it, nested ignore patterns (for example a global PLAN.md rule) silently omit entries from the inventory.

    Do not run per-file commands over the inventory. Read the listing. Open only files whose relevance is unclear.

  3. Establish the present state of the repository: git log --oneline -30, the current tree, README.md, AGENTS.md or CLAUDE.md, and the task runner or tool configuration. Then assess each entry. Assess a whole directory only when the same decision applies to all its contents. Treat an entry as clearly outdated only when evidence such as the following applies:

    • A plan, handoff, thread, or report whose work is visibly complete in the Git history or the current tree.
    • Notes that reference files, symbols, branches, PRs, or tools that no longer exist.
    • Debriefs, evidence captures, renders, logs, or temporary directories (random suffixes, .tmp, dated run folders) from a task that has finished.
    • Caches or outputs for tooling the repository no longer configures.

    Keep and list as uncertain anything without such evidence, anything still referenced by live docs, scripts, or configuration, and anything protected above.

  4. Apply the decisions unless --dry-run was given:

    • .ai/ entries: move each to .ai/archive/$today/<path relative to .ai> so the archive mirrors the original layout. Create parent directories with mkdir -p. A same-day re-run merges into the existing dated folder. If the destination path already exists, leave the source in place and report the collision. Do not overwrite the destination.
    • .cache/ entries: move to the Trash with /usr/bin/trash -s <path>... in one call for all entries. -s fails on the first path that cannot be moved. Never use rm. Finder can restore trashed entries. Still classify any borderline entry as "kept".
    • Remove directories under .ai/ that became empty, except the protected ones.
  5. Verify by listing .ai/archive/$today/ and re-running the inventory from step 2. Every path you acted on must be absent from its source. These directories are usually Git-ignored. Verify on the filesystem rather than with git diff.

Completion

Report one outcome line, then a table with columns Path, Action (archived, trashed, kept), and Reason. Include kept entries only when you considered them and judged them uncertain. Do not list protected or obviously live paths. Keep paths, commands, and diagnostics undecorated.

  • Success: 🗂️ Archived <n> → .ai/archive/<today> · Trashed <m> from .cache · Kept <k> uncertain
  • No-op: ✅ Nothing outdated under .ai or .cache · Kept <k> uncertain
  • Dry run: 🔎 Would archive <n> → .ai/archive/<today> · Would trash <m> from .cache · Kept <k> uncertain

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The ai-prune skill manages agent scratch directories on macOS by archiving or trashing outdated files. Its primary security risk is indirect prompt injection, as it evaluates file content to make decisions. It uses standard system tools and includes safety measures like dry-run support and protected path lists.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at c9e5a34. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 months ago
argument-hint
[path] [--dry-run]
compatibility
macOS 15 or later only. Deletions use the system `/usr/bin/trash` command.
disable-model-invocation
true

README badge

README badge for paulrberg/agent-skills/ai-prune