Purpose of GLOSSARY.md in cangjie-skill: Central Dictionary vs. Skill Definitions

GLOSSARY.md serves as the central terminology dictionary for the cangjie-skill repository, aggregating shared definitions across all skill modules to ensure consistency, while individual SKILL.md files define the behavioral logic and implementation details of specific capabilities.

The cangjie-skill project organizes knowledge into discrete, reusable modules. Understanding the distinction between the global glossary and individual skill definitions is essential for navigating and contributing to the repository effectively.

What Is GLOSSARY.md in cangjie-skill?

GLOSSARY.md functions as the central terminology dictionary for the entire repository. It consolidates every term, concept, and definition that appears across multiple skill modules into a single, authoritative reference.

This file resides at the root of the generated repository and is shared by all skills. The content consists of a curated list of terms—often extracted automatically by the glossary-extractor—paired with concise definitions or explanations. During the Zettelkasten stage of the workflow, the extractor gathers candidate terms from source text, and the project scaffolding moves the temporary file from candidates/glossary.md to the final GLOSSARY.md location at the repository root.

According to the methodology documented in methodology/05-stage3-zettelkasten.md (lines 33-34), this movement ensures the glossary is centrally accessible. The file is then linked from INDEX.md as specified in methodology/07-stage5-deliver.md (lines 22-23), enabling readers to navigate quickly to the shared dictionary.

How GLOSSARY.md Differs from Skill Definitions

While GLOSSARY.md defines terminology, skill definitions describe behavioral logic. A skill definition lives in its own */SKILL.md file, representing a self-contained module that specifies its purpose, trigger sentences, output format, and implementation details.

The key distinctions include:

• Scope: GLOSSARY.md provides one entry per term for global reuse, while each SKILL.md focuses on a single skill's functionality.
• Location: The glossary sits at the repository root; skill definitions reside inside individual skill folders.
• Generation: The glossary is produced by the glossary-extractor during parallel extraction (methodology/02-stage1-parallel-extract.md, lines 40-41), whereas skills are generated by various specialized extractors (framework, principle, case, etc.).
• Content: Glossary entries explain what a term means; skill definitions specify how a capability behaves.

Skills may reference terms from the glossary, but they do not define the terminology itself. This separation maintains clean architectural boundaries between vocabulary and functionality.

The Zettelkasten Workflow: Generating the Glossary

The creation of GLOSSARY.md follows a specific pipeline within the cangjie-skill methodology:

1. Parallel Extraction: During Stage 1, the glossary-extractor runs alongside other extractors to identify key concepts from source materials.
2. Candidate Collection: Terms are initially written to candidates/glossary.md as temporary storage.
3. Final Placement: In Stage 3 (Zettelkasten), the build process moves candidates/glossary.md to the repository root as GLOSSARY.md.

This workflow ensures that terminology is collected systematically across all source materials before being finalized as the authoritative dictionary.

Practical Implementation Examples

Referencing Terms from a Skill File

Skill definitions can link to the global glossary to avoid duplicating term definitions:

<!-- Inside books/example/skill/SKILL.md -->

### Example Skill: 解释文字

本技能接受用户的文字描述，并返回对应的 **概念解释**。  
使用的术语请参见全局词典：[`GLOSSARY.md`](../GLOSSARY.md) → *“概念解释”*。

The Glossary Extraction Pipeline

The extractor processes source text and stages the output before final integration:

# After parallel extraction completes

mv candidates/glossary.md books/example/GLOSSARY.md

This command, referenced in the Zettelkasten stage documentation, transitions the glossary from temporary candidate status to its permanent position.

Linking from the Index

The INDEX.md file serves as the navigation hub, explicitly connecting readers to the glossary:

# INDEX.md (auto-generated)

- [Skill Map](SKILL.md)
- [Global Glossary](GLOSSARY.md)   <!-- central term dictionary -->

This structure ensures discoverability of both functional skills and the terminology they employ.

Summary

• GLOSSARY.md acts as the central terminology dictionary for the entire cangjie-skill repository, located at the root and shared across all modules.
• It is generated by the glossary-extractor during the parallel extraction phase and finalized during the Zettelkasten stage by moving from candidates/glossary.md.
• Skill definitions in */SKILL.md files describe behavioral logic and implementation, distinct from the glossary's focus on term definitions.
• The glossary is linked from INDEX.md, providing global access to shared vocabulary while skills remain self-contained in their respective folders.

Frequently Asked Questions

Where is GLOSSARY.md located in the cangjie-skill repository?

GLOSSARY.md resides at the root of the generated repository. According to methodology/05-stage3-zettelkasten.md, the file is moved from the temporary candidates/glossary.md location to the repository root during the Zettelkasten stage, making it accessible to all skill modules.

How are terms added to GLOSSARY.md?

Terms are added through automated extraction by the glossary-extractor during Stage 1 (parallel extraction). The extractor identifies key concepts from source text and writes them to candidates/glossary.md. During the build process, this temporary file is relocated to the root as the final GLOSSARY.md, as documented in methodology/02-stage1-parallel-extract.md.

Can a skill exist without referencing GLOSSARY.md?

Yes. While skills may reference terms from the glossary for clarity, each */SKILL.md file is self-contained and focuses on behavioral logic rather than terminology definitions. A skill defines its purpose, triggers, and output format independently, though linking to the glossary improves consistency across the repository.

What is the difference between glossary-extractor and other extractors?

The glossary-extractor specifically targets terminology and concept definitions for the global dictionary, whereas other extractors (such as framework, principle, or case extractors) generate individual skill definitions. As noted in methodology/02-stage1-parallel-extract.md (lines 40-41), the glossary-extractor runs in parallel with these specialized extractors but outputs to the shared glossary rather than individual skill files.

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