## 仓库性质

这是一个 **Claude Code / Agent Skill 仓库**，不是可执行的软件项目。这里没有源代码、构建脚本、测试或依赖——核心产物是供 AI 阅读并据此工作的 **Markdown 指令文档**。因此不存在「如何 build / lint / run tests」这类命令；对本仓库的修改就是编辑文档本身。

技能本身（`markji-cards`）的作用：说明「墨墨记忆卡」（Markji）卡片的**纯文本标记语法与排版样式**，并含制卡质量原则。它只提供文本语法依据；素材上传、建卡、导入等实际操作需搭配墨墨 API、浏览器或其他技能完成。

## 文件结构与各自职责

- `SKILL.md` —— 技能主文件。开头的 YAML frontmatter（`name` / `description` / `metadata`）决定该技能何时被触发，`description` 写得越准，触发越精确。正文是墨墨卡片文本的**完整语法/样式规范 + 自检清单**，是改动时的事实来源。
- `references/制卡20条原则.md` —— 制卡**质量原则**（Woźniak「知识表述 20 条原则」的中文高考改写版）。`SKILL.md` 在「制卡质量原则」一节引用它；首次制卡或材料复杂时应通读。

`SKILL.md` 与参考文档强耦合：`SKILL.md` 讲**语法**（怎么写墨墨能识别的标记），`制卡20条原则.md` 讲**原则**（怎么把材料切成好记的卡）。`SKILL.md` 里有一张「参考文档写法 → 墨墨语法」的映射表把语法与原则衔接起来。

## 编辑时必须维护的一致性

修改语法或规则时，下面这些地方往往要**同步更新**，否则文档会自相矛盾：

1. **语法说明（第二节「元素语法速查」）↔ 自检清单（第五节）** —— 自检清单逐条对应语法规则。改了某条语法限制，对应的自检项也要改。
2. **`SKILL.md` 的语法 ↔ `references/制卡20条原则.md` 的举例映射** —— 参考文档用「问/答」和省略号占位的通用写法，靠 `SKILL.md` 的映射表转成墨墨语法（如 `[F##文字]`、`---` 答案线）。

## 墨墨语法中容易写错、需特别小心的硬约束

这些是 `SKILL.md` 反复强调、最易出错的点，编辑示例或新增规则时务必遵守：

- **挖空 `[F#分组#文字]` 只支持纯文本**：内部不能嵌 `[T#…]` 行内样式或 `[E##…]` 公式。
- **行内样式 `[T#…]` 不能自嵌套，也不能包住挖空**：需要叠加样式或在样式中挖空时，拆成「前段 T ＋ 中段 ＋ 后段 T」三段，中段把样式一次写全。
- **段落 `[P#…]` 必须独占整行**；只有 `[P#…]` 能包住 `[T#…]` 或 `[F#…]`。
- **挖空分组数字 ≠ 揭示顺序**：揭示永远按文本从上到下的位置；分组只决定「哪些空一起亮」。
- **公式用 KaTeX（非完整 LaTeX）**；行内公式可直接写在句子中间，块级公式才必须顶格独占一行；占用空间大的公式（分段函数、矩阵等）建议用块级，便于手机阅读。
- **单 `!` 是字体色、双 `!!` 是高亮色**，别混淆；优先用 7 种内置色；避免对普通文字用「绿字＋下划线」——挖空未揭示时正是绿色下划线外观，容易混淆。
- **图片只能用 `[Pic#ID/…#]` 引用已经 API 上传的图片**（不能直接塞图片文件）；带遮罩 `MID/` 的图片在揭示机制里算一个可交互元素。
- **发音 `[Audio#…]`、引用 `[Card#…]` 的显示文本内外都不能嵌套行内样式 / 挖空 / 公式**。

## 语言

仓库面向中文（高考）场景，所有文档用简体中文。新增内容沿用现有文档的术语和体例（代码标记、表格、`>` 引用块、示例代码块）。