這個 skill 是什麼

markdown-plus-author 是一個 Claude Skill, 讓 Claude(Claude Code、Claude Desktop、API)在寫或改寫 dev note / decision record / status report / runbook 這類 AI-readable 結構化文件時,直接產出合法的 Markdown+。

Source 內已涵蓋:

• 受控字彙表(type:、status:、visibility: 等 closed list)
• 強制保留 code fence / ASCII art / 對齊表格 1:1 的 hard rule
• ```svg / ```mermaid fence 的允許範圍與大小閾值
• keywords: 何時手寫、何時讓 viewer 自動抽取(配合本 repo 的 viewer)
• HTML → Markdown+ 改寫 playbook(剝 <script> / 移除 base64 / 拆 chart spec / 對齊巢狀)
• Functional + abuse + multilingual eval 集合

下載 .skill

最新版的 skill bundle(zip 格式,內含 SKILL.md + references + assets):

↓ 下載 markdown-plus-author.skill 約 46 KB · zipped · 含 SKILL.md + 7 個 references + 2 個 eval JSON

Canonical source 在 skills/markdown-plus-author/; .skill 檔是從 source 用 zipfile.ZipFile(..., ZIP_DEFLATED) 重新打包。

安裝到 Claude Code(或其他宿主)

Claude Code(CLI / 桌面)

1. 下載 markdown-plus-author.skill
2. 解壓到 ~/.claude/skills/ 底下,得到 ~/.claude/skills/markdown-plus-author/SKILL.md
3. 重啟 Claude Code,新對話時若使用者敘述命中 description 條件,skill 就會被觸發

# macOS / Linux
unzip -o ~/Downloads/markdown-plus-author.skill -d ~/.claude/skills/

# Windows PowerShell
Expand-Archive -Force "$env:USERPROFILE\Downloads\markdown-plus-author.skill" "$env:USERPROFILE\.claude\skills\"

Claude Desktop

Settings → Skills → Install from file,選下載的 .skill。 Desktop 會自動解開並驗證 frontmatter。

Claude API / Agent SDK

把 SKILL.md 的 frontmatter description 與正文一起放進 system prompt; references 視需要載入(metadata 規則建議常駐,其他可隨情境拉)。

Skill 結構

解開 .skill 後的目錄:

markdown-plus-author/
├── SKILL.md                              # 唯一進入點;frontmatter 控觸發
├── references/                           # on-demand 載入的細節
│   ├── what-is-markdown-plus.md          # 概念、實證數據
│   ├── syntax-reference.md               # 完整語法 + ```svg/```mermaid + auto keywords
│   ├── metadata-vocabulary.md            # closed vocab + `keywords:` 規則
│   ├── rewriting-playbook.md             # md → mdp,html → mdp 改寫程序
│   ├── code-fence-preservation.md        # 保留 ASCII tree / DSL fence 的 hard rule
│   ├── worked-examples.md                # 前後對照(good / bad)
│   └── quality_checklist.md              # 出貨前最後一關
└── assets/
    └── evals/
        ├── evals.json                    # trigger + functional + abuse + multilingual
        └── regression_gates.json         # 釋出前須過的 must-pass + 時/token 上限

SKILL.md 的角色

SKILL.md 是 Claude 看到的唯一入口。Frontmatter 的 description 欄位決定整個 skill 是否在對話中被啟用—— 所以它精確列出觸發場景(dev note / decision record / 改寫 HTML…) 與排除場景(投影片 / 短信件 / 一次性短回覆)。

正文以結構化 XML-like tag 分區: <role> / <decision_boundary> / <spirit> / <workflow> / <output_contract> / <default_follow_through_policy> / <viewer_features> / <references>。 Claude 不會把整份 references 載入記憶體,而是在 workflow Step 標明 Load on demand 時才讀對應檔案。

references/ — 七個檔各管什麼

assets/evals/ — 觸發測試與回歸閘門

如果你要二次開發或基於本 skill 改造,assets/evals/ 提供現成的測試集:

• evals.json — 三類測試:
  • trigger — should / shouldnot / near-miss:確認哪些敘述會喚起、哪些不會
  • functional — Given/When/Then:固定輸入是否產生符合 output contract 的輸出
  • edge & abuse — 含 prompt injection、secret leak、多語言混雜
• regression_gates.json — 釋出版本的最低標準:必過 case、 時間 / token 上限、pass rate 不可比上一版降超過多少。

搭配 skill-creator-advanced 的 run_eval.py 與 check_regression_gates.py 就能跑完整 audit。

從 source 重新打包

改完 skills/markdown-plus-author/ 內任何檔後,從 repo root 跑:

cd skills && python -c "
import zipfile, os
src = 'markdown-plus-author'
out = '../public/markdown-plus-author.skill'
with zipfile.ZipFile(out, 'w', zipfile.ZIP_DEFLATED) as zf:
    for root, _, files in os.walk(src):
        for f in files:
            zf.write(os.path.join(root, f),
                     os.path.join(root, f).replace(os.sep, '/'))
"

產出的 public/markdown-plus-author.skill 就是這頁下載連結指向的檔案。Round-trip 驗證:

mkdir /tmp/check && cd /tmp/check
python -c "import zipfile; zipfile.ZipFile('public/markdown-plus-author.skill').extractall('.')"
diff -r skills/markdown-plus-author /tmp/check/markdown-plus-author   # 應該 CLEAN