diff --git a/.agents/skills/tttk-authoring/reference.md b/.agents/skills/tttk-authoring/reference.md
index 1a7a70c..db2946f 100644
--- a/.agents/skills/tttk-authoring/reference.md
+++ b/.agents/skills/tttk-authoring/reference.md
@@ -297,13 +297,19 @@ d6,结果
 
 Reactive variable / tag-modifier definitions.
 
-Columns (any order): `tag`, `threshold`, `key`, `expr`. A row with an empty `tag` declares a variable; a row with a `#tag` applies a modifier when that tag is active.
+YAML with two optional maps. `vars:` maps a `$name` to its expression. `tags:` maps a tag name to a map of thresholds to `$target` modifiers: at that tag count the target gains the value, so sibling thresholds stack. Tag names may be written with or without the leading `#`. YAML resolves bare numbers to numbers and everything else to strings; both become expression text.
 
 ````markdown
-```csv role=declare
-tag,threshold,key,expr
-,,$hp,$con*5+$mod_hp
-#warrior,2,$mod_hp,20
+```yaml role=declare
+vars:
+  $hp: $con*5 + $mod_hp
+  $ac: 10 + $dex
+tags:
+  warrior:
+    1:
+      $mod_hp: 20
+    2:
+      $mod_str: 1
 ```
 ````
 
diff --git a/docs/reference.md b/docs/reference.md
index 1a7a70c..db2946f 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -297,13 +297,19 @@ d6,结果
 
 Reactive variable / tag-modifier definitions.
 
-Columns (any order): `tag`, `threshold`, `key`, `expr`. A row with an empty `tag` declares a variable; a row with a `#tag` applies a modifier when that tag is active.
+YAML with two optional maps. `vars:` maps a `$name` to its expression. `tags:` maps a tag name to a map of thresholds to `$target` modifiers: at that tag count the target gains the value, so sibling thresholds stack. Tag names may be written with or without the leading `#`. YAML resolves bare numbers to numbers and everything else to strings; both become expression text.
 
 ````markdown
-```csv role=declare
-tag,threshold,key,expr
-,,$hp,$con*5+$mod_hp
-#warrior,2,$mod_hp,20
+```yaml role=declare
+vars:
+  $hp: $con*5 + $mod_hp
+  $ac: 10 + $dex
+tags:
+  warrior:
+    1:
+      $mod_hp: 20
+    2:
+      $mod_str: 1
 ```
 ````