Agent-Skills.md

Agent Skills: Index Navigator

Navigate index.md files generated by the catalogador tool to identify the minimal set of documents or sections to read. Use this skill when exploring directories that contain index.md files, when attempting to read documentation in indexed folders, or when optimizing context usage by reading only relevant sections instead of entire documents.

UncategorizedID: edneyreis999/zord-project/index-navigator

Repository

edneyreis999/zord-project
edneyreis999

Install this agent skill to your local

pnpm dlx add-skill https://github.com/edneyreis999/zord-project/tree/HEAD/service_financial-claude/skills/index-navigator

Skill Files

Browse the full folder contents for index-navigator.

Download Skill

Loading file tree…

service_financial-claude/skills/index-navigator/SKILL.md

Skill Metadata

Name
index-navigator
Description
Navigate index.md files generated by the catalogador tool to identify the minimal set of documents or sections to read. Use this skill when exploring directories that contain index.md files, when attempting to read documentation in indexed folders, or when optimizing context usage by reading only relevant sections instead of entire documents.

Index Navigator

Overview

Navigate catalogador-generated index.md files to determine which documents or sections to read, minimizing unnecessary context consumption. Output the stdout 📚 index-navigator invocado na pasta: <PASTA> before any other action.

When to Invoke

Invoke this skill immediately when:

  1. Attempting to read any document within a directory containing index.md
  2. Listing a directory and finding index.md among the files
  3. Exploring a folder structure where index.md exists

Rule of thumb: If index.md exists in the target directory, use it as a navigation guide before reading any other file.

First Action: stdout

Before performing any reads or navigation, output a single-line log to the terminal:

📚 index-navigator invocado na pasta: <PASTA>

Determining <PASTA>:

  • If triggered by reading a document: use the document's directory path
  • If triggered by listing a directory: use that directory path

Mental Model

Treat each index.md as a menu that:

  • Lists available files and subdirectories
  • Indicates when to use or ignore each item
  • Provides quick navigation paths (links/anchors)
  • Often includes token cost estimates per section

Golden Rule: Read index.md first. Read complete documents only when necessary.

Reading index.md Files

When opening an index.md, extract only these sections:

1. Navegação Rápida (Quick Navigation)

  • Maps "want X → read Y" directly
  • Prefer this path when it matches the request

2. Arquivos (Files)

For each file, focus on:

  • Objetivo principal (Main objective)
  • Use quando (Use when)
  • Não cobre (Does not cover)
  • Estrutura (Structure: anchor links + token estimates)

3. Subpastas (Subdirectories)

For each subdirectory, focus on:

  • Resumo (Summary)
  • Quando explorar (When to explore)
  • Quando ignorar (When to ignore)

4. Escopo (Scope)

Determines whether this directory is relevant for the current task.

Ignore other sections unless needed for disambiguation.

Navigation Workflow

Step 1: Choose Initial index.md

  • If triggered in a specific directory, start with that directory's index.md
  • If multiple indices exist, prefer:
    1. Current directory's index.md (where exploring)
    2. Parent index.md if current is too narrow

Step 2: Decide Navigation Path Using index.md

Decision order:

  1. Navegação Rápida contains the answer → follow indicated link
  2. Otherwise, use Arquivos:
    • Select file whose Use quando best matches the request
    • Respect Não cobre (if it falls there, wrong file)
  3. If correct file not listed, use Subpastas:
    • Enter only subdirectories marked Quando explorar that match the case
    • Avoid those indicating Quando ignorar for this scenario

Step 3: Navigate Levels if Stuck

  • Index too general and doesn't point to target → descend to subdirectories
  • Index too specific and doesn't mention topic → ascend to parent index

Reading Strategy: Section vs Complete Document

When index.md offers anchors/sections, apply these rules:

Read ONLY A SECTION when

  • Request is specific
  • Index already points to a corresponding anchor
  • Section is visibly smaller than total document
  • File has well-defined Estrutura (clear headings)

Read COMPLETE DOCUMENT when

  • Request is broad and requires full view
  • Index doesn't offer useful anchors (or no clear headings)
  • Answer depends on multiple scattered sections (≥3) and sum approaches total
  • File is explicitly "foundational" (overview/architecture/cross-cutting) and request depends on global understanding
  • Total estimated tokens are small (e.g., ≤ ~1200–1500 tokens) and reading entire reduces risk of missing context

Decision Heuristic

If index provides tokens per section:

  • 1 section resolves → read 1 section
  • 2 sections resolve → read 2 sections
  • 3+ sections needed and sum > ~60% of total → read complete document

If NO token estimates:

  • Prefer section if clear anchor exists
  • If need to hunt across multiple headings → read complete document

Assertive Reading Without Overreading

Before opening a complete document, answer internally:

  1. "What exact question does this file answer?"
  2. "Is there a section/anchor that already delivers this?"
  3. "How many sections do I actually need?"

If unable to answer (1) based on the index, likely in the wrong index (ascend/descend and try another).

Expected Output

Produce for the agent a short list (1–5) of recommended reads, each containing:

  • Path: File path
  • Target: section/anchor OR complete document
  • Reason: Single sentence referencing "Use quando / Não cobre / Navegação rápida"

Example:

1. docs/sso/auth0-setup.md#token-generation (section)
   Reason: "Use quando" indicates this section covers token generation workflows.

2. docs/techspec-backend.md (complete document)
   Reason: Request requires understanding of full backend architecture; multiple sections needed.