keeping-system-clean

Keeping System Clean

Everything an agent installs or generates for a one-off task lives in one place you can delete with a single command.

This skill gives the agent a single, auditable, throwaway workspace (~/.agent-sandbox). All transient packages and scratch files from one-off, project-independent tasks are routed there instead of into your global Python/Node environment or scattered across the filesystem — so the entire footprint is inspectable in one folder and reversible in one command:

rm -rf ~/.agent-sandbox   # undoes everything the agent ever set up for one-off work

Core Concepts

• 🗑️ One removable workspace — every install + scratch file lands in ~/.agent-sandbox, deletable in one command
• 🔍 Auditable — structured subdirs (python/, node/, tmp/, bin/, cache/) + a self-documenting README, so you can always see what's there and why
• ✅ One-shot commands prefer zero-install runners (uvx, uv run, npx -y) — nothing to clean up at all
• ✅ Project dependencies stay with the project (the repo's own .venv / node_modules)
• ❌ Never global installs (pip install, npm install -g, sudo pip)

When to Use

Use when: running pip install, npm install -g, uv pip install, uvx, or npx; needing a scratch virtualenv; needing somewhere to put downloaded or generated temp files; or whenever you want installs kept off the global system.

Don't use for: project-local dependencies that belong in a specific repo's own .venv / node_modules, or system-level tools that genuinely need global access.

Enforcement (Claude Code plugin)

A skill is guidance — the model decides whether to follow it. This plugin adds a PreToolUse hook that deterministically blocks global/system installs before they run, regardless of whether the skill was loaded. When the plugin is installed, the agent simply cannot run these without redirecting to a clean path:

Blocked	Allowed
pip install / pip3 install / python -m pip install (no active venv)	uvx · uv run --with · npx -y
sudo pip · easy_install · uv pip install --system	.venv/bin/pip install (direct venv)
npm/pnpm/bun install -g · yarn global add	source .venv/bin/activate && pip install …
	npm install (project-local)

The hook fails open (a parse error never blocks your shell) and is best-effort string matching — it stops honest habitual mistakes, not deliberate obfuscation.

Coverage limits & airtight complement. A command-string hook can't see through aliases, wrappers (sh -c "…"), or non-Bash install paths. For invocation-agnostic coverage, also set tool-native guardrails in your Claude Code settings.json (these aren't shipped by the plugin — env vars come from settings):

{ "env": { "PIP_REQUIRE_VIRTUALENV": "true" } }

PIP_REQUIRE_VIRTUALENV makes pip itself refuse to install outside a venv, no matter how it's invoked.

Installation

Claude Code (plugin — one command)

/plugin marketplace add zhiyuc123/keeping-system-clean
/plugin install keeping-system-clean@zhiyuc123-skills

Manual (any agent)

Copy the keeping-system-clean folder into your agent's skills directory:

Claude Code — ~/.claude/skills/

git clone https://github.com/zhiyuc123/keeping-system-clean /tmp/keeping-system-clean
cp -r /tmp/keeping-system-clean/skills/keeping-system-clean ~/.claude/skills/

Codex — ~/.agents/skills/

cp -r /tmp/keeping-system-clean/skills/keeping-system-clean ~/.agents/skills/

For other agents, place the keeping-system-clean/ folder in that agent's skills directory.

Contributing

Contributions are welcome. Please ensure:

1. SKILL.md follows the agentskills.io specification
2. The description uses "Use when..." format, lists concrete trigger keywords, and does not summarize the internal workflow
3. The skill is tested before submission (run it against real scenarios on each supported OS)

License

MIT — see the LICENSE file.