原因其实很现实：不是因为 Markdown 高级，而是因为 LLM 对 Markdown 的解析最稳定、最廉价。
OpenClaw 把 skill 写成 .md，本质是工程取舍，不是技术限制。

下面把底层逻辑拆开说。

---

1 本质：Skill 其实是 Prompt + 规则

在 OpenClaw 里，一个 Skill 典型结构其实是：

skill
 ├─ description
 ├─ instructions
 ├─ examples
 └─ tools

而这些内容 99% 是自然语言。

如果用 JSON 写：

{
  "name": "sql_query",
  "description": "...",
  "instructions": "...",
  "examples": [...]
}

问题是：

• 可读性差
• prompt 写起来痛苦
• 改动困难

所以很多框架直接用 Markdown。

---

2 Markdown 对 LLM 极其友好

大模型在训练时大量见过 Markdown，例如：

• GitHub
• 技术文档
• StackOverflow

所以结构：

# Skill: SQL Query

## Description

查询数据库信息

## When to use

用户需要数据库查询

## Steps

1. 生成SQL
2. 调用sql_tool
3. 返回结果

LLM 理解准确率比 JSON 高。

原因：

Markdown ≈ 自然语言 + 结构

而不是：

JSON = 纯结构

---

3 Prompt + 文档可以合并

如果 Skill 是 Markdown：

系统可以直接拼接到 Prompt：

System Prompt

<global instructions>

# Skill: SQL Query
...

不需要再做结构解析。

这减少一层：

parse → serialize

延迟更低。

---

4 Git 友好

如果 Skill 是 .md：

开发体验会好很多：

skills/
   sql_query.md
   web_search.md
   financial_analysis.md

优点：

• diff 清晰
• PR review 简单
• 非工程人员也能改

产品经理甚至能直接改 skill。

---

5 Markdown 可以嵌入结构

Markdown 也能写结构：

## Tools

- sql_query
- db_schema

或者：

```tool
sql_query

解析也简单。

---

## 6 真正原因：Prompt Engineering

Skill 文件本质是：

long prompt template

而 Prompt 最好的格式其实就是：

Markdown

因为：

- 层级清晰
- 可读
- 训练数据多

很多系统（包括内部系统）都这么做。

---

## 7 但这其实有一个隐藏问题

Markdown skill **规模一大就会崩**。

比如：

100 skills
每个 1500 token

Agent prompt：

150000 tokens

直接爆 context。

所以成熟系统会变成：

skill metadata (JSON)
skill prompt (MD)
skill routing (embedding)

也就是：

Router
↓
select skill
↓
load markdown

而不是一次加载全部。

---

## 8 更高级系统甚至不用 Markdown

很多大厂现在用的是：

Skill Graph

结构类似：

skill
├─ capability vector
├─ tool set
├─ workflow
└─ prompt template

Markdown只负责：

instruction

---

## 结论

OpenClaw 用 Markdown 主要是四个原因：

1 可读性好
2 LLM理解稳定
3 Prompt直接拼接
4 Git协作友好

但它本质上只是：

prompt container

不是技术必须。

---

如果你真的在深入研究 OpenClaw，我可以继续讲一个很多人没意识到的问题：

**为什么 Skill 数量一旦超过 30，Agent 几乎一定会开始乱选工具。**

这背后其实是 **LLM 决策复杂度的问题**。