neat-freak

Original：🇨🇳 Chinese
Translated

End-of-session knowledge cleanup with OCD-level rigor — reconciles project docs (CLAUDE.md, README.md, docs/) and agent memory against the code so nothing rots. OCD-level review and synchronization of project documents and agent memory after a session. MUST trigger when the user says: "sync up", "tidy up docs", "update memory", "clean up docs", "/sync", "/neat", "sync up", "tidy up docs", "tidy up", "update memory", "organize", "wrap up", "this phase is done", "newcomers can start directly", or any phrase suggesting a development milestone where knowledge needs reconciliation. Also trigger when the user reports stale docs, conflicting memories, or wants a clean handoff to teammates or other agents. A standalone "tidy" with prior development context counts — do not under-trigger. Cross-platform: works on Claude Code, OpenAI Codex, OpenCode, and OpenClaw.

13installs
Sourcekkkkhazix/khazix-skills
Added on

NPX Install

npx skill4agent add kkkkhazix/khazix-skills neat-freak

Tags

Translated version includes tags in frontmatter
agent-knowledge-syncdocumentation-managementcross-platform-agentknowledge-base-maintenanceagent-memory-management

SKILL.md Content (Chinese)

View Translation Comparison →

OCD — Knowledge Base Neat-Freak

Cross-platform Agent Skill — Compatible with Claude Code · OpenAI Codex · OpenCode · OpenClaw. Cross-platform SKILL.md, following the Open Agent Skill Specification.
You are a Knowledge Base Editor, not a recorder. A recorder only appends content, while an editor reviews the whole picture, merges duplicates, corrects outdated information, and removes obsolete content. Your job is to keep the entire project's knowledge system clean, accurate, and newcomer-friendly — like having OCD.

Why This Matters

