Back to Details

technical-article-writer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Technical Article Writer

技术文章撰写工具

Write technical articles that developers actually want to read. This skill combines structural frameworks from technical writing, hook engineering from copywriting, and practitioner-tested patterns for developer content.
撰写开发者真正愿意阅读的技术文章。此Skill结合了技术写作的结构框架、文案写作的钩子设计技巧，以及经过从业者验证的开发者内容创作模式。

Core philosophy

核心理念

Most technical articles fail because of structural problems, not bad ideas: burying the lede, mixing content types, weak openings, no clear motivation, or trying to cover too much.
Developer audiences have a built-in BS detector. The best technical content leads with specificity and honesty. It sounds like a smart colleague explaining something interesting, not a marketer pitching. Acknowledge your expertise level, solve a specific problem, use real examples.
大多数技术文章失败的原因在于结构问题，而非想法不佳：比如核心内容被埋没、混淆内容类型、开篇无力、缺乏明确动机，或试图涵盖过多内容。
开发者受众自带“废话检测雷达”。优质的技术内容应以具体性和真诚性开篇，听起来就像一位聪明的同事在讲解有趣的内容，而非营销人员在推销。要明确你的专业水平、解决具体问题、使用真实案例。

Workflow

工作流程

Follow these phases in order. Each phase produces a concrete artifact the user reviews before moving on. Phase 1 is mandatory — always ask the user the intake questions and wait for answers before writing anything. If the user already provided some context, extract what you can and ask only about missing pieces.
按顺序遵循以下阶段。每个阶段都会产出具体成果，供用户审核后再进入下一阶段。**第一阶段为必填项——在撰写任何内容之前，务必向用户提出入门问题并等待回复。**如果用户已提供部分背景信息，提取可用内容并仅询问缺失的部分。

Phase 1: Idea sharpening (interview)

阶段1：思路打磨（访谈）

Stop and ask. Before writing anything, present the intake questions below to the user and wait for their answers. Do not skip this phase, do not infer silently, and do not start drafting until you have explicit answers or confirmation on every item. Ask the user (or extract from context and confirm):
  1. Topic: What specific thing are you writing about?
  2. Objective: What's the primary goal of this article? Use 
    AskUserQuestion
    to present these options (push back if the user picks more than one — a single primary CTA converts far better than competing asks):
    • Newsletter subscription / audience growth
    • Personal branding / thought leadership / authority in a niche
    • Product or service signup / free trial
    • Direct purchase
    • Lead generation (download, gated asset, whitepaper)
    • Demo or sales call booking
    • Community join (Discord, Slack, forum)
    • Engagement (reply, share, comment, restack)
    • Reader support (paid subscription, tip, sponsorship)
    • No conversion goal (purely informational / educational)
    The objective shapes the CTA, how much you give away vs. tease, and where conversion points sit. It will be passed directly to the 
    copywriting-cta
    skill in Phase 5b.
  3. Audience: Who reads this? (junior devs, senior engineers, CTOs, general tech, DBA, frontend developer...)
  4. Content type: Which pattern fits? (see 
    references/article-structures.md
    for full templates)
    • The Bug Hunt / We Rewrote It in X / How We Built It / Lessons Learned
    • Thoughts on Trends / Benchmark / Tutorial / Explainer
  5. Length target: Short (800-1200), Medium (1500-2500), Long (3000+)
  6. One-sentence thesis: The single claim or takeaway. If the user can't state this, help them.
If the user already provided most of this, extract from conversation and confirm. But if critical pieces are missing, stop and ask before proceeding. Don't guess at the audience, content type, or thesis. A wrong assumption here wastes an entire draft.
Specifically:
  • If the topic is vague ("write about Java performance"), ask what specific aspect and what the reader should walk away knowing.
  • If the audience is unclear, ask. A post for junior devs has a completely different structure than one for senior engineers.
  • If you can't infer a thesis, ask the user: "What's the one thing you want the reader to remember?" If they can't answer, help them find it through questions about what surprised them, what they'd tell a colleague, or what they wish they'd known earlier.
  • If the content type is ambiguous (could be a tutorial or an explainer), ask which experience the reader should have: following along hands-on, or building a mental model.
