Skip to content

Maigo Self-Check

Owner: Taki (Verifier) Consumers: /maigo:go, /maigo:quick, /maigo:team, /maigo:crystallize

觸發條件

diff 動到以下任一路徑時啟用本 skill：

  • agents/
  • commands/
  • skills/（含 SKILL.md 與 references/ 子目錄）
  • mkdocs.yml
  • docs/

純動 Python source（hooks/、scripts/、tests/）→ 只跑 pytest，不觸發本 skill。 兩者都動（如同時改 scripts/ 與 docs/）→ pytest + 本 skill 兩條都跑。

驗證指令

uv run python scripts/validate_plugin.py
uv run mkdocs build --strict

為什麼都用專案環境：

  • uv run python scripts/validate_plugin.py — validator 使用專案宣告的 Python 版本；不受 host 上較舊的系統 python3 影響。
  • uv run mkdocs build --strict — mkdocs 是 venv 工具（在 pyproject.toml 的 docs dependency 裡）。

這兩條抓的是 pytest 抓不到的東西

問題類型 被哪條抓到
include shim 缺失（docs/skills/<name>.md 沒建） validate_plugin.py
frontmatter name 對不上目錄名 validate_plugin.py
skill catalog（docs/reference/skills.md）漏列 validate_plugin.py
mermaid 相依圖缺 skill 節點 validate_plugin.py
相對 link 在 include-markdown rewrite 後炸 strict-mode mkdocs build --strict
docs nav 指到不存在的 page mkdocs build --strict
command 檔缺「掛名」角色台詞（引號旁邊沒有角色 emoji / 名字） validate_plugin.py
CLAUDE.md / AGENTS.md 的共同驗證慣例漂移 validate_plugin.py

pytest 測的是 Python 行為；上述問題都在 plugin 結構層——pytest 對它們是盲的。

新增 / 改 commands/*.md 時，至少保留一段掛名角色台詞（MyGO!!!!! 濃度慣例）——單純 「有「」引號」不算數，旁邊要看得到角色 emoji / 名字（或是 > 「...」 blockquote 標題引言）， 不能只是 UI/error 訊息引號。機器兜底由 validate_plugin.py 的 check_command_persona_quotes 檢查，不必自己記著掃。

改 references/*.md 時：跟 SKILL.md 摘要同步

幫某個 skill 的 references/*.md 加新內容時，兩件事一起做，缺一都算沒改完：

  1. 改之前先看該 reference 檔開頭宣告的範圍（例如「Read this file when ...」）是否覆蓋新主題。 題材對不上就不要硬塞——擴大宣告範圍，或改放進更貼切的位置（往往是 SKILL.md 本體裡已經在談同主題的段落）。
  2. 改之後同步 SKILL.md 本體對這份 reference 檔案的摘要（列出的條數、bullet 清單）——SKILL.md 是永遠會被載入的主體，reference 檔是 on-demand；摘要沒同步，新內容等於沒人看得到。

為什麼：/maigo:crystallize 一次批次畢業多筆記憶時踩過兩次——references/*.md 加了新內容， 但 SKILL.md 本體的條數摘要（如「Three cross-cutting patterns」）沒跟著改成新的數字。這條檢查 不限 crystallize；/maigo:quick、/maigo:go 只要動到 skills/ 都算。

兩條都必須綠才算完成

任何一條紅 → 驗證未通過，不算 Taki PASS。回報實際錯誤，不跳過、不假裝綠。