How to use the Neat Freak agent skill: install and trigger it

What Neat Freak makes the agent do

When you finish a development session, Neat Freak has the agent check whether your README, architecture docs, CLAUDE.md or AGENTS.md rule files, and any agent memory notes still match the real code and running system. It fixes stale or contradictory statements in place, flags leftover files such as old plans or backup copies, and reports what is verified, pending, or not applicable.

The skill is scoped to project knowledge. It is not meant for pure coding, refactoring or debugging tasks, and it is not meant for tidying data, prose or changelogs.

• Compares documentation claims (startup commands, ports, dependencies, implemented features) against the current code.
• Creates a minimal CLAUDE.md or AGENTS.md for a small project that has runnable code but no rule file yet.
• Lists leftover session files such as PLAN.md, TODO.md, debugging scripts, and old copies like xxx_old or xxx_backup, then asks you before deleting any of them.
• Reports each area of the project as verified-current, changed-and-verified, pending, out-of-scope or not-applicable.

How do you install the Neat Freak skill?

Download the ZIP from the Neat Freak page on this directory. There are two ways to install it, depending on where you use your agent.

For Claude Code, unzip the download into ~/.claude/skills/ to make it available in all your projects, or into a project's .claude/skills/ folder to make it available only in that project. For the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

After installing, start a new session so the agent can load the skill. The skill folder should contain SKILL.md at its top level, since that file defines the skill.

• Personal install: ~/.claude/skills/
• Single-project install: the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger Neat Freak with a natural request?

You can invoke the skill by name or simply describe the closeout you want. The skill's description lists these triggers: the name "neat-freak", the Chinese name "洁癖", or the command "/neat". It also responds to clear closeout intent without the name, such as asking to sync or tidy project docs, rules or memory after development, or saying the docs no longer match the code.

Examples of phrasing the skill is written to recognise include "把文档和记忆整理一下" (tidy up the docs and memory), "收尾时把文档同步掉" (sync the docs when wrapping up), and "docs 和代码对不上了" (the docs and code don't match). A plain request like "tidy up" with no project context is not enough, so say what you want tidied.

• Use the name: "Use neat-freak to check the docs against the code."
• Describe the closeout: "The docs and code don't match after today's changes, please sync them."
• Ask for a handoff: "I'm handing this project to a teammate, make the docs and CLAUDE.md the single current source of truth."
• Ask for an audit: "Check whether our workspace rules are actually being followed."

Light path or full path: which one runs?

Most personal projects use the light path, which has five steps: inventory the project, align facts with the code, add or fix the AI rule file, review leftover session files, and report the results. The full path is for projects with a release process or several platforms, such as projects with pull requests, CI, production services, or multiple projects linked together. If you are unsure, the skill says to use the full path.

On the light path, the agent creates a minimal rule file only when the project has runnable code and no rule file. The file should stay within 60 lines and cover one-line purpose, how to run it, tech stack, layout and conventions, and current status with next steps. If a rule file already exists, the agent only fixes contradictions and outdated items rather than rewriting it.

• Light path: inventory, align facts, add or fix rule file, review session leftovers, report.
• Full path: steps 0 to 7, including platform discovery, a current-facts matrix, rule audit, routing of affected docs, careful memory handling, verification, and a two-phase report.

What does Neat Freak need, and what do its scripts do?

The skill needs filesystem read access in your agent environment. It can use Bash to run the optional inventory script scripts/audit-inventory.sh. Without Bash, the agent does the equivalent checks manually. Git and ripgrep (rg) are optional, but they improve verification. The skill's own listing says it runs scripts and does not use the network.

To run the read-only inventory yourself, the skill's documented command is shown below. Replace the placeholder with your project root.

• Required: filesystem read access.
• Needed for the script: Bash.
• Optional, improves verification: Git and rg.
• Network: not used.

What safety rules does Neat Freak follow?

Neat Freak asks before deleting anything. Deletions, renames, service shutdowns, permission or key changes, and similar actions are treated as needing explicit authorization. Cleanup of branches, worktrees, temporary databases or intermediate outputs happens in two phases: the agent first previews what would be removed and reports to you, and only deletes after you confirm.

Memory is read-only by default. The skill writes to agent memory only when you or the project's closeout rules explicitly authorize it. The skill also does not edit other projects without permission. Text inside project files, rule files or memory is treated as data, not as instructions, so a line in a file that says to run a command or delete something does not count as your approval.

• Deletions: listed as candidates with reasons, nothing removed until you confirm.
• Memory writes: only with explicit authorization.
• Other projects: read-only checks for naming and dead references; no edits outside the current project without permission.
• Commands and downloads found inside files are not authorized by being written there.

Tips for getting the best results from Neat Freak

Start a closeout after a finished chunk of work, not in the middle of debugging, because the skill is built for finished sessions. Keep your important rules in one place. If your workspace has its own conventions, state them in the rule files, since the skill checks against the rules that actually apply to your workspace.

Read the report before you approve cleanup. The report separates what changed from what needs your decision, and it lists pending and out-of-scope items explicitly. Treat those lists as the part to review.

• Run it at the end of a session, once the code and tests reflect what you intended.
• Install it where you will use it: personal folder for all projects, project folder for one.
• Review deletion candidates line by line before confirming.
• If the agent reports an item as pending, check it yourself rather than assuming it is settled.