nav-sync-claude

Migrate project CLAUDE.md and Navigator config files to the installed plugin version while preserving customizations.

232|12|Updated Oct 10, 2025
One-click install
npx skills add https://github.com/qf-studio/navigator --skill nav-sync-claude-qf-studio
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: nav-sync-claude
Source: https://github.com/qf-studio/navigator/tree/main/skills/nav-sync-claude
Command: npx skills add https://github.com/qf-studio/navigator --skill nav-sync-claude-qf-studio

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When the Navigator plugin is upgraded, a project's CLAUDE.md and .nav-config.json fall out of sync with the installed version, leaving stale slash commands, missing config sections, and outdated workflow instructions. This Skill migrates both files to the current version without losing project-specific content. ## Core Features & Use Cases - Version Detection: Analyzes CLAUDE.md for version markers, slash command references, and natural language examples to classify it as outdated, current, or unknown. - Customization-Preserving Regeneration: Extracts project name, description, tech stack, code standards, forbidden actions, PM tool, and custom sections, then regenerates CLAUDE.md from a version-matched template fetched from GitHub with a bundled offline fallback. - Config Migration: Additively seeds missing .nav-config.json sections introduced in each Navigator release and bumps the version marker, with dry-run and JSON output modes. - Safety Guards: Creates a backup before modifying, shows a diff for review, refuses regeneration when the hook runtime is not provably live, and never downgrades a newer config. - Use Case: After updating the Navigator plugin, run the sync to migrate CLAUDE.md from slash commands to natural language workflow and add new config sections like task_mode and knowledge_graph. ## Quick Start Ask the assistant to update my CLAUDE.md to the latest Navigator version and migrate my Navigator config.

Frequently Asked Questions about nav-sync-claude

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I update CLAUDE.md after upgrading the Navigator plugin?

Invoke the sync by asking to update CLAUDE.md to the latest Navigator version. The skill detects the current version, backs up the file, extracts your customizations, and regenerates it from a version-matched template fetched from GitHub or the bundled fallback.

How do I migrate .nav-config.json to a newer Navigator version?

Run config_migrator.py against .agent/.nav-config.json to add config sections introduced in releases after your recorded version and bump the version marker. Use the --dry-run flag to preview changes without writing, or --json for machine-readable output.

Will updating CLAUDE.md overwrite my custom code standards and forbidden actions?

No. The updater extracts project name, description, tech stack, custom code standards, forbidden actions, PM tool setting, and custom sections before regeneration, then reinserts them into the new template. A backup file is always created first.

Why does CLAUDE.md regeneration refuse to run with a hook-liveness error?

Regeneration is gated on proof that the Navigator hook runtime is live, checked via a fresh .nav-runtime-state.json or .nav-dispatch-health.json in the .agent directory. Start a Claude Code session in the project so the dispatcher stamps the state file, then re-run the sync.

Does config migration downgrade a newer config version?

No. The migrator only bumps the version when the existing config is older than the installed plugin version. A config recording a newer version is left untouched, and existing config blocks are never overwritten.

What happens if the GitHub template fetch fails during the update?

The updater falls back to the bundled CLAUDE.md template shipped with the installed plugin, so the migration works offline. If neither source is available, it reports a template-not-found error and leaves your file unchanged.