Agent skill

Nav Diagnose

by qf-studio in qf-studio/navigator

Detect quality drops in AI output and prompt re-anchoring. An agent skill from qf-studio/navigator.

MITAuto-check: notes

Install Nav Diagnose

skills CLI
$ npx skills add qf-studio/navigator --skill nav-diagnose -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install qf-studio/navigator nav-diagnose --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/qf-studio/navigator.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/nav-diagnose .claude/skills/nav-diagnose && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
nav-diagnose
GitHub stars
355
Token cost
~2.4k tokens
SKILL.md length
526 words
Files
2
Skills in repo
32
Repo updated
First seen
Licence
MIT

At a glance

Detect quality drops in AI output and prompt re-anchoring. An agent skill from qf-studio/navigator.

  • Works in 12 steps: Repeated Corrections (High Severity) → Hallucination Signals (High Severity) → Context Confusion (Medium Severity) → …
  • After repeated corrections
  • SKILL.md covers Why This Exists (Theory of Mind), When to Invoke, Quality Drop Indicators and Execution Steps, plus 4 more sections
  • Runs Python scripts from its folder; calls claude

What it does

Nav Diagnose is an agent skill from qf-studio/navigator. Detect quality drops in AI output and prompt re-anchoring. Auto-triggers after repeated corrections, context confusion, or when user says "something seems off", "you're not getting this".

Its SKILL.md is about 2.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files (for example `functions/quality_detector.py`).

The repository describes itself as: Finish What You Start — Context engineering for Claude Code. Sessions last 20+ exchanges instead of crashing at 7. The licence is MIT.

When your agent uses it

  • After repeated corrections
  • Context confusion
  • User says something seems off
  • Youre not getting this

Example prompts

  • “something seems off”
  • “re not getting this”
  • “/nav-diagnose”

Requirements

  • Python 3
  • Pre-approved tools (allowed-tools): Read, Write, Bash

Workflow steps

12 steps, taken from the step headings in SKILL.md.

  1. Repeated Corrections (High Severity)
  2. Hallucination Signals (High Severity)
  3. Context Confusion (Medium Severity)
  4. Unaddressed Feedback (Medium Severity)
  5. Goal Drift (Low Severity)
  6. Loop Stagnation (High Severity)
  7. Assess Quality State
  8. Identify Root Cause
  9. Display Diagnostic
  10. Re-anchor Collaboration
  11. Log Diagnostic (Optional)
  12. Suggest Preventive Actions

What it can do on your machine

