Context Navigator Skill

Date: 2026-05-08 Status: v0.3.0-ready

What It Is

Context Navigator is a portable Agent Skill for Markdown-heavy workspaces. It teaches an AI agent to bootstrap, navigate, maintain, and validate a lightweight index system for docs folders, Obsidian vaults, decision logs, research folders, personal knowledge bases, and documentation-heavy project workspaces.

It is intentionally not RAG, not a vector database, not a recursive scanner, and not an Obsidian plugin. Its job is practical workspace hygiene: create human-readable maps, preserve context budget, and make source reading traceable.

When To Use It

Use it when your workspace has enough durable Markdown that "just search everything" starts to fail:

• project docs
• Obsidian vaults
• decision logs
• personal knowledge bases
• multi-app repositories
• research folders

It can work in four modes:

Mode	What it does
Navigate	Uses existing indexes to read only what matters
Bootstrap	Creates a root map and key INDEX.md files for important folders
Maintain	Updates indexes as folders grow, files move, or authority changes
Validate	Checks index schema, required sections, and local links

Good triggers:

• the user explicitly asks to bootstrap, organize, index, or make a Markdown workspace AI-readable
• the workspace has no durable root map and has several long-term Markdown areas
• docs, decisions, notes, reports, research, or archive material are mixed together
• existing indexes have stale links, missing routes, or inconsistent structure

Avoid using it as the primary tool for:

• ordinary TypeScript, Python, Swift, or other source-code navigation
• single-file edits or small bug fixes
• repositories where useful navigation comes from package manifests, types, routes, tests, and source structure rather than Markdown docs

For code repositories, use Context Navigator only for durable docs, architecture notes, decisions, specs, and runbooks.

Change Safety

If a user explicitly asks an agent to use this skill for a task that will create or edit files, the agent should first give a concise change plan and wait for confirmation.

The plan should include:

• mode: Navigate, Bootstrap, Maintain, or Validate
• scope to inspect
• likely files to create or update
• validation command or review check

Read-only Navigate tasks do not need this extra confirmation.

Install

Copy skill/context-navigator/ into your agent's skill directory.

For Codex:

~/.codex/skills/context-navigator/

For a project-local skill setup, copy the folder into the project's configured skills path.

For platform-specific notes, see:

• adapters/codex/README.md
• adapters/claude/README.md
• adapters/cursor/README.md
• DISTRIBUTION.md

Usage

Ask the agent to use the skill on a Markdown workspace:

Use $context-navigator to understand this workspace and tell me which docs matter for the billing system.

Or ask it to create the index system:

Use $context-navigator to bootstrap an index system for this Markdown workspace.

Expected behavior:

• start from a root map such as CONTEXT.md, README.md, or INDEX.md
• create a root map if the workspace has no durable entry point
• add key INDEX.md files for important long-term folders
• skip dependency folders, build outputs, hidden internals, temporary folders, and archives unless explicitly requested
• report created indexes, skipped folders, read files, and remaining gaps

Validate indexes:

Use $context-navigator to validate the index system for this Markdown workspace.

Or run the bundled script directly from the skill folder:

python scripts/validate_indexes.py /path/to/workspace

Migration Guide

To convert an existing Markdown workspace manually:

1. Add a root map: CONTEXT.md, root README.md, or root INDEX.md.
2. List major domains and their preferred entry files.
3. Add INDEX.md to any durable folder that has several Markdown files.
4. Mark authority sources separately from archive, raw notes, and one-time analysis.
5. Add task-routing tables for common user intents.
6. During future work, update the nearest index whenever durable docs move or grow.

Do not migrate by bulk-adding frontmatter or building a search database first. The first win is a human-readable route.

Repository Layout

Path	Purpose
skill/context-navigator/SKILL.md	Portable Agent Skill
skill/context-navigator/references/bootstrap-workflow.md	Workflow for creating indexes in a real workspace
skill/context-navigator/references/index-template.md	Template for workspace and domain indexes
skill/context-navigator/references/navigation-checklist.md	Task-time reading checklist
skill/context-navigator/references/maintenance-rules.md	Rules for keeping an indexed workspace healthy
skill/context-navigator/scripts/validate_indexes.py	Schema and local-link validator for CONTEXT.md and INDEX.md
adapters/codex/README.md	Codex install notes
adapters/claude/README.md	Claude upload notes
adapters/cursor/context-navigator.mdc	Cursor rule bridge
marketplaces/mcplug-listing.md	Third-party marketplace listing copy
DISTRIBUTION.md	Release and distribution checklist
examples/minimal-workspace/CONTEXT.md	Small example workspace
examples/minimal-workspace/bootstrap-prompt.md	Example prompt for creating indexes
tests/test_validate_indexes.py	Unit tests for the validator
LICENSE	MIT license

Task Routing

User intent	First read	Then read	Do not read first
Understand this repository	README.md	skill/context-navigator/SKILL.md	Unrelated local workspace files
Bootstrap indexes in a user workspace	SKILL.md	references/bootstrap-workflow.md and references/index-template.md	Recursive full-document scan
Edit the skill	SKILL.md	Relevant reference file	All examples recursively
Test navigation behavior	examples/minimal-workspace/CONTEXT.md	One domain index and 1-3 docs	Every Markdown file
Validate index schema	SKILL.md	Run scripts/validate_indexes.py	Manual full-doc audit
Prepare GitHub release	README.md and skill/context-navigator/SKILL.md	Example workspace	Internal source material

Maintenance Rules

• Keep the skill portable and English-first for public reuse.
• Put detailed procedures in references/, not in SKILL.md, unless they are core trigger-time behavior.
• Keep examples small, artificial, and safe to publish.
• Update this README when adding durable directories or changing public positioning.
• Run python -m unittest tests.test_validate_indexes after changing the validator.
• Run python skill/context-navigator/scripts/validate_indexes.py examples/minimal-workspace after changing example indexes.

License

MIT.