Help us improve
Share bugs, ideas, or general feedback.
From navigator
Syncs a project's CLAUDE.md to the latest Navigator version while preserving customizations. Detects outdated versions via version markers or /nav: commands and migrates to natural language v3.1.
npx claudepluginhub alekspetrov/navigator --plugin navigatorHow this skill is triggered — by the user, by Claude, or both
Slash command
/navigator:nav-sync-claudeThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Update project's CLAUDE.md to latest Navigator version (v3.1) while preserving project-specific customizations.
Automates Navigator plugin updates with version detection, conflict resolution, and post-update validation. Invoked when user mentions upgrading Navigator or getting new features.
Generates or audits a CLAUDE.md for a project by combining data from Repo Auditor with a guided developer interview.
Audits and improves CLAUDE.md files in repositories by scanning for them, evaluating quality against criteria, generating reports, and applying targeted updates after approval.
Share bugs, ideas, or general feedback.
Update project's CLAUDE.md to latest Navigator version (v3.1) while preserving project-specific customizations.
Invoke this skill when the user:
DO NOT invoke if:
Check if CLAUDE.md exists and detect version:
if [ ! -f "CLAUDE.md" ]; then
echo "❌ No CLAUDE.md found in current directory"
echo ""
echo "Run 'Initialize Navigator in this project' first."
exit 1
fi
Use version_detector.py to analyze CLAUDE.md:
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-sync-claude/functions/version_detector.py" CLAUDE.md
This script checks for:
/nav:start, /nav:doc, etc.)Outputs:
outdated - Has /nav: commands or v1/v2 markerscurrent - Already v3.1 with natural languageunknown - Can't determine (custom/non-Navigator file)If current:
✅ CLAUDE.md is already up to date (v3.1)
No migration needed.
Exit successfully.
If unknown:
⚠️ CLAUDE.md doesn't appear to be a Navigator file
This might be a custom configuration. Manual review recommended.
Proceed with migration anyway? [y/N]
If user declines, exit. If accepts, continue.
Always create backup before modifying:
cp CLAUDE.md CLAUDE.md.backup
echo "📦 Backup created: CLAUDE.md.backup"
Use claude_updater.py to parse current CLAUDE.md:
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-sync-claude/functions/claude_updater.py" extract CLAUDE.md > /tmp/nav-customizations.json
This extracts:
Apply latest template with extracted customizations:
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
# Template fetching now automatic via get_template_path():
# 1. Tries GitHub (version-matched)
# 2. Falls back to bundled if offline
python3 "$PLUGIN_DIR/skills/nav-sync-claude/functions/claude_updater.py" generate \
--customizations /tmp/nav-customizations.json \
--template "$PLUGIN_DIR/templates/CLAUDE.md" \
--output CLAUDE.md
Template Source Priority:
https://raw.githubusercontent.com/alekspetrov/navigator/v{version}/templates/CLAUDE.md
templates/CLAUDE.md from installed plugin
What this does:
Display changes for user review:
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "📝 CHANGES TO CLAUDE.MD"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
# Show unified diff
diff -u CLAUDE.md.backup CLAUDE.md || true
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
Show summary of changes:
✅ CLAUDE.md Updated to v3.1
Key changes:
✓ Removed slash command references (e.g., /nav:start)
✓ Added natural language examples ("Start my Navigator session")
✓ Added skills architecture explanation
✓ Updated Navigator workflow section
✓ Preserved your project-specific customizations:
- Tech stack: [list]
- Code standards: [count] custom rules
- Forbidden actions: [count] custom rules
Backup saved: CLAUDE.md.backup
Next steps:
1. Review changes: git diff CLAUDE.md
2. Test: "Start my Navigator session" should work
3. Commit: git add CLAUDE.md && git commit -m "chore: update CLAUDE.md to Navigator v3.1"
4. Remove backup: rm CLAUDE.md.backup
Rollback if needed: mv CLAUDE.md.backup CLAUDE.md
If config exists, migrate to latest version with new sections:
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
if [ -f ".agent/.nav-config.json" ]; then
python3 "$PLUGIN_DIR/skills/nav-sync-claude/functions/config_migrator.py" .agent/.nav-config.json
fi
What this does:
simplification configauto_update configtask_mode configExample output:
✅ Config migrated: v5.4.0 → v5.6.0
Changes:
+ auto_update: (new section added)
+ task_mode: (new section added)
~ version: 5.4.0 → 5.6.0
Dry run (preview changes without applying):
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
python3 "$PLUGIN_DIR/skills/nav-sync-claude/functions/config_migrator.py" .agent/.nav-config.json --dry-run
Purpose: Detect CLAUDE.md version (outdated, current, unknown)
Usage:
python3 version_detector.py CLAUDE.md
Output: Prints one of: outdated, current, unknown
Exit codes:
Detection logic:
Navigator Version: X.X.X/nav:start, /jitd:, etc."Start my Navigator session"Heuristics:
/nav: → outdatedPurpose: Extract customizations and generate updated CLAUDE.md
Usage:
# Extract customizations
python3 claude_updater.py extract CLAUDE.md > customizations.json
# Generate updated file
python3 claude_updater.py generate \
--customizations customizations.json \
--template ../../templates/CLAUDE.md \
--output CLAUDE.md
Extract mode outputs JSON:
{
"project_name": "MyApp",
"description": "Brief project description",
"tech_stack": ["Next.js", "TypeScript", "PostgreSQL"],
"code_standards": ["Custom rule 1", "Custom rule 2"],
"forbidden_actions": ["Custom restriction 1"],
"pm_tool": "github",
"custom_sections": {
"Deployment": "Custom deployment instructions..."
}
}
Generate mode:
[Project Name] with project_name[Brief project description] with description[List your technologies...] with tech_stackPurpose: Migrate .nav-config.json to latest version, adding missing sections
Usage:
# Migrate config (applies changes)
python3 config_migrator.py .agent/.nav-config.json
# Preview changes without applying
python3 config_migrator.py .agent/.nav-config.json --dry-run
# JSON output
python3 config_migrator.py .agent/.nav-config.json --json
Version-specific configs added:
simplification (code clarity improvements)auto_update (auto-update on session start)task_mode (unified workflow orchestration)Output example:
✅ Config migrated: v5.4.0 → v5.6.0
Changes:
+ auto_update: (new section added)
+ task_mode: (new section added)
~ version: 5.4.0 → 5.6.0
Exit codes:
No CLAUDE.md found:
❌ No CLAUDE.md found in current directory
This project doesn't appear to have Navigator initialized.
Run "Initialize Navigator in this project" first.
Backup failed:
❌ Failed to create backup: CLAUDE.md.backup
Check file permissions and disk space.
Parse error:
❌ Failed to parse CLAUDE.md
The file might be corrupted or have unusual formatting.
Manual review required.
Backup saved at: CLAUDE.md.backup
Template not found:
❌ Navigator template not found
This might be a plugin installation issue.
Try reinstalling Navigator plugin: /plugin update navigator
Migration is successful when:
If migration fails or user is unhappy:
# Restore backup
mv CLAUDE.md.backup CLAUDE.md
# Or compare and manually fix
diff CLAUDE.md.backup CLAUDE.md
This skill:
What gets updated:
What gets preserved:
User: "Update my CLAUDE.md to v3.1"