writing-notes

name	writing-notes
description	撰写技术笔记/文档时的结构化纲领。当做学习记录、整理技术文档、记录知识时使用此技能。

writing-notes

本技能提供一套写作纲领，确保每篇笔记结构一致、渲染可靠、知识可追溯。

一、YAML Frontmatter 规范

这是 VitePress / Obsidian / 多数 md 渲染器正确解析元数据的基础。写错一条就会导致整个 frontmatter 被当作普通段落原样输出。

硬性规则

为了对齐渲染器的渲染行为边界,约定Frontmatter 规范:

1. 文件第一行必须是 ---。前导空行会让大多数渲染器识别不到 frontmatter.
2. YAML 闭合 --- 前留 1 个空行，将元数据字段与闭合符在视觉上隔开。
3. YAML 块结束后留 2 个空行，再开始正文。

模板

---
title: <name>
tags: [tag1, tag2]
note_types : < document | cognitive-note , | Essay>
created: yyyy-mm-dd
updated: yyyy-mm-dd
---

# H1 Title

> [!note]
> **Ref:** [web source](url) | [local source]($cwd/path)

正文...

二、Top Level Insight

2.1 Abstract

领衔全文，以行业专家的深刻洞察，用一段话阐述问题背景、中心话题。

三、行文纪律

写作前先想清楚这篇笔记是给谁看、什么时候看的。

维度	document	cognitive-note	Essay
目的导向	呈现、对齐、交付：让用户快速获得共识性全貌	思考、内化、涌现：促进深度理解。	随手简记
读者画像	读者已对该技术栈有了较好的认知，需要归档技术文档。	读者刚在AI的指导下接触这个领域，需要AI导学细化，需要沉淀学习路径。	读者能够轻松上手这份简单知识，需要归档以速查备忘。
章节结构	强结构化	调概念间的自然递进	聚焦于How
内容性	对已知结论的结构化整理。	对既定话题的导入，深化	简明扼要，只讲核心机制

• 行文务实，避免口语化表达，也避免长篇幅累赘阐述。
• 叙事具备逻辑，文章结构合理，内容详实，What , Why , How 系统化分析思考。

1. Anti AI slop：
   • “不是……而是……”
   • 一切无意义辞藻。
2. 如果一句话能说清，就只写一句。不要凑长度。

四、图例演示

面对复杂问题时，积极使用图例来演示。发掘，联动Agent Harness 的生图能力。

• 产物要求 : 结构紧凑，内容详实，视觉效果好。积极考虑读者在Site / Typora 的视觉体验，渲染器通常只有半屏宽度供md正文展示，警惕 too large image.
• 编排流程 : 后台执行，不要阻塞主线笔记攥写；珍惜上下文窗口，调用外部工具生成，委托子代理打磨审阅。
• Fallback : Harness Image能力不足时，向用户如实反馈，给出text flow,mermaid 等兜底链路。