technical-writing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Technical Writing Skill

技术写作 Skill

Overview

概述

Create technical blog posts about features you're building. This skill analyzes your codebase to understand implementations, then structures clear, engaging content that balances technical detail with readability while avoiding AI-sounding language.

为你正在构建的功能创建技术博客文章。此 Skill 会分析你的代码库以了解实现方式，然后组织清晰、有吸引力的内容，在技术细节与可读性之间取得平衡，同时避免听起来像 AI 生成的表达。

Process

流程

Phase 1: Research and Planning

阶段 1：研究与规划

1.1 Load Writing Guides (REQUIRED - Load First)

Before any other work, load the following:

Writing Rules (from
```
WRITING_ANTI_PATTERNS_PATH
```
env var, or fall back to
```
references/anti-patterns.md
```
) - Comprehensive lists of AI-sounding words, phrases, and patterns to avoid. This is the foundation - what NOT to sound like.
Writing Style Guide (from
```
WRITING_STYLE_GUIDE_PATH
```
env var, or fall back to
```
references/style-guide.md
```
) - Personal writing voice, tone, structure, and signature moves. This is the voice layer - what TO sound like.

PRIORITY RULE: When guides conflict, anti-patterns win. Avoiding AI patterns always takes precedence over stylistic choices.

1.2 Fetch WordPress Taxonomy (if configured)

WORDPRESS_URL

WORDPRESS_USERNAME

, and

WORDPRESS_APP_PASSWORD

env vars are set, fetch available categories and tags before writing so frontmatter uses existing taxonomy:

bash

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/categories?per_page=100" | python3 -c "import sys,json; [print(c['name']) for c in json.load(sys.stdin)]"

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/tags?per_page=100" | python3 -c "import sys,json; [print(t['name']) for t in json.load(sys.stdin)]"

Use these when choosing

category

and

tags

in frontmatter. Prefer existing values. Skip this step if WordPress env vars are not set.

1.3 Understand What Was Built

Investigate the codebase to understand the feature:

Ask which feature or changes they want to write about
Use git to check recent commits if relevant (skip if not a git repo):
```
git log --oneline -10
```
Read relevant code files to understand implementation
Identify key technical decisions, architecture, and interesting details
Note any challenges solved or clever solutions

1.4 Plan the Structure

Plan what to cover in the post. Use these as a guide, not a rigid template:

Opening: Start with an engaging hook or context for what you built
Overview: Brief explanation of the feature (2-3 sentences)
Problem/Value: Why this matters or what problem it solves
Technical Details: How it works with code snippets
- Key implementation details
- Interesting technical decisions
- Architecture or design patterns used
Challenges: What was tricky and how you solved it (if relevant)
Future: Next steps or related features (if relevant)
Tech Stack: Technologies used (can be woven into the narrative or listed)

The actual headings, structure, and flow should feel natural to the specific post - not formulaic.

1.1 加载写作指南（必需——首先加载）

开始任何其他工作前，加载以下内容：

写作规则（来自
```
WRITING_ANTI_PATTERNS_PATH
```
环境变量，或回退到
```
references/anti-patterns.md
```
）——需要避免的、听起来像 AI 的词语、短语和模式的完整列表。这是基础——用于确定不该采用什么样的表达。
写作风格指南（来自
```
WRITING_STYLE_GUIDE_PATH
```
环境变量，或回退到
```
references/style-guide.md
```
）——个人写作声音、语气、结构以及标志性写法。这是声音层——用于确定应该采用什么样的表达。

优先级规则：指南发生冲突时，以反模式指南为准。避免 AI 模式始终优先于风格选择。

1.2 获取 WordPress 分类与标签（如已配置）

如果设置了

WORDPRESS_URL

、

WORDPRESS_USERNAME

和

WORDPRESS_APP_PASSWORD

环境变量，请在写作前获取可用分类和标签，以便 frontmatter 使用现有 taxonomy：

bash

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/categories?per_page=100" | python3 -c "import sys,json; [print(c['name']) for c in json.load(sys.stdin)]"

curl -s -u "$WORDPRESS_USERNAME:$WORDPRESS_APP_PASSWORD" \
  "$WORDPRESS_URL/wp-json/wp/v2/tags?per_page=100" | python3 -c "import sys,json; [print(t['name']) for t in json.load(sys.stdin)]"

选择 frontmatter 中的

category

和

tags