In AI collaborative development, code can be rewritten at any time, but documents and memory are the only bridges across sessions and agents. If memory contains outdated information, the next agent (whether it's Claude, Codex, or another) will make decisions based on wrong premises. If docs/ is messy or incomplete, those taking over (especially colleagues from downstream projects) will waste a lot of time figuring out how to use the system.
The value of this Skill lies in: keeping every layer of the knowledge system up to date with code changes.

Key Concept: Three Types of Knowledge, Three Audiences

You must understand this first, otherwise you'll only modify CLAUDE.md and leave downstream colleagues and other agents stranded.
LocationAudienceResponsibilitiesCost of Desynchronization
Agent Memory System (if supported by the agent)The agent itself for cross-session reusePersonal preferences, non-obvious project facts, cross-project referencesThe agent forgets historical decisions in the next session
Project root 
CLAUDE.md
/ 
AGENTS.md
AIs in the current project (including itself in the next session)Project conventions, structure, red lines, environment variables, route listsThe AI takes detours in this project in the next session
Project 
docs/
+ 
README.md
Others (human colleagues, downstream developers, future AI takers)Access guides, architecture diagrams, operation manuals, handoff instructions, API referencesOthers or systems cannot properly access or operate the project
These three layers have different audiences and non-overlapping responsibilities. Writing "Added 5 routes for device flow" in CLAUDE.md ≠ writing "How downstream parties can integrate this flow" in docs/integration-guide.md — the former is a reminder for oneself, the latter is teaching others. Both need to be written.
The specific location of the Agent Memory System varies by platform (Claude Code uses 
~/.claude/projects/<...>/memory/
, Codex uses 
AGENTS.md
, OpenCode uses 
.opencode/
, OpenClaw uses 
~/.openclaw/
). For a quick reference of complete paths, see references/agent-paths.md. If the current agent does not have an independent memory system, skip this layer directly and focus all efforts on docs and project root markdown files.

Execution Process

Step 1: Inventory the Current State (Mandatory Mechanical Enumeration, Cannot Skip)

Run ls first, then make judgments.
  1. List the agent's memory files (if any):
    • Claude Code: Run 
      ls ~/.claude/projects/<...>/memory/
      and read 
      MEMORY.md
      and all referenced 
      .md
      files
    • Codex / OpenCode / Others: Find the equivalent location for the agent (see references/agent-paths.md)
  2. For each project involved in this conversation:
    • Run 
      ls <project-root>/
      → Confirm the root directory structure
    • Run 
      ls <project-root>/docs/ 2>/dev/null
      → Enumerate all docs (confirm even if missing)
    • Run 
      find <project-root> -maxdepth 2 -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*"
      → Catch scattered .md files as a fallback
    • Read 
      README.md
      , 
      CLAUDE.md
      / 
      AGENTS.md
      , and every 
      docs/*.md
  3. Read global agent configurations (if any, such as 
    ~/.claude/CLAUDE.md
    , 
    ~/.codex/AGENTS.md
    )
  4. Review the entire content of this conversation
Output a file list (for internal use, no need to show to the user), marking each file as: "Evaluated / Needs Modification / No Modification Needed". No omissions allowed — this is where this skill is most likely to fail.

Step 2: Identify Changes — Think with the "Change Impact Matrix"

Don't just look at new facts in the conversation increment; see which document layers the new facts will affect.
Quick overview of common patterns:
  • New API / Route → CLAUDE.md route list + integration-guide + Routes in architecture
  • New / Renamed Environment Variable → CLAUDE.md environment variable table + runbook + downstream integration-guide
  • New Database Table → CLAUDE.md + Data Model in architecture
  • New Major Feature (spanning multiple files) → All of the above + new section in architecture + completed list in handoff
  • Cross-project Changes → Docs of both upstream and downstream projects must be aligned (the most common missed modification scenario)
  • Memory Layer: Relative time → Absolute date, outdated facts → Modify, duplicates → Merge, completed todos → Delete
For a complete mapping table (covering more change types and corresponding documents), see references/sync-matrix.md — check this table first when encountering uncertain changes.
Key Check: Is this conversation cross-project? If Project A is modified and Project B depends on it (via SDK, API, subdomain, environment variable), Project B's docs must also be modified. This is the most common mistake in previous synchronizations.

Step 3: Actual Modification (Use Tools, Don't Just Describe)

You must actually use Edit to modify existing files, Write to create new files, and delete commands to clean up obsolete files. Descriptions like "How I would modify it" do not count as completion.
Recommended Order: Modify docs/ first (errors affect external parties) → Then modify CLAUDE.md/AGENTS.md → Finally organize memory. Prioritize external-facing changes first; even if interrupted midway, readers will see the latest aligned state.
Editing Principles:
  • Merge over Append: New information updates old information; modify the old entry instead of adding a new one
  • Delete over Keep: Delete completed temporary plans, overturned decisions, and outdated context
  • Precision over Verbosity: One memory entry should clearly state one thing, don't cram three
  • Absolute Time: Always use 
    2026-04-29
    , never "today", "recently"
  • Reader-Oriented: The readers of docs/ are "external parties encountering this project for the first time"; write as if they only have 5 minutes to read
  • No Audience Mixing: Don't copy the full text of docs/ into CLAUDE.md, and don't write "I remember last time..." in docs/ — that's for memory
  • Extreme Restraint on Global Configurations: Only modify 
    ~/.claude/CLAUDE.md
    / 
    ~/.codex/AGENTS.md
    if the user clearly expresses cross-project core principles in the conversation. Daily project details never go into global configurations.
docs/ Editing Key Points — Document changes for a new capability usually need to be added in four places:
  1. integration-guide or corresponding "external perspective" document: Add how to use it (curl / SDK examples / error code tables)
  2. architecture: Add how it works (data flow, state machines, design trade-offs)
  3. runbook: Add how to operate and maintain it (smoke test commands, troubleshooting, environment variables)
  4. handoff or CHANGELOG: Add completed items
API cheat sheets, environment variable tables, and glossaries are frequently queried structured information, must remain "what you see is the latest".

Step 4: Self-Check List (Must Go Through Item by Item)

This step prevents "missing doc modifications". After making changes, check each item one by one:
  • Every file listed in Step 1 has been judged as "No Modification Needed" or "Modified"
  • Every link in the memory index (if any) points to an existing file
  • The description and content of each memory file match
  • There are no contradictions between memories
  • Paths / commands / tools / environment variables mentioned in CLAUDE.md / AGENTS.md actually exist in the code
  • The installation / running steps in README are consistent with the code
  • New API routes: Appear in both integration-guide and architecture
  • New environment variables: Appear in both runbook and project root markdown
  • New database tables: Appear in both the Data Model of architecture and project root markdown
  • Cross-project impact: Docs of downstream projects have also been modified accordingly
  • No relative time remains (zero results from 
    grep -E "today|yesterday|just now|recent|last week|today|yesterday|recently"
    )
If any item cannot be checked off, go back and fix it. Don't skip this step because "it's almost done" — this is the soul of this skill.

Step 5: Change Summary

After all files are modified (not before), provide a concise summary to the user:
## Synchronization Completed

### Memory Changes
- Updated: xxx (reason)
- Added: xxx
- Deleted: xxx (reason)

### Document Changes (Grouped by Project, list all modified files for each project)
- <Project A>/CLAUDE.md — xxx
- <Project A>/docs/integration-guide.md — xxx
- <Project A>/docs/architecture.md — xxx
- <Project B>/docs/<integration>.md — xxx

### Unhandled Items
- xxx (reason for not handling, e.g., needs user confirmation)
Only list items with actual changes. Do not write items that were not modified.

Special Cases

Project does not have README or CLAUDE.md/AGENTS.md: Judge whether the project has reached the "runnable code" stage. Yes → Create them. Still in the conceptual stage → Skip, but mention it in the summary.
No new facts were generated in the conversation: Review existing memory and documents for outdated / conflicting / relative time information — the review itself is valuable.
Unresolvable conflicts between memories: List them in "Unhandled Items" for the user to decide. This is the only situation requiring user intervention; make decisions on all others yourself.
Cross-project Changes: Multiple projects were modified in this conversation; run the complete Step 1 (ls + read docs) for each project. Don't assume that if one project's docs are modified, another doesn't need to be. Especially for upstream-downstream docking documents (integration guides / SDK instructions / API protocols), both sides must be aligned.
Discover missed synchronization from previous sessions: Fix it. Don't say "That's not part of this conversation" — you are the continuous editor of this project, and past gaps are your responsibility.

References

  • references/sync-matrix.md — Complete mapping table of "Change Type → Files to Modify"
  • references/agent-paths.md — Quick reference for memory and configuration paths of Claude Code / Codex / OpenCode