How Zettelkasten Linking Connects Skills in Stage 3 of the Cangjie Skill Pipeline

Stage 3 uses Zettelkasten linking to convert isolated atomic skills into a navigable knowledge network through three explicit relationship types: depends‑on, contrasts‑with, and composes‑with.

Zettelkasten linking in the Cangjie skill-building methodology transforms the standalone capabilities produced in Stage 2 into an interconnected system. By recording semantic relationships between skills as structured metadata, the pipeline generates both human-readable documentation and machine-parsable dependency graphs—without requiring any external database.

---

The Three Relationship Types in Cangjie Zettelkasten Linking

Every skill connection in Stage 3 is classified into one of three relationship types defined in methodology/05-stage3-zettelkasten.md:

• depends‑on — Skill A requires mastery of Skill B as a prerequisite. This builds the foundation for automated learning-path generation.

• contrasts‑with — Skill A and Skill B represent alternative approaches that learners should evaluate side-by-side.

• composes‑with — Skill A is frequently combined with Skill B in practical application, signaling complementary usage patterns.

These three relationship types enable both explicit navigation (browsing related skills) and dependency‑driven learning paths (topological sorting for study order).

---

The 7-Step Stage 3 Execution Process

According to the source code analysis, Zettelkasten linking follows a strict 7-step workflow:

1. Enumerate every skill generated in Stage 2.

2. Perform a pair‑wise scan to detect the three relationship types between all skill combinations.

3. For each skill, add a related_skills list to its front‑matter YAML block.

4. Append a "Related Skills" section to the skill's SKILL.md file, describing the links in natural language.

5. Return to the skill's A2 section and replace provisional differentiation text with finalized descriptions—syncing the front‑matter description field simultaneously.

6. Render a per‑skill books/<slug>/INDEX.md file from templates/INDEX.md.template.

7. Promote the shared candidates/glossary.md to books/<slug>/GLOSSARY.md and reference it from INDEX.md.

No external database is required. The entire network persists as ordinary markdown files, making the knowledge base fully version‑controlled and human‑readable.

---

YAML Metadata: Storing Zettelkasten Relationships

Relationships are encoded in skill front‑matter as structured YAML. From books/forward-reasoning/SKILL.md:

---
title: 正向推理
slug: forward-reasoning
description: 用已知事实向前推导结论的思维方式
related_skills:
  - slug: multi-mental-models
    relation: depends-on
  - slug: reverse-thinking
    relation: contrasts-with
  - slug: safety-margin
    relation: composes-with
---

The related_skills list functions as the machine-readable backbone of the Zettelkasten system. Each entry contains:

• slug: The target skill's unique identifier
• relation: One of the three canonical relationship types

---

Natural Language Documentation: The "Related Skills" Section

Each SKILL.md receives a human-readable "Related Skills" section that translates YAML relationships into explanatory prose:

## 相关 Skills

- **依赖**：正向推理 依赖 **多元思维模型**（需要先掌握模型才能构造推理步骤）。
- **对比**：正向推理 对比 **逆向思维**（两者提供互补的推理视角）。
- **组合**：正向推理 常与 **安全边际** 组合使用，以确保推理结论在风险容忍范围内。

This dual representation—structured YAML for machines, natural language for humans—ensures the Zettelkasten network serves both automated tooling and manual browsing.

---

Automated INDEX.md Generation with Mermaid Graphs

The template at templates/INDEX.md.template renders each skill's network into a comprehensive navigation document:

# {{ book.title }} — INDEX

## 基本信息

- **作者**: {{ book.author }}
- **年份**: {{ book.year }}
- **主旨**: {{ book.tagline }}

## Skill 列表

{% for group in book.skill_groups %}

### {{ group.name }}

{% for skill in group.skills %}
- [{{ skill.title }}]({{ skill.path }})
{% endfor %}
{% endfor %}

## 引用图

```mermaid
graph LR
{% for edge in book.edges %}
  {{ edge.from }} -->|{{ edge.relation }}| {{ edge.to }}
{% endfor %}

推荐学习顺序

依据 depends‑on 链条自动生成的拓扑排序。

The Mermaid diagram in the **引用图** (Citation Graph) section visualizes all outgoing relationships for immediate pattern recognition.

---

## Rendered Output Example

The final [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/INDEX.md) presents relationships in a compact, scannable format:

```markdown
- **正向推理** → **多元思维模型** (depends‑on)
- **正向推理** ↔ **逆向思维** (contrasts‑with)
- **正向推理** → **安全边际** (composes‑with)

Arrows indicate directionality: unidirectional for depends‑on and composes‑with, bidirectional for contrasts‑with.

---

Key Files in the Zettelkasten Linking Implementation

File	Purpose
methodology/05-stage3-zettelkasten.md	Complete Stage 3 specification, relationship types, and execution steps
templates/INDEX.md.template	Jinja2 template for generating INDEX.md files with Mermaid graphs
books/<slug>/SKILL.md	Individual skill files storing front‑matter YAML and "Related Skills" sections
candidates/glossary.md	Shared terminology source, promoted to per‑skill GLOSSARY.md
README.en.md (Section 5)	High‑level overview of Zettelkasten linking for end users

---

Summary

• Zettelkasten linking in Stage 3 creates three explicit relationship types (depends‑on, contrasts‑with, composes‑with) between atomic skills.

• Relationships are stored as YAML front‑matter in SKILL.md files and rendered as natural language sections for human readers.

• The 7-step process converts isolated skills into a navigable network without external databases—everything persists in version‑controlled markdown.

• Template-driven generation produces INDEX.md files containing Mermaid relationship graphs and topologically-sorted learning recommendations.

• The implementation relies entirely on simple metadata conventions, making the knowledge base portable, inspectable, and tool-agnostic.

---

Frequently Asked Questions

What are the three relationship types used in Cangjie Zettelkasten linking?

The three relationship types are depends‑on (prerequisite relationships), contrasts‑with (alternative approaches worth comparing), and composes‑with (frequently combined skills). These are defined in methodology/05-stage3-zettelkasten.md and stored in each skill's YAML front‑matter related_skills list.

How does Zettelkasten linking generate learning paths automatically?

The depends‑on relationships form a directed acyclic graph that enables topological sorting. The templates/INDEX.md.template uses these edges to generate a "推荐学习顺序" (Recommended Learning Order) section, presenting skills in prerequisite-respecting sequence without manual curation.

Why does Cangjie use both YAML and natural language for the same relationships?

The dual representation serves different audiences: YAML front‑matter enables programmatic processing (graph traversal, validation, template generation) while the "Related Skills" markdown section provides immediate human comprehension. Both are stored in the same SKILL.md file to ensure synchronization.

Where is the Zettelkasten linking logic documented in the repository?

The canonical specification resides in methodology/05-stage3-zettelkasten.md, with implementation examples visible in any books/<slug>/SKILL.md file and the rendering template at templates/INDEX.md.template. High-level context appears in README.en.md Section 5.

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