sequential-navigation by alexander-kastil/agentic-sw-engineering

Overview

The sequential-navigation skill provides a complete framework for organizing and navigating multi-file markdown documentation. It enables you to:

Break down large documents into manageable, sequential sections
Add intelligent navigation with three link types:
- ↑ Internal: Jump to top of current file
- ← Contextual: Return to main documentation hub
- → Sequential: Move to next file in workflow
Create guided workflows where users progress through documentation in a logical order

When to Use This Skill

Use sequential-navigation when you have:

Monolithic documentation that would benefit from being split into multiple files
Tutorial or exercise guides with ordered steps across multiple documents
Workflow documentation where users need to progress through sections sequentially
Learning materials where navigation helps maintain orientation and context
Step-by-step procedures that span multiple markdown files
Documentation sets that require easy jumping between related topics

How This Skill Works

The Three Navigation Link Types

1. Contextual Navigation (← Back to Hub)

Appears at the top and throughout each file, provides a permanent link back to the central documentation hub.

[← Back to Exercise Instructions](../readme.md#exercise-instructions)

2. Internal Navigation (↑ Back to top)

Allows users to instantly return to the file's beginning from the navigation bar.

[↑ Back to top](#main-heading)

3. Sequential Navigation (→ Next Section)

Guides users to the next file in the workflow, displayed in the navigation bar.

[→ Next: Section Name](next-file.md)

Step-by-Step Implementation

Phase 1: Analyze Your Large Document

Read through the entire document and identify all major sections (marked with ## headings)
List sections in logical order
Sequence them - determine the order users should read/process them
Identify dependencies - which sections require knowledge from previous ones?
Group content - decide which subsections should stay together vs. split

Phase 2: Create Your File Structure

Preserve a central hub - usually the main README with overview and links
Create a subdirectory for instruction files (e.g., /instructions)
Name files sequentially or descriptively:
- Sequential: 01-setup.md, 02-config.md, 03-implement.md
- Descriptive: setup.md, configuration.md, implementation.md

Phase 3: Extract Content into Files

Copy content from the original document into individual files
Preserve headings as the main file heading (#)
Keep subsections as secondary headings (##, ###)
Remove extracted content from the hub document and replace with links

Phase 4: Reorganize the Hub Document

Update your main documentation file to:

Keep the overview/introduction explaining the documentation's purpose
Add a links section pointing to each instruction file
Organize links under category headings that match your workflow
Use descriptive text explaining what each file contains

Example:

# Main Documentation

Brief overview of the documentation.

## Getting Started

- [Set up the project](instructions/setup.md)
- [Configure your environment](instructions/configuration.md)

## Implementation

- [Build the feature](instructions/implementation.md)
- [Test your work](instructions/testing.md)

Phase 5: Add Navigation Links

Now add the three navigation types to each file:

At the top of each file (after title):

# File Title

[← Back to Exercise Instructions](../readme.md#exercise-instructions)

**Table of Contents:**
- [Section 1](#section-1)
- [Section 2](#section-2)

---

At the bottom of each file (except the last), use a full-width navigation bar:

---

<div style="display: flex; justify-content: space-between; padding: 1rem 0; border-top: 1px solid #ccc; border-bottom: 1px solid #ccc;">
  <a href="../readme.md#exercise-instructions">← Back to Exercise Instructions</a>
  <a href="#file-title">↑ Back to top</a>
  <a href="next-file.md">→ Next: Next File Title</a>
</div>

At the bottom of the last file, use:

---

<div style="display: flex; justify-content: space-between; padding: 1rem 0; border-top: 1px solid #ccc; border-bottom: 1px solid #ccc;">
  <a href="../readme.md#exercise-instructions">← Back to Exercise Instructions</a>
  <a href="#file-title">↑ Back to top</a>
</div>

Complete Example

Here's a complete before/after example showing how to transform a large document:

Directory Structure

readme.md (main hub - 100 lines total)
├── instructions/
│   ├── setup.md (30 lines)
│   ├── configuration.md (35 lines)
│   ├── implementation.md (40 lines)
│   └── testing.md (25 lines)

Sample File: instructions/setup.md

# Set up the project

[← Back to Exercise Instructions](../readme.md#exercise-instructions)

**Table of Contents:**
- [Installation](#installation)
- [Verification](#verification)

---

## Installation

Follow these steps to install the project...

## Verification

Verify the installation is correct...

---

<div style="display: flex; justify-content: space-between; padding: 1rem 0; border-top: 1px solid #ccc; border-bottom: 1px solid #ccc;">
  <a href="../readme.md#exercise-instructions">← Back to Exercise Instructions</a>
  <a href="#set-up-the-project">↑ Back to top</a>
  <a href="configuration.md">→ Next: Configure your environment</a>
</div>

Sample File: instructions/configuration.md (last file)

# Configure your environment

[← Back to Exercise Instructions](../readme.md#exercise-instructions)

**Table of Contents:**
- [Settings](#settings)
- [Verification](#verification)

---

## Settings

Configure these settings...

## Verification

Verify your configuration...

---

<div style="display: flex; justify-content: space-between; padding: 1rem 0; border-top: 1px solid #ccc; border-bottom: 1px solid #ccc;">
  <a href="../readme.md#exercise-instructions">← Back to Exercise Instructions</a>
  <a href="#configure-your-environment">↑ Back to top</a>
</div>

Best Practices

Consistent Link Format: Use the same arrow symbols and formatting throughout
- ↑ for internal navigation
- ← for contextual navigation to hub
- → for sequential next-section navigation
Relative Paths: Use relative paths (e.g., ../readme.md) for cross-file navigation
- More portable and works with local file viewing
- Easier to reorganize folder structure
Anchor Naming: Keep heading text simple and anchor-friendly
- Use lowercase letters and hyphens
- Avoid special characters in headings
- Make anchors human-readable
Order Matters: Ensure the sequential flow matches logical learning/usage progression
- Start with foundational concepts
- Progress to advanced topics
- End with cleanup or next steps
Main Hub Identification: Clearly identify the central documentation hub with an #exercise-instructions or similar anchor for consistent linking back
Test Links: Verify all links work correctly
- Test relative path navig
- Always use the same arrow symbols (↑, ←, →)
- Keep link styling consistent across all files
- Use clear, descriptive link text
Relative Paths
- Use ../ notation to navigate between directories
- More portable than absolute paths
- Works with local file browsing and GitHub
Anchor Naming
- Convert heading to lowercase with hyphens: # Create Specifications → #create-specifications
- Avoid special characters in headings
- Keep anchors simple and readable
Logical Flow
- Start with foundational concepts
- Progress to intermediate topics
- End with advanced or cleanup steps
- Ensure sequential order matches user needs
Hub Identification
- Use a consistent anchor name for your hub (e.g., #exercise-instructions)
- Clearly mark the central location
- Every file should link back to it
Testing
- Test all relative path links
- Verify anchors match actual headings exactly
- Check that the last file returns properly to hub
- Validate in both local editor and GitHub

Common Use Cases

Tutorial Series

Multiple lesson files guiding users through a complete course with sequential navigation between lessons.

Step-by-Step Guides

Sequential procedure files where users work through tasks in order, with clear navigation between steps.

Exercise Workflows

Training exercises with ordered phases (setup → specification → planning → implementation → testing).

Contributing Guidelines

Onboarding documentation for new contributors with navigation through setup, coding standards, and submission processes.

Learning Paths

Organized educational content where pre-requisite knowledge flows into advanced topics.

Product Documentation

Feature documentation organized by complexity with clear navigation between related features.