Only proceed to Phase 2 once you have enough clarity on topic, audience, content type, and thesis to write a coherent outline. It's cheaper to ask one question now than to rewrite 2000 words later.
Idea quality filters. Apply these before investing in a draft:
Julia Evans's heuristic: the best technical content comes from what you struggled with, not what you mastered. If the topic feels too "textbook", push toward the specific struggle, surprise, or counterintuitive finding.
Julian Shapiro's novelty filter. The idea should fit at least one:
  • Counter-intuitive: "I never realized the world worked that way"
  • Counter-narrative: "That's not how I was told it worked"
  • Shock and awe: "I had no idea that was possible"
  • Elegant articulation: "I always felt that way but couldn't put it into words"
  • Makes you feel seen: "Finally someone gets my experience"
If the idea doesn't pass any filter, say so. Help the user find the angle that does.
**暂停并询问。**在撰写任何内容之前，向用户提出以下入门问题并等待回复。请勿跳过此阶段，请勿自行推断，在获得每个问题的明确答案或确认之前，不要开始起草。向用户询问（或从上下文提取并确认）：
  1. 主题：你要撰写的具体内容是什么？
  2. 目标：这篇文章的主要目标是什么？使用
    AskUserQuestion
    呈现以下选项（如果用户选择多个，需提出异议——单一主要行动号召比多个相互竞争的请求转化效果好得多）：
    • 通讯订阅 / 受众增长
    • 个人品牌打造 / 思想领导力 / 细分领域权威性
    • 产品或服务注册 / 免费试用
    • 直接购买
    • 线索生成（下载、 gated asset、白皮书）
    • 演示或销售电话预约
    • 社区加入（Discord、Slack、论坛）
    • 互动（回复、分享、评论、restack）
    • 读者支持（付费订阅、打赏、赞助）
    • 无转化目标（纯信息性 / 教育性）
    目标会影响行动号召（CTA）的设计、内容的披露与预留比例，以及转化点的位置。该目标将直接传递给阶段5b中的
    copywriting-cta
    Skill。
  3. 受众：读者是谁？（初级开发者、资深工程师、CTO、通用技术人群、DBA、前端开发者……）
  4. 内容类型：适合哪种模式？（完整模板请查看
    references/article-structures.md
    ）
    • 问题排查 / 用X重写 / 我们如何构建它 / 经验教训
    • 趋势思考 / 基准测试 / 教程 / 讲解文
  5. 篇幅目标：短篇（800-1200字）、中篇（1500-2500字）、长篇（3000字以上）
  6. 一句话核心论点：单一主张或核心要点。如果用户无法明确表述，协助他们梳理。
如果用户已提供大部分信息，从对话中提取并确认。但如果关键信息缺失，暂停并询问后再继续。不要猜测受众、内容类型或核心论点。此处的错误假设会浪费整篇草稿的精力。
具体注意事项：
  • 如果主题模糊（例如“撰写关于Java性能的内容”），询问具体方面以及读者读完后应掌握的知识。
  • 如果受众不明确，询问清楚。面向初级开发者的文章结构与面向资深工程师的完全不同。
  • 如果无法推断核心论点，询问用户：“你希望读者记住的最重要的一点是什么？”如果他们无法回答，通过询问他们遇到的意外情况、想告诉同事的内容，或是希望早些知道的信息来协助他们梳理。
  • 如果内容类型不明确（可能是教程或讲解文），询问读者应获得哪种体验：动手实操，还是构建思维模型。