Read from SKILL.md and the folder at commit 3bb9eac. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Write
    • Bash

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships script files (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • claude

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Nav Diagnose loads about 2.4k tokens when it runs. Until then it costs about 50 tokens; SKILL.md has 526 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~50
When it runs · the whole SKILL.md, loaded when a task matches
~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
    allowed-tools: Read, Write, Bash

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from qf-studio/navigator at commit 3bb9eac, republished under its MIT licence (© qf-studio). 526 words, ~2,408 tokens.

Download SKILL.mdSave it as .claude/skills/nav-diagnose/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
nav-diagnose
description
Detect quality drops in AI output and prompt re-anchoring. Auto-triggers after repeated corrections, context confusion, or when user says "something seems off", "you're not getting this".
allowed-tools
Read, Write, Bash
version
1.0.0

Navigator Diagnose Skill

Detect when human-AI collaboration quality drops and prompt re-anchoring to restore effective communication.

Why This Exists (Theory of Mind)

Based on Riedl & Weidmann 2025 research on Human-AI Synergy:

  • Theory of Mind varies dynamically within users (moment-to-moment)
  • Quality drops occur when ToM alignment degrades
  • Early detection and re-anchoring restores collaboration effectiveness
  • Both user ToM (understanding Claude) and Claude's model of user can drift

This skill detects when collaboration is degrading and prompts corrective action.

When to Invoke

Auto-invoke when:

  • 2+ corrections on the same topic detected
  • User says "something seems off", "you're not getting this"
  • User says "wrong again", "still not right"
  • Context usage exceeds 75% and quality signals degrade
  • User expresses frustration ("ugh", "sigh", explicit frustration)
  • Loop mode stagnation detected (3+ same-state iterations)

DO NOT invoke if:

  • Single correction (normal collaboration)
  • User is providing new requirements (not correcting)
  • Fresh session (insufficient data to diagnose)
  • User explicitly says "it's fine" or "close enough"

Quality Drop Indicators

1. Repeated Corrections (High Severity)
Trigger: Same correction given 2+ times
Signal: "No, I said users plural, not user" (2nd time)
Issue: Not incorporating user feedback
2. Hallucination Signals (High Severity)
Trigger: References to non-existent files, functions, or packages
Signal: "That file doesn't exist", "There's no such function"
Issue: Generating from incorrect mental model
3. Context Confusion (Medium Severity)
Trigger: Mixing details from unrelated tasks
Signal: "That's from the other project", "Wrong feature"
Issue: Context window pollution or misattribution
4. Unaddressed Feedback (Medium Severity)
Trigger: User correction not reflected in next output
Signal: Generates same pattern after being told not to
Issue: Not properly updating internal model
5. Goal Drift (Low Severity)
Trigger: Output increasingly diverges from original goal
Signal: "We're getting off track", "Not what I asked for"
Issue: Lost sight of user's actual objective
6. Loop Stagnation (High Severity)
Trigger: 3+ consecutive iterations with same state hash (loop mode only)
Signal: nav-loop detects stagnation, triggers nav-diagnose
Issue: Stuck on same step, unable to progress

Execution Steps

Step 1: Assess Quality State

Analyze recent exchanges (last 10-15 messages):

Quality Indicators:
- [ ] Corrections given: {count}
- [ ] Same-topic corrections: {count}
- [ ] User frustration signals: {count}
- [ ] Hallucination reports: {count}
- [ ] "Not what I meant" phrases: {count}

Calculate severity:

python
severity = "critical" if same_topic_corrections >= 2 or hallucinations >= 1
severity = "high" if corrections >= 3 or frustration_signals >= 2
severity = "medium" if corrections >= 2 or goal_drift_detected
severity = "low" if corrections == 1  # Normal, don't trigger
Step 2: Identify Root Cause

Analyze correction patterns:

PatternLikely CauseRe-anchoring Focus
Same correction repeatedNot incorporating feedbackExplicitly acknowledge and confirm understanding
Increasing correctionsDrifting from user intentRe-establish goals
Technical mismatchesWrong assumptionsClarify technical context
Frustration without specificsCommunication mismatchAsk what's wrong
Step 3: Display Diagnostic

Show quality check alert:

⚠️  QUALITY CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Detected Issue: {ISSUE_TYPE}
Severity: {SEVERITY}

What I noticed:
- {OBSERVATION_1}
- {OBSERVATION_2}

Possible causes:
- {CAUSE_1}
- {CAUSE_2}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Let me re-anchor our collaboration:

1. Your goal: {RECONSTRUCTED_GOAL}
2. Current state: {STATE_SUMMARY}
3. What you want: {CORRECTED_UNDERSTANDING}

Is this understanding correct? [Y/n]
Step 4: Re-anchor Collaboration

Based on user confirmation:

If correct (Y):

✅ Re-anchored!

I'll proceed with this understanding:
- {KEY_POINT_1}
- {KEY_POINT_2}

Continuing with: {NEXT_ACTION}

If incorrect (n):

Help me understand better:

1. What is your actual goal?
2. What am I getting wrong?
3. What constraints should I know?

[Open-ended response welcome]
Step 5: Log Diagnostic (Optional)

If nav-profile exists, save diagnostic:

json
{
  "date": "{YYYY-MM-DD}",
  "issue_type": "{ISSUE_TYPE}",
  "severity": "{SEVERITY}",
  "resolution": "re-anchored|user-corrected|escalated",
  "learnings": ["{WHAT_TO_AVOID}"]
}
Step 6: Suggest Preventive Actions

Based on severity and pattern:

For context overload:

💡 Suggestion: Consider running nav-compact to clear context.
Current context usage is high, which can cause confusion.

For repeated corrections:

💡 Suggestion: Let me save your preference to avoid this in future.
"Remember I always want {X}" - This will persist across sessions.

For communication mismatch:

💡 Suggestion: Consider adjusting your profile preferences.
- Current verbosity: {VERBOSITY}
- Current confirmation: {CONFIRMATION}

Update with: "Remember I prefer {SUGGESTED_STYLE}"

Re-anchoring Templates

Template 1: Goal Re-alignment
Let me verify I understand your goal:

You want to: {GOAL_STATEMENT}

Not: {COMMON_MISUNDERSTANDING}

Key constraints:
- {CONSTRAINT_1}
- {CONSTRAINT_2}

Is this right?
Template 2: Technical Re-alignment
Let me verify the technical context:

Framework: {FRAMEWORK}
Patterns: {PATTERNS}
Conventions: {CONVENTIONS}

What I should be using:
- {TOOL_1}: for {PURPOSE_1}
- {TOOL_2}: for {PURPOSE_2}

Corrections to my assumptions?
Template 3: Communication Re-alignment
I may be mismatching your communication style:

You seem to prefer:
- {INFERRED_STYLE_1}
- {INFERRED_STYLE_2}

I've been:
- {MY_STYLE_1}
- {MY_STYLE_2}

Should I adjust my approach?

Show full SKILL.md (211 more words)Show less

Integration with Other Skills

With nav-profile
  • Log diagnostics for pattern analysis
  • Suggest preference updates after repeated issues
  • Load profile preferences for baseline comparison
With nav-marker
  • Suggest marker before major re-anchoring
  • Include diagnostic state in marker
With nav-compact
  • Recommend compact if context overload detected
  • Track if compaction resolves issues

Quality Signals Reference

Positive Signals (Good Collaboration)
- "Perfect, exactly what I needed"
- "Yes, continue"
- "Good, now..."
- No corrections for 5+ exchanges
- User providing new requirements (not corrections)
Negative Signals (Quality Drop)
- "No", "Wrong", "Not that"
- "I already said..."
- "Again, please..."
- "Sigh", "Ugh", explicit frustration
- "You're not understanding"
- Same correction twice
Neutral Signals (Normal Iteration)
- "Actually, let's try..."
- "Can we also..."
- "What about..."
- Single correction with explanation

Example Scenarios

Scenario 1: Repeated REST Convention Correction
Exchange 1:
User: "Create endpoint for users"
Claude: Creates /user endpoint
User: "Should be /users (plural)"

Exchange 2:
User: "Now create endpoint for posts"
Claude: Creates /post endpoint
User: "Again, plural! /posts"

→ Trigger: Same correction (plural naming) given twice
→ Action: Re-anchor on REST conventions
→ Outcome: "I understand now - always use plural nouns for REST resources"
Scenario 2: Context Confusion
User working on: OAuth feature (Feature A)
Claude references: Stripe integration (Feature B from earlier)

User: "That's from the payment feature, not auth"

→ Trigger: Context confusion detected
→ Action: Re-anchor on current feature
→ Suggestion: Consider nav-compact to clear old context
Scenario 3: User Frustration
User: "Ugh, still not right"
User: "This is frustrating"

→ Trigger: Frustration signals detected
→ Action: Pause and diagnose
→ Response: Open-ended question about what's wrong

Success Criteria

Diagnostic is successful when:

  • Quality drops detected before user escalates
  • Root cause correctly identified
  • Re-anchoring restores collaboration quality
  • Preventive suggestions are actionable
  • User confirms understanding after re-anchor
  • Same issue doesn't recur immediately

Limitations

Cannot detect:

  • Silent user frustration (no signals in text)
  • Issues outside conversation context
  • Problems with external systems
  • User preferences not yet expressed

Should not:

  • Over-trigger on normal corrections
  • Interrupt productive flow
  • Make user feel blamed
  • Require lengthy re-explanation

Best Practices

When diagnosing:

  • Be humble about AI limitations
  • Don't blame user for miscommunication
  • Offer concrete next steps
  • Keep re-anchoring brief

When re-anchoring:

  • Focus on understanding, not apologizing
  • Confirm specific points, not general "I understand"
  • Let user correct if wrong
  • Thank user for patience

This skill catches collaboration quality drops early, enabling quick recovery through Theory of Mind re-alignment 🔍

© qf-studio, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file in skills/nav-diagnose of qf-studio/navigator.

  • SKILL.md
  • functions/quality_detector.py

Open the folder on GitHubat commit 3bb9eac

Compare with similar skills

Nav Diagnose next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Nav Diagnose compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Nav Diagnose this skillqf-studio/navigator355—~2.4kAutomated safety check: NotesMIT
Diagnose Gatewayopenclaw/openclaw392k—~670Automated safety check: PassMIT
Threat Detectionalirezarezvani/claude-skills28k—~3.5kAutomated safety check: PassMIT
Diagnosegithub/awesome-copilot40k1 repos~1kAutomated safety check: PassMIT
Resemble Detectgithub/awesome-copilot40k3 repos~4.1kAutomated safety check: PassApache-2.0
Pii Detectruvnet/ruflo74k—~350Automated safety check: NotesMIT

Similar skills

  • Diagnose Gateway

    openclaw/openclaw

    Diagnose Gateway, config, secrets, channels, and port failures with read-only one-liners.

    392k GitHub stars~670 tokensUpdated today
    Auto-check passed
  • Threat Detection

    alirezarezvani/claude-skills

    A skill your agent uses when hunting for threats in an environment, analyzing IOCs, or detecting behavioral anomalies in telemetry.

    28k GitHub stars~3.5k tokensUpdated 1 mo ago
    SecurityAuto-check passed
  • Diagnose

    github/awesome-copilot

    Official

    Perform a systematic diagnostic scan of an AI workflow across 5 quality dimensions — prompt quality, context efficiency, tool health, architecture fitness, and safety — producing a scored report…

    40k GitHub starsUsed in 1 repo~1k tokens
    Agent WorkflowsAuto-check passed
  • Resemble Detect

    github/awesome-copilot

    Official

    Deepfake detection and media safety — detect AI-generated audio, images, video, and text, trace synthesis sources, apply watermarks, verify speaker identity, and analyze media intelligence using…

    40k GitHub starsUsed in 3 repos~4.1k tokens
    Media & CreativeAuto-check passed
  • Pii Detect

    ruvnet/ruflo

    Detect and flag personally identifiable information (PII) in text, code, and configurations.

    74k GitHub stars~350 tokensUpdated yesterday
    Auto-check: notes
  • Anchor Text

    thedaviddias/Front-End-Checklist

    A skill your agent uses when auditing metadata, crawlability, structured data, or indexability related to Use descriptive anchor text.

    74k GitHub stars~426 tokensUpdated 5 days ago
    Marketing & SEOAuto-check passed

More from qf-studio/navigator

All 32 skills in this repo
  • Nav Start

    qf-studio/navigator

    Load Navigator documentation navigator when starting development session, resuming work, or beginning new feature.

    355 GitHub stars~4.7k tokensUpdated 2 days ago
    Auto-check: notes
  • Backend Endpoint

    qf-studio/navigator

    Create REST/GraphQL API endpoint with validation, error handling, and tests.

    355 GitHub stars~4.5k tokensUpdated 2 days ago
    Auto-check: notes
  • Backend Test

    qf-studio/navigator

    Generate backend tests (unit, integration, mocks) for existing code.

    355 GitHub stars~1.5k tokensUpdated 2 days ago
    Auto-check: notes
  • Database Migration

    qf-studio/navigator

    Create database migration with schema changes and rollback. An agent skill from qf-studio/navigator.

    355 GitHub stars~3.7k tokensUpdated 2 days ago
    Auto-check: notes
  • Frontend Component

    qf-studio/navigator

    Create React/Vue component with TypeScript, tests, and styles.

    355 GitHub stars~4.5k tokensUpdated 2 days ago
    Auto-check: notes
  • Frontend Test

    qf-studio/navigator

    Generate frontend component tests (React Testing Library, Vue Test Utils, snapshot) for existing components.

    355 GitHub stars~1.6k tokensUpdated 2 days ago
    Auto-check: notes

Questions about Nav Diagnose

What does Nav Diagnose do?

Detect quality drops in AI output and prompt re-anchoring. An agent skill from qf-studio/navigator. Nav Diagnose is an agent skill from qf-studio/navigator. Detect quality drops in AI output and prompt re-anchoring.

When should I use Nav Diagnose?

Nav Diagnose fits situations like: after repeated corrections; context confusion; user says something seems off; youre not getting this.

How do I install Nav Diagnose in Claude Code?

Run `npx skills add qf-studio/navigator --skill nav-diagnose -a claude-code`. Or copy the skill folder (skills/nav-diagnose in qf-studio/navigator) into .claude/skills/nav-diagnose in your project. Claude Code loads it when a task matches its description.

How do I install Nav Diagnose in Codex?

Run `npx skills add qf-studio/navigator --skill nav-diagnose -a codex`. Or copy the skill folder (skills/nav-diagnose in qf-studio/navigator) into .agents/skills/nav-diagnose in your project. Codex loads it when a task matches its description.

Can I use Nav Diagnose in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add qf-studio/navigator --skill nav-diagnose -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/nav-diagnose, .gemini/skills/nav-diagnose, .github/skills/nav-diagnose and .opencode/skills/nav-diagnose in your project.

What does Nav Diagnose need to run?

Going by SKILL.md and its folder, Nav Diagnose needs Python for the scripts in its folder and the command-line tools its instructions call (claude). Our summary lists: Python 3. Its frontmatter pre-approves these tools: Read, Write, Bash.

Does Nav Diagnose access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Nav Diagnose safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Nav Diagnose use?

Nav Diagnose is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Nav Diagnose use?

About 2.4k tokens (SKILL.md is roughly 9.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Nav Diagnose?

Skills that share tags, products or a category with Nav Diagnose: Diagnose Gateway (openclaw/openclaw, 392k stars), Threat Detection (alirezarezvani/claude-skills, 28k stars), Diagnose (github/awesome-copilot, 40k stars) and Resemble Detect (github/awesome-copilot, 40k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Nav Diagnose?

qf-studio (a GitHub organization) maintains it in qf-studio/navigator, which has 355 GitHub stars. The repository holds 32 skills in this directory. The repository was last updated on October 8, 2026.

Source: qf-studio/navigator on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.