Audit and fix project documentation role overlaps. One command to keep all your context files healthy.
In LLM-driven development, organizing concepts is implementation. Markdown carries the same weight as executable code — a stale number in CLAUDE.md, a misplaced design rationale in README, or a contradictory module count silently degrades every AI-assisted session that reads it. The agent works from what the documents say, not from what the code is.
Context consistency is not a housekeeping task. It is a prerequisite for the core concepts to reach the system without noise. This skill mechanically guarantees that consistency — freeing the human to focus on creating and refining the concepts themselves.
As projects grow, documentation sprawls across multiple files with overlapping responsibilities:
- CLAUDE.md becomes a dumping ground for architecture details, design decisions, and conventions
- README has internal implementation details that belong elsewhere
- Design decisions live in comments, PR descriptions, or nowhere at all
- Numbers in docs (module count, test count, version) silently go stale
- Architecture docs duplicate design explanations that belong in a specification
- Data schemas appear in 3+ files and drift out of sync
context-sync enforces a five-role model where every piece of project knowledge lives in exactly one place:
| Role | Purpose | Examples |
|---|---|---|
| Context | How to work here | CLAUDE.md, .cursorrules |
| Specification | How the system works | docs/spec/ |
| Architecture | Where things are in the code | docs/CODEMAPS/, docs/architecture/ |
| Decisions | Why it's this way | docs/adr/ |
| External | What this project is | README.md |
These two roles are complementary, not overlapping:
- Specification answers "what does this system do and how is it designed?" — readable by researchers and AI alike, focuses on concepts, data flow, and design choices
- Architecture answers "where is that implemented?" — code-level index with file paths, function names, and line numbers for navigation
When both exist, Architecture docs should point to Specification for design details rather than duplicating them.
- Discover — Scans for context files, classifies them into five roles, identifies missing roles
- Overlap Detection — Finds content in the wrong role (architecture detail in CLAUDE.md, design explanations in CODEMAPS)
- Create / Migrate — Creates missing docs (ADR, spec, architecture), moves content, replaces with pointers
- Freshness Check — Verifies numbers match code reality, flags stale files
- Report — Summary of all changes
Every action requires user confirmation. Nothing is auto-modified.
Large project (6900 LOC, 30 modules):
- Created system specification from scattered design descriptions
- CODEMAPS simplified to code-level index (design details → spec)
- ADRs remain independent decision records
- All docs maintainable via context-sync
Small project (iOS app, 591 tests):
- Correctly identified project was already healthy
- Only action: created missing ADR index + fixed stale test count
Run after milestones — feature complete, refactor done, architecture change. Not every commit; that's too frequent. A good trigger is "I just changed how something works, not just what it does."
Run as part of PR review, before merge. This catches doc drift introduced by the PR itself — a renamed module, a new pipeline stage, a changed threshold. Post-merge requires a follow-up PR just for doc fixes, which adds noise and often gets skipped.
Monthly or per-sprint as a health check. Catches gradual drift that no single PR introduced — stale test counts, module counts that crept up, ADRs that were never created for decisions made in Slack.
Copy SKILL.md to your Claude Code skills directory:
mkdir -p ~/.claude/skills/context-sync
cp SKILL.md ~/.claude/skills/context-sync/Then invoke with /context-sync in Claude Code.
This skill is the Maintain phase of AKC — a cyclic self-improvement architecture for AI coding agents.
MIT