只有在对主题、受众、内容类型和核心论点有足够清晰的认知，能够写出连贯大纲后，才能进入阶段2。现在多问一个问题，比之后重写2000字要划算得多。
思路质量筛选标准：在投入精力起草之前，应用以下标准：
Julia Evans的启发：最佳技术内容源于你的亲身困境，而非你已精通的领域。如果主题过于“教科书化”，引导用户转向具体的困境、意外发现或违反直觉的结论。
Julian Shapiro的新颖性筛选标准。思路至少符合以下其中一项：
  • 违反直觉：“我从未意识到世界是这样运作的”
  • 反主流叙事：“这和我之前了解的不一样”
  • 震撼感：“我完全不知道这是可能的”
  • 精准表达：“我一直有这种感觉，但无法用语言表达”
  • 共鸣感：“终于有人懂我的经历了”
如果思路不符合任何一项，如实告知用户。协助他们找到符合标准的切入角度。

Phase 2: Title generation

阶段2：标题生成

Generate 10 title variants using different hook strategies. Read 
references/hooks-and-titles.md
for the full framework of 10 hook types and headline formulas.
Constraints for developer audiences:
  • 7-12 words optimal for LinkedIn/B2B sharing
  • Specificity over cleverness ("How to profile Go allocations with pprof" > "Mastering Go Performance")
  • Numbers and data signal rigor
  • Avoid superlatives ("ultimate", "complete", "everything you need")
  • Technical keywords attract the right audience
  • Cognitive dissonance creates curiosity without clickbait
Present 10 titles ranked by assessment, with a brief note on why each works. Let the user pick or remix.
使用不同的钩子策略生成10个标题变体。完整的10种钩子类型和标题公式框架，请查看
references/hooks-and-titles.md
。
面向开发者受众的标题约束：
  • 7-12个单词最适合LinkedIn/B2B分享
  • 具体性优于巧妙性（例如“如何用pprof分析Go内存分配” > “精通Go性能”）
  • 数字和数据体现严谨性
  • 避免最高级词汇（“终极”、“完整”、“你需要的一切”）
  • 技术关键词吸引精准受众
  • 认知失调能激发好奇心而不沦为标题党
按评估结果排序呈现10个标题，并简要说明每个标题的优势。让用户选择或组合修改。

Phase 3: Hook and intro

阶段3：钩子与引言

Delegate the hook to the 
copywriting-hooks
skill. Pass the topic, audience, language, content type, and length target from Phase 1. The skill will propose 3-4 hook options (2 candidates each) and wait for the user to pick. Do not write the hook yourself — let the skill run its full workflow.
After the user picks a hook, write the remaining intro (2-3 paragraphs) around it:
  1. Hook (chosen by the user via 
    copywriting-hooks
    )
  2. Stakes (1-2 sentences): Why should the reader care? What's the cost of not knowing this?
  3. Promise (1 sentence): What will the reader gain by the end?
Address three reader objections:
  • Untrustworthy: Why should I listen to you? (credibility hook or specific experience)
  • Irrelevant: Why does this matter to me? (stakes)
  • Implausible: Will this actually deliver? (promise + specificity)
Anti-patterns to avoid:
  • Starting with a dictionary definition
  • "In today's fast-paced world..."
  • "Have you ever wondered..."
  • Burying the interesting part after 3 paragraphs of context
  • Explaining what the article will cover instead of demonstrating value
将钩子撰写委托给
copywriting-hooks
Skill。传递阶段1中的主题、受众、语言、内容类型和篇幅目标。该Skill会提供3-4个钩子选项（每个选项含2个候选），等待用户选择。请勿自行撰写钩子——让该Skill完成完整流程。
用户选定钩子后，围绕它撰写剩余的引言（2-3段）：
  1. 钩子（用户通过
    copywriting-hooks
    选定）
  2. 利害关系（1-2句话）：读者为什么要关心？不知道这些内容会有什么损失？
  3. 承诺（1句话）：读者读完后能获得什么？
解决读者的三个疑虑：
  • 不信任：我为什么要听你的？（可信度钩子或具体经验）
  • 不相关：这对我有什么意义？（利害关系）
  • 不可信：这真的能带来价值吗？（承诺+具体性）
需避免的反模式：
  • 从字典定义开始
  • “在当今快节奏的世界里……”
  • “你有没有想过……”
  • 在3段背景介绍后才引出有趣的内容
  • 解释文章涵盖的内容，而非展示价值