时使用这些值。优先使用现有值。如果未设置 WordPress 环境变量，则跳过此步骤。

1.3 了解构建了什么

调查代码库以了解该功能：

询问他们希望撰写哪个功能或变更
使用 git 查看近期提交（如相关且当前目录是 git 仓库）：
```
git log --oneline -10
```
阅读相关代码文件以了解实现方式
确定关键技术决策、架构和值得关注的细节
记录已解决的挑战或巧妙方案

1.4 规划结构

规划文章需要涵盖的内容。将以下内容作为指南，而不是僵化模板：

开篇：以吸引人的切入点或背景开始，介绍你构建了什么
概述：简要说明该功能（2–3 句话）
问题/价值：说明它为何重要，或解决了什么问题
技术细节：通过代码片段说明其工作方式
- 关键实现细节
- 值得关注的技术决策
- 使用的架构或设计模式
挑战：如果相关，说明哪些部分比较棘手，以及你是如何解决的
未来：如果相关，介绍后续步骤或相关功能
技术栈：使用的技术（可以融入叙述中，也可以单独列出）

实际标题、结构和行文方式应针对具体文章自然展开，不要套用固定公式。

Phase 2: Writing

阶段 2：写作

2.1 Draft Creation

Create the blog post applying BOTH guides you loaded in Phase 1. After drafting, re-read the post against the anti-patterns guide and fix any violations before saving.

Code Snippets:

Keep snippets short (5-15 lines)

Target length: Match length to complexity. Default short.

Simple idea, announcement, or single concept: 400-600 words
Moderate technical walkthrough: 600-900 words
Deep architectural dive or multi-part explanation: 900-1200 words

Err on the side of shorter. If the post can be said in 500 words, don't stretch it to 800. Cut filler, merge thin sections, and stop when the point is made.

2.2 Save the Draft

Save the completed blog post to the drafts directory (create the folder if missing).

To find the save path, run:

echo $WRITING_DRAFTS_PATH

If the output is non-empty, save there
If empty, fall back to
```
.drafts/
```
in the current project

File naming convention:

Format:
```
YYYY-MM-DD-slug.md
```
Slugs should be short, memorable, and easy to type — two words max
Capture the core concept of the post, not necessarily the title
Think "what would I type after the domain name?"
Examples:
```
2025-12-29-ralph.md
```
(post: "How I Got Ralph to Ship Overnight"),
```
2026-01-10-listen.md
```
(post: "Giving my blog a voice"),
```
2025-11-15-choosing-open.md
```
(post: "WordPress Almost Didn't Happen" — about choosing open source)

Frontmatter (REQUIRED):

Every draft must start with YAML frontmatter containing

title

and

url

yaml

---
title: How I got Ralph to ship overnight
url: /ralph
category: Development
tags:
  - AI
  - Shipping
---

```
title
```
— the post title (do NOT repeat as an H1 in the body). Titles should be short (3-7 words), evocative, and leave room for curiosity. Don't explain the whole post — hint at it. Think newspaper headline, not description.
- Good: "Giving my blog a voice", "WordPress Almost Didn't Happen", "Planning Out Loud"
- Bad: "I built a skill that writes blog posts from my codebase" (too long, explains everything)
```
url
```
— the permalink path, matching the filename slug (e.g.
```
/ralph
```
,
```
/listen
```
,
```
/choosing-open
```
)
```
category
```
— WordPress category (use an existing one from Phase 1.2 when available)
```
tags
```
— WordPress tags (prefer existing ones from Phase 1.2)

2.1 创建草稿

创建博客文章时，同时应用第一阶段加载的两份指南。起草后，对照反模式指南重新阅读文章，并在保存前修正所有违规之处。

代码片段：

保持简短（5–15 行）

目标长度：根据复杂度调整。默认保持简短。

简单想法、公告或单一概念：400–600 个单词
中等技术讲解：600–900 个单词
深入架构解析或多部分说明：900–1200 个单词

尽量写短。如果文章用 500 个单词就能说清楚，就不要硬拉到 800 个。删掉填充内容，合并单薄章节，说明到位即止。

2.2 保存草稿

将完成的博客文章保存到草稿目录；如果目录不存在，则创建它。

查找保存路径，运行：

echo $WRITING_DRAFTS_PATH

如果输出非空，则保存到该位置
如果为空，则回退到当前项目中的
```
.drafts/
```

文件命名约定：

