AgentStack
Browse Sign in
Browse Why AgentStack Sell Docs
Sign in
SKILL verified MIT Self-run

Doc Writing Best Practices

skill-jinsyin-skills-doc-writing-best-practices · by JinsYin

中文技术文档的写作规范。涵盖中西文混排的空格与标点、标题层级与代码块标注、表格与列表的取舍、以及"写清为什么"和"示例可直接抄用"的内容要求。在编写或修改 README、设计文档、运维手册、变更说明、注释块等任何面向人阅读的中文技术文档时使用——尤其是产出 Markdown 文件、写提交说明、或整理已有文档时。

↗ Repository
— No reviews yet
0 installs
27 views
0.0% view→install

Install

$ agentstack add skill-jinsyin-skills-doc-writing-best-practices

✓ scanned · ✓ verified, works with Claude Code, Cursor, and more.

Security review

✓ Passed

No issues found. Passed automated security review. · v0.1.0 How review works →

  • ✓ Prompt-injection patterns
  • ✓ Secret / credential exfiltration
  • ✓ Dangerous shell & filesystem operations
  • ✓ Untrusted network calls
  • ✓ Known-malicious package signatures

What it can access

  • ✓ Network access No
  • ✓ Filesystem access No
  • ✓ Shell / process execution No
  • ✓ Environment & secrets No
  • ✓ Dynamic code execution No

From automated source analysis of v0.1.0. “Used” means the capability is present in the source — more access means more to trust, not that it’s unsafe.

View the full security report →

Verified badge

Passed review? Show it. Paste this badge into your README, it links to the public security report.

AgentStack Verified badge Links to your public security report.
[![AgentStack Verified](https://agentstack.voostack.com/badges/verified.svg)](https://agentstack.voostack.com/security/report/skill-jinsyin-skills-doc-writing-best-practices)

Reliability & compatibility

✓ Security review passed
0 installs to date
— no reviews yet
● 1mo ago

Declared compatibility

Claude CodeClaude Desktop

Compatibility is declared by the source manifest. End-to-end runtime verification is coming, see below.

Preview Execution monitoring

We're building live execution health for every listing: tool-call success rate, median latency, uptime, and last-checked timestamps, measured, not self-reported. It isn't live yet, so we don't show numbers we can't stand behind.

How agent discovery & health will work →
Are you the author of Doc Writing Best Practices? Claim this listing to set pricing, connect Stripe payouts, and keep 70% of every sale.
Sign up to claim

About

Doc Writing Best Practices

中文技术文档的规范集，8 条规则分 3 类。

如何使用本 skill

规则总量小，可以先读索引再按需取；若正在集中整理一批文档，直接通读 AGENTS.md 也不贵。

| 你在做什么 | 先读 | |---|---| | 写任何中文文档 | cjk-*（3 条，成本最低收益最直接） | | 写 README / 设计文档 | content-*、struct-heading-no-skip | | 写运维手册 / 操作步骤 | content-example-copy-ready、struct-code-fence-language | | 整理已有文档 | 全部 |

这类规范的共性

文档的失效方式和代码不同：没有编译器会告诉你写错了。排版不一致、示例抄不动、缺少"为什么"——这些都不会报错，只会让读者慢慢地不再信任这份文档。

而一份过期或含糊的文档比没有文档更糟：它会被信任，然后把人带偏。

分类与影响级别

| 优先级 | 分类 | 影响 | 前缀 | 条数 | |---|---|---|---|---| | 1 | 内容质量 | HIGH | content- | 2 | | 2 | 文档结构 | MEDIUM | struct- | 3 | | 3 | 中文排版 | MEDIUM | cjk- | 3 |

排序按影响，不按阅读顺序——cjk-* 最常用但后果最轻。

规则索引

1. 内容质量（HIGH）

  • content-example-copy-ready — 示例用真实值、可直接粘贴执行；占位符会被抄错，且错在读者的环境里
  • content-why-not-just-what — 写清为什么，只写"怎么做"的文档在情况变化时无法判断是否还适用

2. 文档结构（MEDIUM）

  • struct-code-fence-language — 代码块必须标语言；标错比不标更糟，纯输出显式标 text
  • struct-heading-no-skip — 层级不跳级、一篇一个 H1、深度控制在 H4 内
  • struct-table-vs-list — 有共同维度用表格、无共同维度用列表；表格里不放长段落

3. 中文排版（MEDIUM）

  • cjk-latin-spacing — 中文与西文、行内代码之间加空格；一致性比选哪一种更重要
  • cjk-number-spacing — 中文与数字之间加空格
  • cjk-punctuation — 中文句子用全角标点；判据是这一段的主语言，不是整篇文档

与项目规范的关系

本 skill 是跨项目通用基线。具体的术语表、平台称谓、对外文案口径属于项目事实，应写在项目的 CLAUDE.md，不要写进这里。

冲突时以项目自身的约定为准。

维护

改动 rules/ 后必须重新生成全量版：

bash scripts/build.sh

Source & license

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

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

Reviews

No reviews yet, be the first.

Write a review

Versions

  • v0.1.0 Imported from the upstream source.

More in Content & Media