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

> Discover how Zettelkasten linking transforms atomic skills into a connected knowledge network in Stage 3 of the Cangjie Skill Pipeline. Learn about depends-on, contrasts-with, and composes-with relationships.

- Repository: [kangarooking/cangjie-skill](https://github.com/kangarooking/cangjie-skill)
- Tags: deep-dive
- Published: 2026-08-13

---

**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`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/candidates/glossary.md) to `books/<slug>/GLOSSARY.md` and reference it from [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/books/forward-reasoning/SKILL.md):

```yaml
---
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`](https://github.com/kangarooking/cangjie-skill/blob/main/SKILL.md) receives a human-readable "Related Skills" section that translates YAML relationships into explanatory prose:

```markdown

## 相关 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:

```markdown

# {{ 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`](https://github.com/kangarooking/cangjie-skill/blob/main/methodology/05-stage3-zettelkasten.md) | Complete Stage 3 specification, relationship types, and execution steps |
| `templates/INDEX.md.template` | Jinja2 template for generating [`INDEX.md`](https://github.com/kangarooking/cangjie-skill/blob/main/INDEX.md) files with Mermaid graphs |
| `books/<slug>/SKILL.md` | Individual skill files storing front‑matter YAML and "Related Skills" sections |
| [`candidates/glossary.md`](https://github.com/kangarooking/cangjie-skill/blob/main/candidates/glossary.md) | Shared terminology source, promoted to per‑skill [`GLOSSARY.md`](https://github.com/kangarooking/cangjie-skill/blob/main/GLOSSARY.md) |
| [`README.en.md`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/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`](https://github.com/kangarooking/cangjie-skill/blob/main/README.en.md) Section 5.