CLI开发工具AI Agent人工智能包管理器【免费下载链接】x-cmdPosix Shell 工具库项目地址https://gitcode.com/x-cmd/x-cmd点击查看免费下载导读本文围绕 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 MatterYFM是 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 fieldsGitHub issue bodyGitHub Issue PR bodies同左tags、description、repo、numberGitHub PR bodyGitHub Issue PR bodies同左与 issue 相同GitHub wiki 页面x-cmd 默认三字段x-cmd 默认三字段tags、description、memoGitHubREADME.mdx-cmd 默认三字段x-cmd 默认三字段tags、description、memoproject/.x-cmd/story/*.mdstorystorytags、description、memo、issueskill/SKILL.mdx-cmd 默认三字段 skill0-writerx-cmd 默认三字段tags、description、memo另加metadata.related按 skill0-writer本地 Markdown 笔记x-cmd 默认三字段 或不写 YFMx-cmd 默认三字段tags、description、memoObsidian 库文件Obsidian 原生obsidiantags、aliases、cssclassesJekyll 站点文件Jekyll 原生jekylltitle、date、tags、categoriesHugo 站点文件Hugo 原生hugotitle、date、tags、keywords、站点分类法Agent Skill 文件agentskillsagentskillsname、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:0008: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:0008:00: Tightened field list; cut aliases, added memo. 2026-07-31T10:00:0008:00: Initial draft. ---适用边界来自 yfm/SKILL.mdproject/.x-cmd/story/在三字段基础上扩展issue:见 story usecaseGitHub issue / PR body在三字段基础上扩展repo:、number:即本文主角GitHubREADME.md仅用默认三字段不扩展。配套命令行x yfmyfm 模块在 x-cmd 中以 helper 形式提供共三个命令yfm/SKILL.mdx 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:0008: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的状态字段关联文档特别强调stateopen / 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 正文时。而对于你无法控制的 IssueGitHub 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.relatedSKILL.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 分派解析。Obsidiantags、aliases、cssclasses三个保留属性tags必须是列表正文中的#inline-tag也算标签/表示层级关系如inbox/to-readcollector 应展开为层级边而非拍平字符串。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-cmdPosix Shell 工具库项目地址https://gitcode.com/x-cmd/x-cmd点击查看免费下载相关推荐x-cmd yfm为 Agent、索引与本体管线统一 Markdown 的 YAML Front Matter 规范x cmd yfm为 Agent、索引与本体管线统一 Markdown 的 YAML Front Matter 规范 YAML Front MatterYFCLI开发工具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上一篇如何用Outlook CalDav Synchronizer免费实现跨平台日历联系人同步终极完整指南下一篇国家中小学智慧教育平台电子教材下载终极指南一键获取完整教学资源创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考