- CLI
- 开发工具
- AI Agent
- 人工智能
- 包管理器
【免费下载链接】x-cmd
Posix Shell 工具库
导读
本文围绕 x-cmd 仓库中 yfm skill 的实战指南展开，核心讲解"在哪种 Markdown 场景下写哪些 YFM 字段"这一张面向 agent、索引器与本体（ontology）管线的映射表。你将掌握 x-cmd 默认三字段（tags/description/memo）的规范、GitHub Issue 与 PR body 的特殊扩展字段（repo/number），以及 Obsidian、Jekyll、Hugo、Agent Skills 等外部方言的读写规则，并学会用x yfm ls / init / lint命令落地这套约定。
什么是 YFM，为什么需要一张"场景映射表"
YAML Front Matter（YFM）是 Markdown 文件开头的 YAML 元数据块，用于描述这篇文档的标签、摘要、修订记录等结构化信息。在 x-cmd 的 skill0 体系中，凡是可能被agent、索引器或本体（ontology）管线扫描的 Markdown，都应当使用 YFM 来承载可被机器读取的元数据（见 yfm/SKILL.md）。
问题的关键在于：Markdown 的宿主场景千差万别——GitHub Issue、GitHub Wiki、本地笔记、Obsidian 库、Jekyll/Hugo 站点、Agent Skills 目录——每种场景都有自己既有的 YFM 方言。x-cmd 的约定是：
若某种方言已经在该场景生效（Agent Skills、Obsidian、Jekyll、Hugo 等），沿用既有方言；x-cmd 默认三字段只在没有任何其他方言管辖时才适用。
本文所基于的 git-issue-pr-wiki-markdown-etc.md 正是这张逐场景（surface-by-surface）映射表，回答了三个问题：写什么字段（Writing）、读什么字段（Reading）、哪些字段有用（Useful fields）。
快速映射表：一图看懂"哪个场景用哪些字段"
原文档给出了下面这张核心速查表，它决定了 YFM 在 x-cmd 生态中的一切落点：
| 场景（Surface） | 写作规范（Writing） | 读取规范（Reading） | 常用字段（Useful fields） |
|---|---|---|---|
| GitHub issue body | GitHub Issue & PR bodies | 同左 | tags、description、repo、number |
| GitHub PR body | GitHub Issue & PR bodies | 同左 | 与 issue 相同 |
| GitHub wiki 页面 | x-cmd 默认三字段 | x-cmd 默认三字段 | tags、description、memo |
GitHubREADME.md | x-cmd 默认三字段 | x-cmd 默认三字段 | tags、description、memo |
<project>/.x-cmd/story/*.md | story | story | tags、description、memo、issue |
<skill>/SKILL.md | x-cmd 默认三字段 + skill0-writer | x-cmd 默认三字段 | tags、description、memo；另加metadata.related（按 skill0-writer） |
| 本地 Markdown 笔记 | x-cmd 默认三字段 或不写 YFM | x-cmd 默认三字段 | tags、description、memo |
| Obsidian 库文件 | （Obsidian 原生） | obsidian | tags、aliases、cssclasses |
| Jekyll 站点文件 | （Jekyll 原生） | jekyll | title、date、tags、categories |
| Hugo 站点文件 | （Hugo 原生） | hugo | title、date、tags、keywords、站点分类法 |
| Agent Skill 文件 | agentskills | agentskills | name、description、metadata.* |
表中有两条全局原则值得强调：
- 兜底规则：未列入上表的任何 Markdown，一律回退到 x-cmd 默认三字段。
- "地板"而非"天花板"：三个默认字段是底线，不是上限——但想增加任何字段，都必须通过新增一个 usecase 文档来定义，绝不允许在某个文件里私自发明字段。这保证了整个 skill0 生态的 YFM 方言可枚举、可校验、可被本体管线稳定消化。
x-cmd 默认三字段：tags、description、memo
这是整张映射表的基石。GitHub wiki、README、本地笔记、story、SKILL.md 等绝大多数 x-cmd 自有场景都直接继承它。规范定义在 yfm/SKILL.md，其形态借用了 Agent Skills 的 frontmatter 规范（agentskills.io 规范）。
--- tags: [design, front-matter] description: One-sentence summary a reader uses to decide whether to open this file. memo: 2026-07-31T14:30:00+08:00: Cut aliases; renamed third field to memo. --- # Title Body...三个字段的语义与消费方：
tags— 顶层列表，取值必须是 slug（[a-z0-9-]）。消费方是用于本体索引的 collector（收集器）。注意 slug 字符集不含逗号，这为后续"逗号连接"类的方言解析提供了安全前提（见下文 Jekyll 一节）。description— 顶层字符串，一句话。作用是为读者提供"是否值得打开此文件"的决策摘要。它不是Agent Skills 里的description:——那是 SKILL.md 专属要求，由 skill0-writer 管辖。两个 description 的用途与载体完全不同。memo:— 顶层映射，即该文件的修订日志。键是 ISO 8601 时间戳（YYYY-MM-DDTHH:mm:ss±HH:mm，采用作者本地时区偏移），值是简短的变更描述，新的在前。若没有值得记录的历史，可以省略整个字段。
从 story.md 可以看到memo:的典型多条目形态：
--- tags: [yfm, design] description: How the yfm skill settled on three fields, in chronological order. issue: 142 memo: 2026-07-31T14:30:00+08:00: Tightened field list; cut aliases, added memo. 2026-07-31T10:00:00+08:00: Initial draft. ---适用边界（来自 yfm/SKILL.md）：
<project>/.x-cmd/story/：在三字段基础上扩展issue:，见 story usecase；- GitHub issue / PR body：在三字段基础上扩展
repo:、number:，即本文主角； - GitHub
README.md：仅用默认三字段，不扩展。
配套命令行：x yfm
yfm 模块在 x-cmd 中以 helper 形式提供，共三个命令（yfm/SKILL.md）：
x yfm ls [path]— 列出指定路径下的 YFM 块，默认当前目录；x yfm init [path]— 为路径下每个 Markdown 文件写入一个 x-cmd 默认三字段块；x yfm lint [path]— 校验每个 YFM 块是否为合法 YAML，并检查是否符合其所声明的方言。
其中lint尤为关键：它把"方言正确性"从口头约定变成了可机器执行的门禁，与 skill0 体系"用规则而非文档强制约定"的理念一致（参见 skill0/SKILL.md 中的 OKR 工作流与x rule check/audit）。
GitHub Issue 与 PR body：在默认三字段上扩展repo与number
这是关联文档着墨最多的场景，也是 x-cmd 工具链实际写 GitHub Issue/PR 时遵循的规范。
继承关系与完整示例
GitHub Issue / PR body 继承 x-cmd 默认三字段，并额外增加两个用于"问题识别（issue-identification）"的扩展字段。原文档给出的完整示例：
--- tags: [yfm, design] description: Should the yfm skill include metadata.related? repo: x-bash/skill0 number: 142 memo: 2026-07-31T14:30:00+08:00: Initial draft. --- # Should yfm include metadata.related? ...两个扩展字段的可选性规则
repo:— 取值形如owner/name（例如x-bash/skill0）。必填当且仅当该文档是一份"独立成文的 issue 摘要"（free-standing issue summary，即这份 Markdown 本身不在 GitHub 上）；若文档就是issue 正文本身，则可选——因为 GitHub 平台本身已经记录了仓库归属，重复书写只会引入漂移。number:— 整型 issue 编号。可选性规则与repo:完全一致。同一对字段对 PR body 同样适用。
明确"不该写进 YFM"的状态字段
关联文档特别强调：state（open / closed / merged）不属于该场景的 YFM 字段。理由是 GitHub API 才是状态的事实来源（system of record），在 YFM 中重复陈述 open/closed/merged 会导致状态漂移（drift）——文档里的旧状态会与平台上的真值脱节。同理，labels:、assignees:、created_at:、updated_at:也不应写入 YFM。
这条规则体现的设计哲学是：YFM 只记录"GitHub 不知道或不便表达"的信息（tags、description、memo），凡是平台自身已有权威记录的内容，一律不重复。对读者而言，判断标准很简单：写这个字段，是为了让 agent/索引器在不调用 API 的情况下就能理解这篇 Issue 的语境，而不是为了复述 GitHub 已有的状态。
何时使用本节规范
以下两种情况应当按本节书写 YFM 块：
- 书写一个描述某 Issue 或 PR 的 YFM 块（例如把 Issue 摘要归档到本地 Markdown 时）；
- 由 x-cmd 工具生成GitHub Issue/PR 正文时。
而"对于你无法控制的 Issue，GitHub API 是唯一的事实来源"——这句话是收尾的边界提醒：不要试图用本地 YFM 去覆盖平台状态。
关联场景纵深：story、SKILL.md 与本体管线如何消费 YFM
映射表里几个 x-cmd 自有的落点，与 Issue/PR 场景共享同一套继承体系，值得展开：
<project>/.x-cmd/story/*.md：加一个issue:关联字段
story.md 定义了设计故事（design story）的 YFM 约定：继承默认三字段，扩展issue:。issue:引用相关联的 Issue，支持单个编号或列表：
issue: 142 issue: [142, 158]collector 会把它映射为一条本体关系，将 story 实体链接到 issue 实体。若没有关联的 Issue，直接省略该字段——不要写issue: null或issue: 0。这与 Issue body 场景的number:形成呼应：编号类字段只记录真实存在的引用。
<skill>/SKILL.md：默认三字段 + skill0-writer 的metadata.related
SKILL.md 的 YFM 由 yfm 与 skill0-writer 双重管辖：顶层保留name与description（这是加载器用于匹配的关键载荷），其余扩展字段一律嵌套进metadata:块。本文所读的各个 SKILL.md 本身就是范例，例如 yfm 自己的 frontmatter：
--- name: yfm description: | YAML front matter (YFM) for any markdown article. ... metadata: related: "skill0-writer,ontology-database" ---这套设计最终服务于本体管线：在 ontology-database/SKILL.md 中明确指出"yfm 的metadata:是推荐的本体摄取面（ingest surface）"——YFM 字段被 collector 解析后，直接成为 TSV 追加式本体日志中的实体属性（key→val），供x ondb查询与推理。这也解释了为什么默认三字段要严格约束tags为 slug：保证跨方言解析时值域可预期。
外部方言速览：Obsidian、Jekyll、Hugo、Agent Skills
映射表显示，外部平台场景"写"时遵循各平台原生规范，"读"时由 collector 按方言处理。四个 usecase 文档的关键差异点如下（详见各链接）：
- Agent Skills：顶层是封闭集合，仅
name、description、license、compatibility、metadata、allowed-tools六个键；扩展字段必须放metadata:内，且metadata必须是 string→string 映射（标签用逗号分隔，而allowed-tools用空格分隔——分隔符不统一，须按 key 分派解析）。 - Obsidian：
tags、aliases、cssclasses三个保留属性；tags必须是列表，正文中的#inline-tag也算标签；/表示层级关系（如inbox/to-read），collector 应展开为层级边而非拍平字符串。 - Jekyll：字符串形态的标签用空格分隔而非逗号；
categories参与 URL 路径生成而tags不参与，二者须保持为独立集合。 - Hugo：定界符是
+++且内容是TOML 而非 YAML；标签键名不固定（取决于站点[taxonomies]配置），collector 只能做"已知键 + 读取站点配置补充"。
掌握这些差异的实际价值在于：当 x-cmd 工具需要读取（Reading 列）某个外部方言文件时，必须按正确规则抽取标签，例如把 Jekyll 的categories: jekyll update按空格拆成两个标签，而不是按逗号拆成一个"jekyll update"——后者会因含空格而被 Obsidian 规则直接判为非法。
小结：判断"该写什么 YFM"的四步决策法
综合整张映射表与关联文档，可以提炼出 x-cmd 场景下的实用决策流程：
- 确认场景：文档属于上表哪一行（GitHub Issue/PR、wiki、README、story、SKILL.md、本地笔记、Obsidian/Jekyll/Hugo 站点、Agent Skills）？
- 确定方言：该场景是否有原生方言在生效？有则沿用；无则套用 x-cmd 默认三字段。
- 查扩展字段：GitHub Issue/PR 场景加
repo:/number:（注意可选性规则）；story 场景加issue:；SKILL.md 场景按 skill0-writer 将扩展项放入metadata:。 - 遵守"地板"原则：三字段是底线；新增字段必须走 usecase 文档流程，不私自发明；平台已有权威记录的状态类信息（如 Issue 的 open/closed）不写进 YFM。
这套约定让 Markdown 元数据在 agent、索引器与本体管线之间保持可预测、可校验、可追踪，也正是 yfm skill 目录 下每个 usecase 文档存在的意义。
- CLI
- 开发工具
- AI Agent
- 人工智能
- 包管理器
【免费下载链接】x-cmd
Posix Shell 工具库
相关推荐
x-cmd yfm：为 Agent、索引与本体管线统一 Markdown 的 YAML Front Matter 规范
x cmd yfm：为 Agent、索引与本体管线统一 Markdown 的 YAML Front Matter 规范 YAML Front Matter（YF
CLI开发工具AI Agent人工智能包管理器Biome 的 useTopLevelHeading 规则实战：YAML Front Matter 场景下 Markdown 一级标题校验
Biome 的 useTopLevelHeading 规则实战：YAML Front Matter 场景下 Markdown 一级标题校验 导读 本文围绕 Bi
开发工具Lint格式化静态分析代码质量前端使用 Gulp 结合 Swig 与 YAML front-matter 实现 HTML 模板渲染
使用 Gulp 结合 Swig 与 YAML front matter 实现 HTML 模板渲染 本指南基于 gulp 官方 Recipe「Templating
构建工具CLI
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