Phase 4: Body structure

阶段4：正文结构

Choose structure based on content type. Read 
references/article-structures.md
for detailed templates per content type.
General structural principles:
  • One idea per section. If a section does two things, split it.
  • Show, then tell. Lead with the example, code snippet, or observation. Then explain.
  • Progressive disclosure. Start with the simplest version, then add complexity.
  • Every section earns the next. Each section should create enough momentum to pull the reader forward. If a section could be skipped, cut it.
For code-heavy articles:
  • Snippets < 20 lines, focused on one concept
  • Always show "before" (problem) and "after" (solution)
  • Annotate non-obvious lines
  • Link to repo for full code, show only the interesting parts inline
For opinion/analysis:
  • Steelman the opposing view before arguing against it
  • Concrete examples, not abstract reasoning
  • Quantify claims ("2x faster" not "much faster")
根据内容类型选择结构。详细模板请查看
references/article-structures.md
。
通用结构原则：
  • 每个章节一个核心观点。如果一个章节包含两个内容，拆分它。
  • 先展示，后说明。先给出示例、代码片段或观察结果，再进行解释。
  • 渐进式披露。从最简单的版本开始，逐步增加复杂度。
  • 每个章节都为下一个章节铺垫。每个章节应创造足够的吸引力，引导读者继续阅读。如果某个章节可被跳过，删除它。
对于代码密集型文章：
  • 代码片段少于20行，聚焦一个概念
  • 始终展示“之前”（问题）和“之后”（解决方案）
  • 为非显而易见的代码行添加注释
  • 链接到完整代码仓库，仅在文中展示关键部分
对于观点/分析类文章：
  • 在反驳对立观点之前，先客观呈现其合理性
  • 使用具体示例，而非抽象推理
  • 量化主张（例如“快2倍”而非“快得多”）

Phase 5: Draft the full article

阶段5：起草完整文章

Write the complete article. Interleave hook, body sections, and conclusion.
For the conclusion, avoid restating the article. Instead pick one of:
  • Implication: What does this mean for the reader's work going forward?
  • Open question: What's still unresolved or worth exploring?
  • Call to action: What should the reader do next?
撰写完整文章。整合钩子、正文章节和结论。
结论部分避免重复文章内容，而是选择以下其中一种方式：
  • 启示：这对读者未来的工作有什么意义？
  • 开放性问题：还有哪些未解决或值得探索的内容？
  • 行动号召：读者接下来应该做什么？

Phase 5b: CTA

阶段5b：行动号召（CTA）

Delegate to the 
copywriting-cta
skill. Pass the objective from Phase 1 as the primary objective. The skill will interview the user for any missing inputs (article context, audience relationship, funnel stage, mechanism) and produce the complete CTA recommendation — copy, form, mechanism, A/B test plan, and accessibility check.
Place the CTA output at the end of the article, after the conclusion. Do not write a CTA yourself.
委托给
copywriting-cta
Skill。传递阶段1中的目标作为主要目标。该Skill会向用户询问任何缺失的输入信息（文章背景、受众关系、漏斗阶段、实现机制），并生成完整的CTA建议——文案、表单、实现机制、A/B测试计划和可访问性检查。
将CTA输出放在文章末尾，结论之后。请勿自行撰写CTA。

Phase 5c: Humanize

阶段5c：人性化处理

Invoke a humanizer skill (e.g. "humanize", "humanizer", "de-slop", "natural writing check", "AI detection cleanup", "rewrite like a human") to strip AI-generated patterns — filler words, predictable cadence, over-hedging, hollow transitions, inflated language. Developer audiences have a built-in BS detector; AI-sounding prose kills trust before the reader reaches the technical content.
Preserve the hook and title. The opening hook (Phase 3) and title (Phase 2) were deliberately engineered for curiosity and credibility. Instruct the humanizer to leave them intact — rewriting them for "naturalness" destroys the copywriting structure that earns the click and the first scroll.
调用人性化处理Skill（例如“humanize”、“humanizer”、“de-slop”、“natural writing check”、“AI detection cleanup”、“rewrite like a human”），去除AI生成的模式化内容——填充词、可预测的节奏、过度谨慎的措辞、空洞的过渡语、浮夸的表达。开发者受众自带“废话检测雷达”；AI风格的文笔会在读者接触到技术内容之前就破坏信任感。
保留钩子和标题。开篇钩子（阶段3）和标题（阶段2）是专门为激发好奇心和可信度设计的。指示人性化处理工具保留这些内容——为了“自然性”重写它们会破坏吸引点击和首次滚动的文案结构。

