glossary-generator
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseGlossary Generator
术语表生成器
Generate a comprehensive glossary of terms from a learning graph's concept list with ISO 11179-compliant definitions.
基于学习图谱的概念列表生成符合ISO 11179规范的全面术语表。
TOKEN EFFICIENCY WARNING
Token效率警告
This skill generates large files (2,000+ lines). Token cost matters far more than
wall-clock time for teacher users on limited budgets.
Default approach: ONE serial Task agent that writes all definitions directly to
a temp file. This is the most token-efficient method because:
- System prompt / tool description overhead is paid only once (~12K tokens)
- No coordination or assembly overhead
- Proven to complete a 350-term glossary in ~31K tokens (2026-03-14 benchmark)
本Skill会生成大文件(2000行以上)。对于预算有限的教师用户来说,Token成本远比运行时间重要。
默认方案:单串行Task Agent,直接将所有定义写入临时文件。这是Token效率最高的方案,原因如下:
- 系统提示/工具描述开销仅需支付一次(约12K Token)
- 无协调或组装开销
- 经实测,生成含350个术语的术语表仅需约31K Token(2026-03-14基准测试)
Measured Token Economics (350-term benchmark, 2026-03-14)
实测Token成本(2026-03-14,350个术语基准)
| Component | Tokens | Notes |
|---|---|---|
| Agent overhead (system prompt + tools) | ~12K | Paid once for serial, 4× for parallel |
| Definition generation (350 terms) | ~19K | Unavoidable LLM work |
| Assembly (Python script) | ~700 | Trivial programming task |
| Total (serial) | ~31K |
Tokens per term: ~88 total, ~54 marginal (after subtracting one-time overhead).
The marginal cost is calculated as: (30,788 − 12,000) / 350 = ~54 tokens/term.
Use this to estimate costs for glossaries of any size:
| Glossary size | Estimated total tokens |
|---|---|
| 100 terms | ~17K (12K overhead + 5.4K generation) |
| 200 terms | ~23K |
| 350 terms | ~31K (measured) |
| 500 terms | ~39K |
| 组成部分 | Token数 | 说明 |
|---|---|---|
| Agent开销(系统提示+工具) | ~12K | 串行方案仅付一次,并行方案需支付4倍 |
| 定义生成(350个术语) | ~19K | 不可避免的LLM工作 |
| 组装(Python脚本) | ~700 | 简单编程任务 |
| 总计(串行方案) | ~31K |
每个术语平均Token消耗:总计约88,边际成本约54(扣除一次性开销后)。
边际成本计算方式:(30,788 − 12,000) / 350 = 约54 Token/术语。
你可以用这个数值估算任意规模术语表的生成成本:
| 术语表规模 | 预估总Token消耗 |
|---|---|
| 100个术语 | ~17K(12K开销 + 5.4K生成成本) |
| 200个术语 | ~23K |
| 350个术语 | ~31K(实测值) |
| 500个术语 | ~39K |
Why Parallel Execution Should NEVER Be Used
为何绝对不应使用并行执行
Each parallel agent pays the full ~12K system prompt overhead independently.
For glossary generation, the definitions are completely independent — there is
no speedup benefit that justifies the cost. The serial agent writes all terms
in a single Write call and finishes in ~6 minutes, which is perfectly acceptable.
| Approach | Agent overhead | Generation | Assembly | Total | Waste |
|---|---|---|---|---|---|
| 1 serial agent (recommended) | ~12K (once) | ~19K | ~700 | ~31K | — |
| 4 parallel agents + script | ~48K (4×) | ~19K | ~700 | ~68K | +37K (119%) |
| 4 parallel agents + manual Edit | ~48K (4×) | ~19K | ~200K | ~267K | +236K (761%) |
Parallel execution more than doubles the token cost for zero quality benefit.
For teachers on the Claude Pro plan (~200K token five-hour budget), the serial
approach uses ~16% of their budget vs. 34% (parallel) or 100%+ (manual assembly).
NEVER use parallel agents for glossary generation. The token waste is not justified.
Always use the serial approach. Do not offer parallel as an option.
The assembly step (sorting and writing the final file) MUST always use a Python
script — NEVER manually emit glossary content through Edit/Write tool calls.
See for the full post-mortem.
logs/glossary-generation-very-inefficient.md每个并行Agent都需要独立支付约12K的系统提示开销。术语表生成的各个定义完全独立,并行执行不会带来任何值得额外成本的速度提升。串行Agent仅需一次Write调用即可写入所有术语,耗时约6分钟,完全在可接受范围内。
| 方案 | Agent开销 | 生成成本 | 组装成本 | 总计 | 浪费 |
|---|---|---|---|---|---|
| 1个串行Agent(推荐) | ~12K(仅一次) | ~19K | ~700 | ~31K | — |
| 4个并行Agent+脚本 | ~48K(4倍) | ~19K | ~700 | ~68K | 多花37K(119%) |
| 4个并行Agent+手动编辑 | ~48K(4倍) | ~19K | ~200K | ~267K | 多花236K(761%) |
并行执行不会带来任何质量提升,却会让Token成本翻倍不止。对于使用Claude Pro套餐的教师(5小时预算约200K Token),串行方案仅消耗约16%的预算,而并行方案消耗34%,手动组装则会消耗100%以上的预算。
术语表生成绝对不要使用并行Agent,Token浪费完全没有价值。
始终使用串行方案,不要提供并行选项。
组装步骤(排序和写入最终文件)必须始终使用Python脚本完成——绝对不要通过Edit/Write工具调用手动输出术语表内容。完整事后分析请参见。
logs/glossary-generation-very-inefficient.mdPurpose
用途
This skill automates glossary creation for intelligent textbooks by converting concept labels from a learning graph into properly formatted glossary definitions. Each definition follows ISO 11179 metadata registry standards: precise, concise, distinct, non-circular, and free of business rules. The skill ensures consistency across terminology, validates cross-references, and produces alphabetically ordered entries with relevant examples.
Following a short definition you may provide a discussion of why the term is important in the textbook and an example of how the term is used.
本Skill可将学习图谱的概念标签转换为格式规范的术语表定义,实现智能教材术语表创建的自动化。每个定义都遵循ISO 11179元数据注册标准:精准、简洁、独特、无循环定义且不包含业务规则。本Skill可确保术语一致性,验证交叉引用,生成按字母排序的条目并附上相关示例。
在简短定义之后,你可以补充说明该术语在教材中的重要性,以及术语使用示例。
When to Use This Skill
何时使用本Skill
Use this skill after the Learning Graph skill has completed and the concept list has been finalized. All markdown content in the /docs area can also be scanned looking for words or phases that might not be clear to the average high-school student.
The glossary relies on having a complete, reviewed list of concepts from the learning graph's concept enumeration phase. Specifically, trigger this skill when:
- A concept list file exists (typically )
docs/learning-graph/02-concept-list-v1.md - The concept list has been reviewed and approved
- The course description exists with clear learning outcomes
- Ready to create or update the textbook's glossary
在学习图谱Skill运行完成、概念列表最终确定后使用本Skill。你也可以扫描/docs目录下的所有Markdown内容,查找普通高中生可能不理解的词汇或短语。
术语表生成依赖学习图谱概念枚举阶段产出的完整、经过审核的概念列表。具体来说,满足以下条件时可触发本Skill:
- 存在概念列表文件(通常为)
docs/learning-graph/02-concept-list-v1.md - 概念列表已经过审核和批准
- 存在明确学习目标的课程描述
- 准备创建或更新教材的术语表
Workflow
工作流程
Step 1: Validate Input Quality
步骤1:验证输入质量
Before generating definitions, assess the quality of the concept list:
- Read the concept list file (typically )
docs/learning-graph/02-concept-list-v1.md - Check for duplicate concept labels (target: 100% unique)
- Verify Title Case formatting (target: 95%+ compliance)
- Validate length constraints (target: 98% under 32 characters)
- Assess concept clarity (no ambiguous terms)
Calculate a quality score (1-100 scale):
- 90-100: All concepts unique, properly formatted, appropriate length
- 70-89: Most concepts meet standards, minor formatting issues
- 50-69: Some duplicate concepts or formatting inconsistencies
- Below 50: Significant issues requiring manual review
User Dialog Triggers:
- If score < 70: Ask "The concept list has quality issues. Would you like to review and clean it before generating the glossary?"
- If duplicates found: Ask "Found [N] duplicate concepts. Should I remove duplicates automatically or would you like to review?"
- If formatting issues: Ask "Found [N] concepts with formatting issues. Auto-fix?"
生成定义之前,先评估概念列表的质量:
- 读取概念列表文件(通常为)
docs/learning-graph/02-concept-list-v1.md - 检查重复的概念标签(目标:100%唯一)
- 验证首字母大写格式(目标:95%以上符合规范)
- 验证长度约束(目标:98%的术语长度低于32个字符)
- 评估概念清晰度(无歧义术语)
计算质量得分(1-100分):
- 90-100:所有概念唯一、格式正确、长度合适
- 70-89:大部分概念符合标准,仅存在少量格式问题
- 50-69:存在部分重复概念或格式不一致问题
- 低于50:存在严重问题,需要人工审核
用户对话触发条件:
- 如果得分<70:询问「概念列表存在质量问题。生成术语表前是否需要先审核并清理?」
- 如果发现重复项:询问「发现[N]个重复概念。我应该自动删除重复项还是你需要先审核?」
- 如果存在格式问题:询问「发现[N]个概念存在格式问题。是否自动修复?」
Step 2: Read Course Context
步骤2:读取课程上下文
Read the course description file () and any other markdonw files in to understand:
docs/course-description.md/docs/**/*.md- Target audience (for appropriate example complexity)
- Course objectives (for terminology alignment)
- Prerequisites (for background knowledge assumptions)
- Learning outcomes (for context on concept usage)
读取课程描述文件()以及下的所有其他Markdown文件,了解以下信息:
docs/course-description.md/docs/**/*.md- 目标受众(用于设置合适的示例复杂度)
- 课程目标(用于对齐术语使用)
- 前置要求(用于设定背景知识假设)
- 学习成果(用于了解概念使用场景)
Step 3: Generate Definitions Using a Single Serial Agent
步骤3:使用单个串行Agent生成定义
Default approach (most token-efficient): Launch ONE Task agent that generates
all definitions and writes them directly to a single temp file.
Task agent prompt:
"Generate ISO 11179-compliant glossary definitions for the following [N] terms.
Write ALL entries as markdown (#### headers with definitions, examples, and
discussion) to the file /tmp/glossary-raw.md using the Write tool.
Each entry uses #### for the term header. Do not return the content in your
response — just confirm the file was written and report the term count.
[Paste the full term list here]
[Paste course description context here for audience level]"The single agent writes all definitions to one file. This pays system-prompt overhead
only once (~12K tokens) and avoids all coordination costs. Proven at ~31K tokens
for a 350-term glossary (~88 tokens/term total, ~54 tokens/term marginal).
Do NOT use parallel agents for glossary generation. See the TOKEN EFFICIENCY
WARNING section above for why parallel execution should never be used — it more
than doubles the token cost for zero quality benefit.
For each concept in the list, create a definition that follows ISO 11179 standards:
Precision (25 points): Accurately capture the concept's meaning
- Define the concept specifically in the context of the course
- Use terminology appropriate for the target audience
- Ensure the definition matches how the concept is used in the course
Conciseness (25 points): Keep definitions brief (target: 20-50 words)
- Avoid unnecessary words or explanations
- Get to the core meaning quickly
- Use clear, direct language
Distinctiveness (25 points): Make each definition unique and distinguishable
- Avoid copying definitions from other sources
- Ensure no two definitions are too similar
- Highlight what makes this concept different from related concepts
Non-circularity (25 points): Avoid circular dependencies
- Do not reference undefined terms in definitions
- Do not create circular chains (A depends on B, B depends on A)
- Use simpler, more fundamental terms in definitions
Example Format:
For a concept "Learning Graph":
markdown
undefined默认方案(Token效率最高): 启动1个Task Agent生成所有定义,直接写入单个临时文件。
Task agent prompt:
"Generate ISO 11179-compliant glossary definitions for the following [N] terms.
Write ALL entries as markdown (#### headers with definitions, examples, and
discussion) to the file /tmp/glossary-raw.md using the Write tool.
Each entry uses #### for the term header. Do not return the content in your
response — just confirm the file was written and report the term count.
[Paste the full term list here]
[Paste course description context here for audience level]"单个Agent将所有定义写入一个文件,仅需支付一次系统提示开销(约12K Token),避免所有协调成本。经实测,生成含350个术语的术语表仅需约31K Token(平均每个术语约88 Token,边际成本约54 Token/术语)。
术语表生成绝对不要使用并行Agent。 参考上文Token效率警告部分了解为何不应使用并行执行——它不会带来任何质量提升,却会让Token成本翻倍不止。
列表中的每个概念都要生成符合ISO 11179标准的定义:
精准性(25分): 准确传达概念的含义
- 结合课程上下文明确定义概念
- 使用适合目标受众的术语
- 确保定义与课程中概念的使用方式一致
简洁性(25分): 定义保持简短(目标:20-50个词)
- 避免不必要的词汇或解释
- 快速切入核心含义
- 使用清晰、直接的语言
独特性(25分): 每个定义都唯一、可区分
- 不要复制其他来源的定义
- 确保没有两个定义过于相似
- 突出该概念与相关概念的区别
无循环性(25分): 避免循环依赖
- 定义中不要引用未定义的术语
- 不要创建循环链(A依赖B,B依赖A)
- 定义中使用更简单、更基础的术语
示例格式:
针对「Learning Graph」概念:
markdown
undefinedLearning Graph
Learning Graph
A directed graph of concepts that reflects the order that concepts should be learned to master a new concept.
Learning graphs are the foundational data structure use for intelligent textbooks. They are used to guide
intelligent agents and recommend learning paths for students.
Example: In a programming course, the learning graph shows that "Variables" must be understood before "Functions," which must be understood before "Recursion."
undefinedA directed graph of concepts that reflects the order that concepts should be learned to master a new concept.
Learning graphs are the foundational data structure use for intelligent textbooks. They are used to guide
intelligent agents and recommend learning paths for students.
Example: In a programming course, the learning graph shows that "Variables" must be understood before "Functions," which must be understood before "Recursion."
undefinedStep 4: Add Examples (60-80% of terms)
步骤4:添加示例(60-80%的术语)
For most concepts (target: 60-80%), include a relevant example:
- Start with "Example:" (no newline after colon)
- Provide a concrete illustration from the course domain
- Keep examples brief (1-2 sentences)
- Ensure examples clarify the concept without adding confusion
大部分概念(目标:60-80%)都要附上相关示例:
- 以「Example:」开头(冒号后不要换行)
- 提供课程领域内的具体示例
- 示例保持简短(1-2句话)
Step 5: Add Cross-References
步骤5:添加交叉引用
Where appropriate, reference related terms:
- Use "See also:" for related concepts
- Use "Contrast with:" for opposing concepts
- Ensure all cross-referenced terms exist in the glossary
- Keep cross-references to 1-3 per term
合适的场景下引用相关术语:
- 相关概念使用「See also:」
- 对立概念使用「Contrast with:」
- 确保所有交叉引用的术语都存在于术语表中
- 每个术语的交叉引用控制在1-3个
Step 6: Assemble Glossary File Using a Python Script
步骤6:使用Python脚本组装术语表文件
CRITICAL: NEVER manually assemble the glossary through Edit/Write tool calls.
Alphabetical sorting and file merging is a trivial programming task. Doing it manually
through LLM text generation wastes 100,000+ tokens that cost real money.
MANDATORY APPROACH: Write and execute a Python script via the Bash tool that:
- Reads the agent output file(s) — (serial) or
/tmp/glossary-raw.md(parallel)/tmp/glossary-part-*.md - Parses entries by splitting on headers
#### - Sorts entries alphabetically (case-insensitive) using
sorted() - Writes the final in one pass
docs/glossary.md
Reference script (adapt paths as needed):
python
#!/usr/bin/env python3
"""Merge glossary parts into a single sorted glossary."""
import glob, os, re
entries = {}关键提醒:绝对不要通过Edit/Write工具调用手动组装术语表。 字母排序和文件合并是非常简单的编程任务,通过LLM文本生成手动完成会浪费10万以上的Token,产生不必要的成本。
强制方案: 通过Bash工具编写并执行Python脚本,完成以下操作:
- 读取Agent输出文件——(串行方案)或
/tmp/glossary-raw.md(并行方案)/tmp/glossary-part-*.md - 按标题拆分条目
#### - 使用按字母顺序(不区分大小写)排序条目
sorted() - 一次性写入最终的文件
docs/glossary.md
参考脚本(可根据需要调整路径):
python
#!/usr/bin/env python3
"""Merge glossary parts into a single sorted glossary."""
import glob, os, re
entries = {}Support both serial (single file) and parallel (multiple files)
Support both serial (single file) and parallel (multiple files)
if os.path.exists('/tmp/glossary-raw.md'):
sources = ['/tmp/glossary-raw.md']
else:
sources = sorted(glob.glob('/tmp/glossary-part-*.md'))
for path in sources:
with open(path) as f:
content = f.read()
for block in re.split(r'\n(?=#### )', content):
block = block.strip()
m = re.match(r'#### (.+)', block)
if m:
entries[m.group(1).strip()] = block
sorted_terms = sorted(entries.keys(), key=lambda t: t.lower().lstrip('0123456789-'))
with open('docs/glossary.md', 'w') as out:
out.write('# Glossary of Terms\n\n')
for term in sorted_terms:
out.write(entries[term] + '\n\n')
print(f"Wrote {len(sorted_terms)} terms to docs/glossary.md")
Run this script with `python3 /tmp/assemble_glossary.py` via the Bash tool.
Total cost: ~500 tokens for the script + ~200 tokens for output = **~700 tokens**
(versus 200,000+ tokens if done manually through Edit calls).
**NEVER DO ANY OF THE FOLLOWING:**
- Write glossary entries directly through the Write or Edit tool
- Copy-paste subagent output into Edit tool old_string/new_string parameters
- Manually sort terms by emitting them in alphabetical order
- Append sections to the glossary file one at a time through Edit calls
**Formatting rules for the assembled file:**
- Do not put any `---` strings in the glossary. They are not needed.
- Sort all terms alphabetically (case-insensitive) — the script handles this
- Use level-4 headers (####) for term names
- Place definition in body text (no special formatting)
- Use "**Example:**" for examples (bold, with colon)
- Maintain consistent spacing between entries (one blank line between entries)if os.path.exists('/tmp/glossary-raw.md'):
sources = ['/tmp/glossary-raw.md']
else:
sources = sorted(glob.glob('/tmp/glossary-part-*.md'))
for path in sources:
with open(path) as f:
content = f.read()
for block in re.split(r'\n(?=#### )', content):
block = block.strip()
m = re.match(r'#### (.+)', block)
if m:
entries[m.group(1).strip()] = block
sorted_terms = sorted(entries.keys(), key=lambda t: t.lower().lstrip('0123456789-'))
with open('docs/glossary.md', 'w') as out:
out.write('# Glossary of Terms\n\n')
for term in sorted_terms:
out.write(entries[term] + '\n\n')
print(f"Wrote {len(sorted_terms)} terms to docs/glossary.md")
通过Bash工具执行`python3 /tmp/assemble_glossary.py`运行脚本。
总成本:脚本约500 Token + 输出约200 Token = **约700 Token**(如果通过Edit调用手动完成则需要20万以上Token)。
**绝对不要执行以下操作:**
- 直接通过Write或Edit工具写入术语表条目
- 把子Agent的输出复制粘贴到Edit工具的old_string/new_string参数中
- 手动按字母顺序输出术语进行排序
- 通过Edit调用逐个向术语表文件追加内容
**组装文件的格式规则:**
- 术语表中不要添加任何`---`分隔符,不需要使用
- 所有术语按字母顺序排序(不区分大小写)——脚本会自动处理
- 术语名称使用4级标题(####)
- 定义放在正文部分(无需特殊格式)
- 示例使用「**Example:**」格式(加粗,带冒号)
- 条目之间保持一致的间距(两个条目之间空一行)Step 7: Generate Quality Report
步骤7:生成质量报告
Create with:
docs/learning-graph/glossary-quality-report.mdISO 11179 Metadata Registry Compliance Metrics:
For each definition, score on 5 criteria (25 points each):
- Precision: Does it accurately capture the meaning?
- Conciseness: Is it brief (20-50 words)?
- Distinctiveness: Is it unique and distinguishable?
- Non-circularity: No circular dependencies?
- Unencumbered by business rules: Free of specific policies or rules?
Overall Quality Metrics:
- Average definition length: [X] words
- Definitions meeting all 4 criteria: [X]%
- Circular definitions found: [X]
- Example coverage: [X]%
- Cross-references: [X] total, [X] broken
Readability:
- Flesch-Kincaid grade level: [X]
- Appropriate for target audience: Yes/No
Recommendations:
- List any definitions scoring < 70/100
- Identify circular dependencies to fix
- Suggest concepts needing examples
- Note any broken cross-references
创建,包含以下内容:
docs/learning-graph/glossary-quality-report.mdISO 11179元数据注册合规指标:
每个定义按5个维度评分(每个维度25分):
- 精准性:是否准确传达了含义?
- 简洁性:是否足够简短(20-50个词)?
- 独特性:是否唯一、可区分?
- 无循环性:是否不存在循环依赖?
- 无业务规则:是否不包含特定政策或规则?
整体质量指标:
- 平均定义长度:[X]个词
- 符合所有4项标准的定义占比:[X]%
- 发现的循环定义数量:[X]
- 示例覆盖率:[X]%
- 交叉引用总数:[X],无效交叉引用数:[X]
可读性:
- Flesch-Kincaid年级可读性水平:[X]
- 是否适合目标受众:是/否
建议:
- 列出所有得分<70/100的定义
- 标识需要修复的循环依赖
- 建议需要添加示例的概念
- 标注所有无效的交叉引用
Step 8: Validate Output
步骤8:验证输出
Perform final validation:
- Verify alphabetical ordering (100% compliance required)
- Check all cross-references point to existing terms
- Ensure all concepts from input list are included
- Validate markdown syntax renders correctly
- Confirm no circular definitions exist
Success Criteria:
- Overall quality score > 85/100
- Zero circular definitions
- 100% alphabetical ordering
- All terms from concept list included
- Markdown renders correctly in mkdocs
执行最终验证:
- 验证字母排序(要求100%符合)
- 检查所有交叉引用都指向存在的术语
- 确保输入列表中的所有概念都已包含
- 验证Markdown语法可以正常渲染
- 确认不存在循环定义
成功标准:
- 整体质量得分>85/100
- 零循环定义
- 100%按字母排序
- 包含概念列表中的所有术语
- Markdown可以在mkdocs中正常渲染
Step 9: Update Navigation (Optional)
步骤9:更新导航(可选)
If does not already include the glossary:
mkdocs.yml- Read
mkdocs.yml - Check if "Glossary: glossary.md" exists in nav section
- If missing, add it in an appropriate location
- Preserve existing navigation structure
如果中尚未包含术语表:
mkdocs.yml- 读取
mkdocs.yml - 检查导航部分是否存在「Glossary: glossary.md」
- 如果不存在,在合适的位置添加
- 保留原有导航结构
Step 10: Generate Cross-Reference Index (Optional)
步骤10:生成交叉引用索引(可选)
Create for semantic search:
docs/learning-graph/glossary-cross-ref.jsonjson
{
"terms": [
{
"term": "Learning Graph",
"related_terms": ["Concept Dependency", "Directed Acyclic Graph"],
"contrasts_with": ["Linear Curriculum"],
"category": "Educational Technology"
}
]
}This JSON file enables future features like:
- Semantic search across glossary
- Concept relationship visualization
- Automated suggestion of related terms
创建用于语义搜索:
docs/learning-graph/glossary-cross-ref.jsonjson
{
"terms": [
{
"term": "Learning Graph",
"related_terms": ["Concept Dependency", "Directed Acyclic Graph"],
"contrasts_with": ["Linear Curriculum"],
"category": "Educational Technology"
}
]
}这个JSON文件可以支持未来的功能,比如:
- 术语表语义搜索
- 概念关系可视化
- 相关术语自动推荐
Quality Scoring Reference
质量评分参考
Use this rubric to score each definition (1-100 scale):
85-100: Excellent
- Meets all 4 ISO 11179 criteria (20+ pts each)
- Appropriate length (20-50 words)
- Includes relevant example
- Clear, unambiguous language
- No circular dependencies
70-84: Good
- Meets 3-4 ISO criteria
- Acceptable length (15-60 words)
- May lack example
- Generally clear
- No serious issues
55-69: Adequate
- Meets 2-3 ISO criteria
- Length issues (too short or too long)
- Missing example where helpful
- Some ambiguity
- Minor circular references
Below 55: Needs Revision
- Fails multiple ISO criteria
- Serious length issues
- Confusing or circular
- Missing context
- Requires complete rewrite
使用以下评分标准为每个定义打分(1-100分):
85-100:优秀
- 符合所有4项ISO 11179标准(每项得分20+)
- 长度合适(20-50个词)
- 包含相关示例
- 语言清晰、无歧义
- 无循环依赖
70-84:良好
- 符合3-4项ISO标准
- 长度可接受(15-60个词)
- 可能缺少示例
- 整体清晰
- 无严重问题
55-69:合格
- 符合2-3项ISO标准
- 存在长度问题(太短或太长)
- 缺少必要的示例
- 存在一定歧义
- 存在轻微循环引用
低于55:需要修订
- 多项ISO标准不达标
- 存在严重长度问题
- 内容混乱或存在循环定义
- 缺少上下文
- 需要完全重写
Common Pitfalls to Avoid
需要避免的常见陷阱
Circular Definitions:
- Bad: "A Learning Graph is a graph that shows learning."
- Good: "A directed graph of concepts that reflects the order concepts should be learned."
Too Vague:
- Bad: "A thing used in education."
- Good: "A directed graph of concepts that reflects prerequisite relationships."
Too Long:
- Bad: "A learning graph is a specialized type of directed acyclic graph structure commonly used in educational technology and instructional design contexts to represent the hierarchical and sequential relationships between different conceptual elements that students need to master in order to achieve specific learning outcomes."
- Good: "A directed graph of concepts that reflects the order concepts should be learned to master a new concept."
Business Rules:
- Bad: "Students must complete prerequisites before advancing to dependent concepts."
- Good: "A directed graph showing prerequisite relationships between concepts."
Undefined Terms:
- Bad: "Uses a DAG structure" (if DAG not in glossary)
- Good: "Uses a directed acyclic graph structure"
循环定义:
- 错误示例:「学习图谱是用于展示学习内容的图谱。」
- 正确示例:「反映概念学习顺序的有向概念图。」
过于模糊:
- 错误示例:「教育中使用的一种工具。」
- 正确示例:「展示概念之间前置依赖关系的有向图。」
过于冗长:
- 错误示例:「学习图谱是一种特殊的有向无环图结构,常用于教育技术和教学设计领域,用于表示学生需要掌握的不同概念元素之间的层级和顺序关系,以实现特定的学习目标。」
- 正确示例:「反映概念学习顺序的有向图,用于指导学生掌握新概念。」
包含业务规则:
- 错误示例:「学生必须完成前置内容才能学习后续依赖概念。」
- 正确示例:「展示概念之间前置依赖关系的有向图。」
使用未定义术语:
- 错误示例:「使用DAG结构」(如果DAG不在术语表中)
- 正确示例:「使用有向无环图结构」
Output Files Summary
输出文件汇总
Required:
- - Complete glossary in alphabetical order with ISO 11179-compliant definitions
docs/glossary.md
Recommended:
- - Quality assessment and recommendations
docs/learning-graph/glossary-quality-report.md
Optional:
- - JSON mapping for semantic search
docs/learning-graph/glossary-cross-ref.json - Updates to navigation if glossary link missing
mkdocs.yml
必填:
- - 按字母排序的完整术语表,包含符合ISO 11179标准的定义
docs/glossary.md
推荐:
- - 质量评估和改进建议
docs/learning-graph/glossary-quality-report.md
可选:
- - 用于语义搜索的JSON映射文件
docs/learning-graph/glossary-cross-ref.json - 如果术语表链接缺失,更新导航配置
mkdocs.yml
Example Session
示例会话
User: "Generate a glossary from my concept list"
Claude (using this skill):
- Reads concept list file and (~5K tokens)
docs/course-description.md - Validates quality (checks for duplicates, formatting) (~1K tokens)
- Launches ONE serial Task agent that writes all definitions to (~19K tokens)
/tmp/glossary-raw.md - Writes a Python assembly script to (~500 tokens)
/tmp/assemble_glossary.py - Runs the script via Bash — it parses, sorts, and writes (~200 tokens)
docs/glossary.md - Verifies term count with (~100 tokens)
grep -c "^####" docs/glossary.md - Updates navigation if needed (~500 tokens)
mkdocs.yml - Reports: "Created glossary with 350 terms. Added examples to 70% of terms."
Measured result (2026-03-14): 350 terms generated and assembled in ~31K total tokens.
At ~88 tokens/term (or ~54 tokens/term after subtracting agent overhead), this is
the most efficient approach possible.
REMEMBER: The subagent generates text (unavoidable LLM work). The assembly is
a programming task — use , not the Edit tool. NEVER use parallel agents.
sorted()用户:「根据我的概念列表生成术语表」
Claude(使用本Skill):
- 读取概念列表文件和(约5K Token)
docs/course-description.md - 验证质量(检查重复项、格式)(约1K Token)
- 启动1个串行Task Agent,将所有定义写入(约19K Token)
/tmp/glossary-raw.md - 编写Python组装脚本到(约500 Token)
/tmp/assemble_glossary.py - 通过Bash运行脚本——解析、排序并写入(约200 Token)
docs/glossary.md - 用验证术语数量(约100 Token)
grep -c "^####" docs/glossary.md - 必要时更新导航(约500 Token)
mkdocs.yml - 汇报:「已创建包含350个术语的术语表,70%的术语添加了示例。」
实测结果(2026-03-14): 生成并组装350个术语总计消耗约31K Token。
平均每个术语约88 Token(扣除Agent开销后边际成本约54 Token/术语),这是目前最高效的实现方案。
提醒: 子Agent生成文本是不可避免的LLM工作。组装是编程任务——使用,不要使用Edit工具。绝对不要使用并行Agent。
sorted()