格式：
```
YYYY-MM-DD-slug.md
```
slug 应简短、好记且易于输入——最多两个单词
捕捉文章的核心概念，不一定是标题
想想“我会在域名后输入什么？”
示例：
```
2025-12-29-ralph.md
```
（文章：“如何让 Ralph 一夜之间完成交付”）、
```
2026-01-10-listen.md
```
（文章：“让我的博客拥有自己的声音”）、
```
2025-11-15-choosing-open.md
```
（文章：“WordPress 差点就没能实现”——关于选择开源）

Frontmatter（必需）

每篇草稿都必须以包含

title

和

url

的 YAML frontmatter 开头：

yaml

---
title: How I got Ralph to ship overnight
url: /ralph
category: Development
tags:
  - AI
  - Shipping
---

```
title
```
——文章标题（不要在正文中重复为 H1）。标题应简短（3–7 个单词）、有吸引力，并留有想象空间。不要解释整篇文章——只需暗示主题。把它想成报纸头条，而不是描述。
- 好例子：“让我的博客拥有自己的声音”“WordPress 差点就没能实现”“把规划过程说出来”
- 坏例子：“我构建了一个根据我的代码库撰写博客文章的 Skill”（太长，解释了一切）
```
url
```
——permalink 路径，与文件名 slug 一致（例如
```
/ralph
```
、
```
/listen
```
、
```
/choosing-open
```
）
```
category
```
——WordPress 分类（如果阶段 1.2 中获取到了现有分类，则优先使用现有分类）
```
tags
```
——WordPress 标签（优先使用现有标签）

Phase 3: Publishing (Optional)

阶段 3：发布（可选）

3.1 WordPress Publishing

If the user wants to publish to WordPress, load WordPress Publishing Guide (

references/wordpress-publishing.md

) for complete setup and publishing instructions.

The guide covers:

Environment setup and credentials
Python dependencies installation
Publishing commands and workflow
Smart update tracking (no duplicate posts)
Troubleshooting common issues

Quick summary:

First time: Creates new WordPress draft
Subsequent: Updates existing draft (no duplicates)
Always saves as draft (never auto-publishes)
Returns post URL and edit URL

3.1 WordPress 发布

如果用户希望发布到 WordPress，请加载 WordPress Publishing Guide（

references/wordpress-publishing.md

），以获取完整的设置和发布说明。

该指南涵盖：

环境设置与凭据
Python 依赖安装
发布命令与工作流
智能更新跟踪（避免重复文章）
常见问题排查

快速总结：

首次运行：创建新的 WordPress 草稿
后续运行：更新现有草稿（不创建重复内容）
始终保存为草稿（绝不自动发布）
返回文章 URL 和编辑 URL

Output Format

输出格式

After creating and saving the blog post, provide:

Saved Location: Path where the post was saved
Post Title: The final title used
Key Files Referenced: List of files mentioned with line numbers
Word Count: Approximate length

创建并保存博客文章后，提供：

保存位置：文章的保存路径
文章标题：最终使用的标题
引用的关键文件：列出的文件及行号
字数：大致长度

Example Interaction

示例交互

User: "Help me write about the voice planning feature"

Response:

Let me investigate the voice planning implementation to write about it.

[Phase 1: Loads anti-patterns + style guide, fetches WP taxonomy, reads code]

[Phase 2: Creates and saves blog post applying both guides]

Blog post saved to: .drafts/2025-12-29-planning-aloud.md

Title: "Planning Out Loud"

Key Files Referenced:
- src/components/voice-session.tsx:78 (voice session initialization)
- src/app/api/webhook/route.ts:40 (webhook signature validation)
- src/lib/claude.ts:88 (Claude tool calling)

Word Count: ~550 words

用户：“帮我写一篇关于语音规划功能的文章”

响应：

Let me investigate the voice planning implementation to write about it.

[Phase 1: Loads anti-patterns + style guide, fetches WP taxonomy, reads code]

[Phase 2: Creates and saves blog post applying both guides]

Blog post saved to: .drafts/2025-12-29-planning-aloud.md

Title: "Planning Out Loud"

Key Files Referenced:
- src/components/voice-session.tsx:78 (voice session initialization)
- src/app/api/webhook/route.ts:40 (webhook signature validation)
- src/lib/claude.ts:88 (Claude tool calling)

Word Count: ~550 words

Environment Variables

环境变量

