How INDEX.md with Mermaid Diagrams Visualizes cangjie-skill Relationships

INDEX.md serves as an auto-generated skill map that renders Mermaid flowcharts to visualize three relationship types—depends-on, contrasts-with, and composes-with—between skills in the kangarooking/cangjie-skill repository.

The kangarooking/cangjie-skill repository implements a structured RIA-TV++ pipeline that transforms raw inputs into reusable skill modules. During Stage 5 – Zettelkasten Linking, the system generates INDEX.md as a centralized navigation hub that visualizes how individual skills interconnect. This file leverages Mermaid syntax to create a living diagram that reflects the current state of the entire skill ecosystem without manual maintenance.

The Role of INDEX.md in the RIA-TV++ Pipeline

After extraction, verification, and RIA-TV++ structuring steps, each skill resides in its own folder containing a SKILL.md file with metadata including title, description, triggers, and boundaries. According to the methodology defined in methodology/05-stage3-zettelkasten.md, the Zettelkasten stage scans these folders to discover relationships and synthesize them into a directed graph.

The resulting INDEX.md file, rendered from templates/INDEX.md.template, serves as the authoritative "skill map" for both human readers and AI agents navigating the repository.

Three Relationship Types Visualized in the Mermaid Graph

The pipeline identifies three distinct relationship categories, each represented by specific Mermaid edge syntax in the generated diagram.

depends-on (-->)

Dependency relationships indicate that one skill requires the knowledge or output of another before it can be executed. In the Mermaid diagram, these appear as solid arrows (-->) connecting prerequisite skills to dependent ones. This visualization reveals the critical path for learning or invoking capabilities in the correct sequence.

contrasts-with (-.->)

Contrast relationships highlight alternative viewpoints or methodological approaches to solving similar problems. These render as dashed arrows (-.->), signaling that connected skills offer different philosophical or technical paths rather than sequential dependencies. This helps users identify when multiple valid approaches exist for a single challenge.

composes-with (===>)

Composition relationships demonstrate how simpler skills combine to form higher-level capabilities. Thick arrows (===>) visualize these synergies, showing which primitive skills aggregate into complex workflows or compound abilities.

How the Zettelkasten Linking Stage Generates the Diagram

The generation process occurs automatically during the pipeline's execution. The system iterates through all skill directories, parsing the relationship metadata defined in each SKILL.md file to construct the graph edges.

Here is the pseudo-code illustrating how the pipeline constructs the Mermaid graph and writes it to INDEX.md:

# Gather relationships from each skill's metadata

edges = []
for skill in all_skills:
    for dep in skill.depends_on:
        edges.append(f"{skill.id} -->|depends-on| {dep.id}")
    for alt in skill.contrasts_with:
        edges.append(f"{skill.id} -.->|contrasts-with| {alt.id}")
    for comp in skill.composes_with:
        edges.append(f"{skill.id} ===>|composes-with| {comp.id}")

# Write the mermaid block into INDEX.md

with open("INDEX.md", "w") as f:
    f.write("## 引用图\n\n```mermaid\ngraph LR\n")

    f.write("\n".join(edges))
    f.write("\n```\n")

This automation ensures that adding, removing, or re-categorizing a skill immediately updates the visualization without manual editing of INDEX.md.

Navigating the Skill Ecosystem with the Generated Diagram

The generated Mermaid diagram transforms a flat collection of SKILL.md files into an interactive knowledge map. A typical generated block appears as follows:

## 引用图

```mermaid
graph LR
    A[skill-a] -->|depends-on| B[skill-b]
    A -.->|contrasts-with| C[skill-c]
    B ===>|composes-with| D[skill-d]

By following the directed arrows, users can identify:

- **Dependency chains**: The sequential order in which skills must be learned or invoked
- **Alternative paths**: Points where two skills address the same problem from different angles
- **Composition possibilities**: How primitive skills assemble into sophisticated capabilities

The diagram also powers the **recommended learning sequence** detailed later in [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/INDEX.md), which typically progresses from leaf nodes (foundational skills) upward toward complex compositions.

## Summary

- [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/INDEX.md) is auto-generated during **Stage 5 – Zettelkasten Linking** of the cangjie-skill pipeline
- **Mermaid diagrams** visualize three relationship types: `depends-on` (-->), `contrasts-with` (-.->), and `composes-with` (===>)
- The diagram reads metadata from individual [`SKILL.md`](https://github.com/kangarooking/cangjie-skill/blob/main/SKILL.md) files across skill directories using the template in `templates/INDEX.md.template`
- Relationships reveal dependency chains, alternative approaches, and compositional hierarchies
- The visualization automatically updates to reflect repository changes, eliminating manual maintenance

## Frequently Asked Questions

### What is the purpose of INDEX.md in cangjie-skill?

[`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/INDEX.md) functions as the central skill map for the kangarooking/cangjie-skill repository. It aggregates relationship metadata from all skill folders to provide a unified view of how individual capabilities interconnect, helping users navigate dependencies and learning paths efficiently according to the RIA-TV++ methodology.

### How are Mermaid diagrams generated automatically?

During the Zettelkasten linking stage, the pipeline scans each skill's metadata in [`SKILL.md`](https://github.com/kangarooking/cangjie-skill/blob/main/SKILL.md) files to extract `depends-on`, `contrasts-with`, and `composes-with` relationships. It then renders these into Mermaid syntax using the template defined in `templates/INDEX.md.template`, writing the resulting graph into [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/INDEX.md) without requiring manual intervention.

### What do the different arrow types represent in the diagram?

Solid arrows (`-->`) represent **dependencies** where one skill requires another, dashed arrows (`-.->`) indicate **contrasts** showing alternative approaches, and thick arrows (`===>`) denote **composition** where skills combine into higher-level capabilities. These symbols correspond directly to the relationship metadata stored in each skill's configuration.

### How does the diagram determine recommended learning sequences?

The learning sequence starts from leaf nodes (skills with no dependencies) and progresses upward through the dependency graph. By analyzing the `depends-on` relationships in the Mermaid visualization, the system constructs a topological ordering that ensures prerequisites are mastered before dependent skills, as documented in the pipeline's [`README.md`](https://github.com/kangarooking/cangjie-skill/blob/main/README.md).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}