| name | sync-docs |
| description | Synchronize documentation and skills with codebase changes. Analyzes recent git changes and suggests updates to README, CLAUDE.md, and skills to keep documentation in sync. |
| allowed-tools | Bash, Glob, Grep, Read, Edit |
Sync Documentation
Analyze recent changes and update documentation/skills to keep them synchronized with the codebase.
Purpose
This skill helps maintain documentation consistency by:
- Detecting code changes that require documentation updates
- Identifying which documents/skills need updating
- Suggesting or applying necessary changes
- Ensuring README.md, CLAUDE.md, and skills stay in sync
Instructions
1. Analyze Recent Changes
Check what has changed in the codebase:
git diff HEAD~1..HEAD
git diff --staged
git diff
2. Identify Impact Areas
Based on the changes detected, determine which documentation needs updating:
Package/Tool Changes:
- Files (darwin):
darwin/home-manager/default.nix, darwin/flake.nix
- Files (NixOS):
nixos/home-manager/default.nix, nixos/flake.nix, nixos/configuration.nix
- Impact: README.md (Main Tools),
/nix-operations, /mise-guide
Keybinding Changes:
- Files (darwin):
darwin/home-manager/aerospace/, darwin/home-manager/zellij/
- Files (NixOS):
nixos/home-manager/zellij/, nixos/desktop/hyprland/
- Impact:
/services-guide, /hyprland-cheatsheet, /nixos-keybindings, /zellij-worktree
Configuration Structure Changes:
- Files: New modules, directory reorganization,
darwin/, nixos/, nixvim/
- Impact:
.claude/CLAUDE.md (Architecture Overview, Configuration Structure)
Command/Task Changes:
- Files:
Makefile, darwin/home-manager/mise/, nixos/home-manager/mise/, scripts
- Impact:
.claude/CLAUDE.md (Common Commands), /nix-operations, /mise-guide
Service/Daemon Changes:
- Files (darwin):
darwin/homebrew/, darwin/home-manager/aerospace/, darwin/home-manager/borders/
- Files (NixOS):
nixos/services/
- Impact:
/services-guide, /fileserver-guide, /gitserver-guide
Nixvim Configuration Changes:
- Files:
nixvim/config/, nixvim/flake.nix
- Impact: Consider updating nixvim-specific documentation if needed
3. Detection Patterns
Look for these specific change patterns:
New Package Added:
# In darwin/home-manager/default.nix or nixos/home-manager/default.nix
packages = with pkgs; [
...
newpackage # ← New addition
];
→ Update: README.md Main Tools section
New Make Task:
new-task:
@echo "New task"
→ Update: .claude/CLAUDE.md Common Commands
New Keybinding:
alt-shift-s = 'exec-and-forget screencapture -i -c'
→ Update: /services-guide Keyboard Shortcuts table
New Nix Module:
# In darwin/flake.nix or nixos/configuration.nix
imports = [
./new-module # ← New import
];
→ Update: .claude/CLAUDE.md imports list
4. Update Documentation
For each identified change:
- Read the current documentation
- Determine what needs to be added/modified
- Update the documentation (use Edit tool)
- Verify consistency across related documents
5. Report to User
Provide a summary:
- List of detected changes
- Documents that were updated
- Specific sections modified
- Any manual review needed
Common Update Scenarios
Scenario 1: Adding a New Package
Detected Change:
+ ripgrep
Updates Required:
- README.md → Add to appropriate section under Main Tools
- Consider if usage docs needed in relevant skill
Scenario 2: New Keybinding
Detected Change:
+ alt-shift-s = 'exec-and-forget screencapture -i -c'
Updates Required:
/services-guide → Add to Keyboard Shortcuts table- Ensure description matches the action
Scenario 3: New Nix Module
Detected Change:
# In darwin/flake.nix or nixos/configuration.nix
+ imports = [ ./new-feature ];
Updates Required:
.claude/CLAUDE.md → Update imports list.claude/CLAUDE.md → Update Architecture Overview if significant- Consider creating new skill if feature is complex
- Specify if darwin-only or nixos-only feature
Scenario 4: New Make Task
Detected Change:
+ docker-prune:
+ docker system prune -af
Updates Required:
.claude/CLAUDE.md → Add to Development Tools commands- Consider adding to
/nix-operations if Nix-related
Usage Examples
Check for updates needed:
/sync-docs
After making changes:
"I just added a new package, update the docs"
Specific check:
"Check if documentation needs updating based on my staged changes"
Important Notes
- Always run after significant changes to maintain doc consistency
- Review suggested changes before applying
- Check cross-references between documents
- Verify links and file paths are still correct
- Test commands mentioned in documentation
Limitations
This skill provides suggestions and automation but:
- May not catch all subtle documentation needs
- Cannot determine narrative/explanation quality
- Requires human judgment for complex changes
- Should be supplemented with manual review