Configure in Claude Code settings (

~/.claude/settings.json

) under the

env

key:

json

{
  "env": {
    "WRITING_STYLE_GUIDE_PATH": "/path/to/style-guide.md",
    "WRITING_ANTI_PATTERNS_PATH": "/path/to/anti-patterns.md",
    "WRITING_DRAFTS_PATH": "/path/to/drafts",
    "WORDPRESS_URL": "https://yourblog.com",
    "WORDPRESS_USERNAME": "your_username",
    "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx",
    "WRITING_TITLE_CASE_STYLE": "title",
    "WRITING_HEADING_CASE_STYLE": "sentence"
  }
}

Variable	Required	Description
`WRITING_STYLE_GUIDE_PATH`	No	Path to shared writing style guide. Loaded in Phase 1.1
`WRITING_ANTI_PATTERNS_PATH`	No	Path to shared anti-patterns. Overrides `references/anti-patterns.md`
`WRITING_DRAFTS_PATH`	No	Where to save drafts. Falls back to `.drafts/` in current project
`WORDPRESS_URL`	For publishing	WordPress site URL (include `https://` )
`WORDPRESS_USERNAME`	For publishing	WordPress account username
`WORDPRESS_APP_PASSWORD`	For publishing	Application password (not regular password)
`WRITING_TITLE_CASE_STYLE`	No	`"sentence"` (default) or `"title"`
`WRITING_HEADING_CASE_STYLE`	No	`"sentence"` (default) or `"title"`

在 Claude Code 设置（

~/.claude/settings.json

）的

env

键下配置：

json

{
  "env": {
    "WRITING_STYLE_GUIDE_PATH": "/path/to/style-guide.md",
    "WRITING_ANTI_PATTERNS_PATH": "/path/to/anti-patterns.md",
    "WRITING_DRAFTS_PATH": "/path/to/drafts",
    "WORDPRESS_URL": "https://yourblog.com",
    "WORDPRESS_USERNAME": "your_username",
    "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx",
    "WRITING_TITLE_CASE_STYLE": "title",
    "WRITING_HEADING_CASE_STYLE": "sentence"
  }
}

变量	是否必需	说明
`WRITING_STYLE_GUIDE_PATH`	否	共享写作风格指南的路径。在阶段 1.1 加载
`WRITING_ANTI_PATTERNS_PATH`	否	共享反模式指南的路径。覆盖 `references/anti-patterns.md`
`WRITING_DRAFTS_PATH`	否	保存草稿的位置。回退到当前项目中的 `.drafts/`
`WORDPRESS_URL`	发布时必需	WordPress 站点 URL（包含 `https://` ）
`WORDPRESS_USERNAME`	发布时必需	WordPress 账户用户名
`WORDPRESS_APP_PASSWORD`	发布时必需	应用程序密码（不是常规密码）
`WRITING_TITLE_CASE_STYLE`	否	标题大小写样式： `"sentence"` （默认）或 `"title"`
`WRITING_HEADING_CASE_STYLE`	否	标题层级大小写样式： `"sentence"` （默认）或 `"title"`

Tips for Best Results

获得最佳结果的提示

Be specific about scope: "Write about the webhook security implementation" is better than "write about webhooks"
Mention target audience: "For developers familiar with Next.js" vs "For non-technical readers"
Specify length preference: "Quick 500-word update" vs "Detailed deep-dive"
Share context: "This is part 2 in a series" or "First post about this project"
Request revisions: After the draft, ask to expand sections, simplify explanations, or adjust tone

明确范围：“写一篇关于 webhook 安全实现的文章”优于“写写 webhook”
说明目标受众：“面向熟悉 Next.js 的开发者”与“面向非技术读者”
指定长度偏好：“简短的 500 词更新”与“详细深入解析”
分享背景：“这是一个系列的第 2 篇”或“这是关于这个项目的第一篇文章”
提出修改要求：完成草稿后，要求扩展章节、简化说明或调整语气

Advanced: Series Posts

高级：系列文章

For multi-part series:

Start with "Help me outline a 3-part series about [topic]"
Each post should build on previous ones
Include "Previously" and "Next up" sections
Keep consistent structure across posts

对于多部分系列：

从“帮我规划一个关于[主题]的 3 部分系列开始”入手
每篇文章都应在前一篇的基础上继续展开
包含“上一篇”和“下一篇”章节
保持各篇文章的结构一致