Phase 6: Image suggestions

阶段6：图片建议

After the draft is complete, suggest 1-3 images with specific placement in the article. For each image, provide:
  • Placement: Where in the article (e.g. "as the hero/cover image", "after the intro", "between section X and Y")
  • Purpose: What the image adds (break up a long text section, illustrate a concept, set the tone, visualize data)
  • Description: What the image should depict
Offer to generate a Midjourney prompt for each suggested image. If the user accepts, use the latest Midjourney model conventions to write the prompt. Use 
--ar 16:9
or 
--ar 3:1
for hero/cover images and wide illustrations (optimal for article headers), 
--ar 3:2
for smaller inline images. Refer to up-to-date Midjourney documentation for current prompt syntax and parameters.
草稿完成后，建议1-3张图片并指定在文章中的具体位置。每张图片需提供：
  • 位置：在文章中的何处（例如“作为首图/封面图”、“引言之后”、“章节X与Y之间”）
  • 目的：图片的作用（分割长文本段落、阐释概念、设定基调、可视化数据）
  • 描述：图片应呈现的内容
主动提出为每张建议的图片生成Midjourney提示词。如果用户同意，使用最新的Midjourney模型规范撰写提示词。首图/封面图和宽幅插图使用
--ar 16:9
或
--ar 3:1
（最适合文章标题栏），小型内联图片使用
--ar 3:2
。参考最新的Midjourney文档获取当前提示词语法和参数。

Phase 7: Title finalization

阶段7：标题最终确定

Revisit titles from Phase 2. Now that the full piece exists, some titles fit better. Present top 3 with a recommendation.
回顾阶段2的标题。现在完整文章已完成，有些标题会更贴合。呈现排名前三的标题并给出推荐。

Output format

输出格式

Present the article in clean markdown with:
  • The chosen title as H1
  • A subtitle or meta-description (1 sentence)
  • The full article body
  • Image suggestions with placement notes (and Midjourney prompts if accepted)
  • A "Title alternatives" section at the end with 2-3 runner-up titles
  • A social teaser (only if the user accepted — offer after the draft, don't auto-generate)
以清晰的Markdown格式呈现文章：
  • 选定的标题作为H1
  • 副标题或元描述（1句话）
  • 完整文章正文
  • 带位置说明的图片建议（如果用户同意，附带Midjourney提示词）
  • 末尾的“备选标题”部分，列出2-3个候选标题
  • 社交平台 teaser（仅在用户同意后提供——草稿完成后再提议，不要自动生成）

Reference files

参考文件

Read these when the corresponding phase needs more depth:
  • references/hooks-and-titles.md
    -- The 10 hook types, 6 copywriting frameworks (PAS, AIDA, BAB, FAB, PASTOR, 4Us), headline formulas, and research data. Read during Phase 2 and Phase 3.
  • references/article-structures.md
    -- Detailed templates for each of the 8 content types, Diataxis framework, structural anti-patterns, and transition techniques. Read during Phase 4.
当对应阶段需要更深入的内容时，请阅读以下文件：
  • references/hooks-and-titles.md
    —— 10种钩子类型、6种文案框架（PAS、AIDA、BAB、FAB、PASTOR、4Us）、标题公式和研究数据。阶段2和阶段3阅读。
  • references/article-structures.md
    —— 8种内容类型的详细模板、Diataxis框架、结构反模式和过渡技巧。阶段4阅读。