hermes-workspace-hygiene
Skill2 starsChanged 4 months agoMITView on GitHub
Use when Hermes may create, move, clean up, or audit transient and generated files. Keeps artifacts in predictable workspace folders and requires manifests, approval, and rollback planning before cleanup.
In this repository12 other files it gives its agents.
- bounded-grillingSkill
- burnable-visual-briefsSkill
- context-budget-orchestrationSkill
- hermes-backup-recoverySkill
- kanban-workflowsSkill
- planSkill
- prototypeSkill
- skill-lifecycle-managementSkill
- to-specSkill
- to-ticketsSkill
- wayfinderSkill
- wfSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Keep Hermes-generated artifacts predictable, scoped, and recoverable:
- Distinctive: line 38
Do not use for normal source edits inside an existing project, read-only inspection, or durable knowledge and policy files that already …
- Distinctive: line 49
Prefer topic/profile subfolders:
- Distinctive: line 57
Do not create one-off files at a home-directory root.
- Distinctive: line 72
Use a machine-readable manifest such as:
- Distinctive: line 105
Verify resulting locations or absence.
- Distinctive: line 118
Delete-first cleanup: Prefer recoverable moves when they meet the goal.
- Distinctive: line 119
Ambiguous ownership: Ask rather than classifying personal files as generated clutter.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Hermes Workspace Hygiene
Overview
Keep Hermes-generated artifacts predictable, scoped, and recoverable:
- temporary/intermediate files go under
<active-workspace>/scratch/; - generated reports intended for reading or sending go under
<active-workspace>/reports/; - explicit user-requested exports go under
<active-workspace>/exports/; - project source remains in its project root;
- existing user files are never moved or deleted without explicit approval.
Resolve the active workspace from project instructions or the current working directory. If no safe workspace root is clear, ask before writing rather than defaulting to a personal home directory.
When to use
Use when:
- a task will create scripts, intermediate JSON/CSV/HTML, screenshots, downloads, report assets, or exports;
- the user asks to audit or clean generated files;
- generated artifacts appear in a high-level personal directory;
- a recurring job needs a predictable artifact and cleanup lifecycle;
- a report or export needs the correct destination.
Do not use for normal source edits inside an existing project, read-only inspection, or durable knowledge and policy files that already have an authoritative location.
Canonical workspace shape
<active-workspace>/
scratch/ temporary and intermediate artifacts
reports/ generated reports intended for reading or delivery
exports/ explicit user-requested exportsPrefer topic/profile subfolders:
scratch/<topic>/
reports/<report-class>/
exports/<task-slug>/Do not create one-off files at a home-directory root. Do not move project-specific source into a generic scratch tree.
Operating rules
- Before writing: choose the narrowest appropriate workspace subfolder.
- Before cleanup: inspect the exact candidates and produce a manifest.
- Before moving or deleting existing files: obtain explicit approval for that manifest.
- Prefer reversible moves over deletion unless deletion is explicitly requested.
- Keep rollback possible: record source, destination, size, reason, and timestamp.
- Fail closed: missing, changed, moved, symlinked, or ambiguous targets require a fresh audit and approval.
- Do not expand scope: newly discovered or newly stale paths do not inherit an older approval.
- Report honestly: distinguish proposed, moved, deleted, skipped, and failed items.
Cleanup manifest
Use a machine-readable manifest such as:
{
"manifest_id": "<stable approval identifier>",
"created_at": "<actual UTC timestamp>",
"operation": "move | delete",
"items": [
{
"from": "<absolute inspected source>",
"to": "<destination or null>",
"size_bytes": 12345,
"reason": "generated temporary artifact",
"identity_check": "<hash, inode, or other stable evidence when available>"
}
]
}The user-facing summary must include item count, total size, operation type, destination, rollback method, and the approval requirement.
An approval binds only to the exact manifest and targets shown to the user. Re-running an audit creates a new scope and requires new approval.
Audit procedure
- Define the allowed root and artifact classes.
- Inspect candidates without mutation.
- Exclude normal user folders, source trees, hidden configuration, and ambiguous files unless explicitly in scope.
- Resolve symlinks and record stable target evidence.
- Produce the manifest and concise decision summary.
- Wait for approval.
- Re-verify every target against the approved manifest immediately before execution.
- Execute only the approved operation and paths.
- Verify resulting locations or absence.
- Report completed, skipped, changed, and failed items plus recovery instructions.
Burnable brief lifecycle
Temporary visual briefs belong under scratch/visual-briefs/. A brief may carry an expiry timestamp, but expiry only makes it eligible for a cleanup proposal; it never authorizes automatic deletion. Durable evidence must remain elsewhere so the brief can expire safely.
Common pitfalls
- Home-root clutter. Tool defaults are not a safe artifact policy.
- Audit-as-approval. Discovering a candidate does not authorize mutation.
- Scope drift. A second audit cannot be executed under the first manifest.
- Path-only identity. Re-check symlinks and changed targets before execution.
- Delete-first cleanup. Prefer recoverable moves when they meet the goal.
- Ambiguous ownership. Ask rather than classifying personal files as generated clutter.
- Artifact/source confusion. Scratch space is not a project source root.
Verification checklist
- Workspace root and artifact class were resolved before writing.
- Temporary files, reports, and exports use their intended subfolders.
- No one-off artifact was written to a personal home-directory root.
- Cleanup remained read-only until an exact manifest was approved.
- The execution scope exactly matched the approved manifest.
- Targets were re-verified immediately before mutation.
- Every move has a rollback path; every deletion was explicitly approved.
- Results distinguish completed, skipped, changed, and failed items.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

