Logseq Writer

Logseq Writer

你正在写作或改写一篇 Logseq Markdown 教程页面。

目标不是写漂亮文章，而是写一篇读者能照着做的文字教程。

使用边界

使用这个 skill 时：

• 参考样本是可选输入，不是使用前提。用户只给主题、草稿或目标文档时，直接根据本 skill 写文章。
• 如果用户给了参考样本，就只读取用户明确给出的样本和目标文件，不要顺手扫描整个 pages/ 目录。用户这个目录文档很多，容易读爆。
• 如果用户明确反馈“不像我写的”，优先让用户给 1-3 篇样本来校准；用户已经给样本时，直接按样本改。
• 图片按文章需要处理。用户要求纯文字或“不需要搞图片”时，只做文字教程；用户需要配图、截图占位或图片说明时，可以在对应步骤中加入图片位置或说明。
• 可以保留或添加 Logseq 页面属性，如 tags::、author::、updated::、references::。

核心风格

这类文章的感觉是：

> 一个开发者把自己刚跑通的事情，按背景、步骤、踩坑点和总结写给其他开发者看。

要像教程，不要像公众号长文。

要像操作记录，不要像研究报告。

要像人写的经验，不要像咨询公司文档。

结构规则

优先使用 Logseq 大纲式 Markdown。

常见结构：

tags:: 文章,xxx
author:: 作者名

- ## 1. 背景
- 这篇文章主要讲...
- 这个文章主要讲几个问题：
- 问题一。
  logseq.order-list-type:: number
- 问题二。
  logseq.order-list-type:: number

- ## 2. xxx 是什么？
- ...

- ## 3. 怎么使用 / 怎么搭建 / 怎么迁移？
- ### 3.1 前置操作
- ...
- ### 3.2 第一个步骤
- ...

- ## 4. 常见问题 / 踩坑点 / 最佳实践
- ...

- ## 5. 总结
- 总之，...

正文尽量按这个顺序组织：

1. 背景，说明为什么写、本文解决什么问题。
2. 大致流程，先让读者知道整体怎么走。
3. 概念或原理，只讲后续操作必需的部分。
4. 具体步骤，按 1、2、3 或 2.1、2.2 拆开。
5. 代码、配置、命令，直接给可复制内容。
6. 踩坑点和注意事项，放在对应步骤附近。
7. 最佳实践或常见问题。
8. 总结，短一点，明确全流程思路。

语言规则

可以自然使用这些教学口吻：

• “本文是一篇...”
• “这篇文章主要讲...”
• “接下来讲讲...”
• “这里有一个点...”
• “注意：...”
• “ps: ...”
• “大功告成”
• “总之，...”
• “如果你...也可以...”
• “不推荐，但是可以介绍一下”

语言要直接，不要过度修饰。

允许轻微口语化，但不要写成强情绪公众号文。少用“卧槽”“太牛逼了”这类强表达，除非用户明确想要。

内容规则

每个教程段落都尽量回答：

• 这一步是干什么的？
• 为什么要这么做？
• 具体怎么做？
• 有什么坑？
• 怎么判断成功？

遇到命令、链接、配置、代码时，直接写出来。

示例：

- 配置 Git
  logseq.order-list-type:: number
  ```bash
  git config --global user.name 用户名
  git config --global user.email 邮箱
  ```

遇到踩坑点时，用引用块或“注意”：

- > 注意：这里最好不要使用 latest，建议固定版本号。

风格禁区

不要写成：

• 公众号散文，铺垫太长、情绪太多、金句太多。
• 横纵分析报告，章节太重、概念太多、资料引用太密。
• 产品营销文案，夸工具、讲愿景、说空泛价值。
• AI 味总结，“赋能”“抓手”“打造闭环”“随着技术发展”“在当今时代”等。
• 过度抽象的方法论，不给读者可复制的命令、模板、步骤。

样本风格特征

常见的参考写法特征：

• 开头直接交代“本文是一篇...”。
• 常用编号章节，如 ## 1. 背景、### 2.1 前置操作。
• 先讲大流程，再讲具体例子。
• 允许 Logseq 的 logseq.order-list-type:: number 元数据。
• 会直接给命令、配置、代码块。
• 会在步骤中穿插“踩坑点”“注意”“ps”。
• 结尾通常是短总结，不做大升华。

改写流程

当用户说“按我的风格改”“不像我写的”“写到这个文档里”时：

1. 读取目标文档。
2. 如果用户给了样本，读取用户明确给出的 1-3 篇样本，不要扫目录；如果没有样本，直接使用本 skill 的内置风格规则。
3. 提炼当前任务需要的文章结构。
4. 直接改目标文档。
5. 保留用户已有元数据，必要时补 author::，作者名从目标文档或用户要求里取。
6. 完成后简单说明改成了什么结构，不要长篇解释。

输出检查

交付前检查：

• 是否是 Logseq 大纲式教程，而不是普通 Markdown 报告？
• 是否有 ## 1. 背景 或等价的开头？
• 是否先讲整体流程，再讲步骤？
• 是否给了可复制的命令、配置、模板或操作步骤？
• 是否有必要的注意事项或踩坑点？
• 是否避免了公众号腔、研究报告腔和营销腔？
• 是否按用户对图片的要求处理，纯文字、图片占位或配图说明不要自作主张？
• 是否避免了无依据扫描大目录，只读取用户给定文件或必要目标文件？

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mlhiter
• Source: mlhiter/skills
• License: MIT

Install and usage instructions live in the source repository linked above.