AgentSkillsCN

Writing for Developers

当用户请求“撰写文章”、“帮我写博客文章”、“起草技术文章”、“审阅我的文章”、“检查我的写作”、“改进这篇草稿”、“给我写作反馈”、“寻找主题”、“我该写些什么”或提及“写作教练”时，应使用此技能。提供全面的指导，包括主题选择、17 种写作技巧，以及来自 Piotr Sarna 和 Cynthia Dunlop 的《为开发者而写的写作》中的审稿人协作。

SKILL.md
--- frontmatter
name: Writing for Developers
description: This skill should be used when the user asks to "write an article", "help me write a blog post", "draft a technical article", "review my article", "check my writing", "improve this draft", "give me writing feedback", "find a topic", "what should I write about", or mentions "writing coach". Provides comprehensive guidance including topic selection, 17 writing skills, and reviewer collaboration from "Writing for Developers" by Piotr Sarna & Cynthia Dunlop.
version: 2.0.0

Technical Article Writing Coach

A comprehensive writing coach skill based on "Writing for Developers: Blogs that get read" by Piotr Sarna & Cynthia Dunlop. Guides users through topic selection, drafting, review, and publishing.

Topic Selection (Before Everything)

The 3 Ps Test - Does your topic meet at least one?

  • •Proud of - Accomplishments you're eager to show off
  • •Pained by - Challenges that caused constant headaches
  • •Passionate about - What gets your blood racing

If you're not personally proud, pained, or passionate about the topic, the blog post won't yield great results.

See references/topic-selection.md for topic idea sources and testing methods.

The 15 Core Writing Skills

Pre-Writing Phase

1. Goal Definition - Before writing, establish:

  • •"The goal of this article is to..." (never published)
  • •"My perspective is interesting because..." (never published)
  • •Who is the target reader? What do they already know?

2. Pattern Selection - Match content to the right structure:

Content TypePattern
Finding/fixing a tricky bugBug Hunt
Migrating to new language/frameworkRewrote It in X
Significant technical projectHow We Built It
Hard-won wisdom from experienceLessons Learned
Opinion on industry directionThoughts on Trends
Educational content with productNon-markety Product
Performance data/comparisonsBenchmarks

Writing Phase

3. Evidence-Based Claims - Support every statement with specifics 4. Conversational Voice - Write authentically, not robotically 5. Single-Idea Paragraphs - One idea per paragraph 6. Scannability - Headings, bold key points, lists/tables 7. Show Don't Tell - Code, diagrams, specific numbers 8. Actionable Writing - Don't make reader think

See references/actionable-writing.md for transforming abstract → actionable.

Review Phase (The 3 F's)

9. Facts Check - Is each claim supported by evidence? 10. Focus Check - Does every paragraph advance the goal? 11. Flow Check - Logical progression? Smooth transitions? 12. Component Review - Title, intro, headings, ending, code, visuals 13. Pattern-Specific Review - Apply criteria for chosen pattern 14. Pre-Publish Verification - Links, code, images, metadata 15. Self-Review Test - Would I share this if someone else wrote it?

Human Voice (Avoiding AI-Sounding Writing)

Check for AI red flags:

  • •Unusually dense/consistent metaphors
  • •Overly flowery, consistently ornate prose
  • •Lack of specific technical details
  • •Artificial emotional arc
  • •Excessive em dashes (—) - Classic AI tell

To sound human:

  • •Include specific, idiosyncratic details
  • •Admit mistakes, uncertainties, frustrations
  • •Let voice vary naturally
  • •Include self-deprecating comments

See references/human-voice.md for detailed guidance.

Working with Reviewers

Selecting reviewers:

  • •Technical reviewer (knows subject matter)
  • •Clarity reviewer (unfamiliar with topic)

Preparing reviewers:

  • •Provide background on goal and target reader
  • •Specify what feedback you want

See references/working-with-reviewers.md for detailed guidance.

Workflow for Writing New Articles

  1. •Topic Selection - Apply the 3 Ps test
  2. •Goal Definition - Write goal and differentiator sentences
  3. •Pattern Selection - Match to appropriate pattern
  4. •Draft - Focus on getting ideas down fast
  5. •Optimize - Apply the 3 F's (Facts, Focus, Flow)
  6. •Review - Get feedback from reviewers
  7. •Ship - Final checks and publish

Coaching Prompts

Stuck starting:

"Start with the most interesting technical part. What's the one thing you most want to share?"

Too much content:

"Go back to your goal statement. Does this paragraph advance that goal? If not, cut it."

Doubts expertise:

"You're the world's expert on YOUR specific experience. Share what you learned."

Additional Resources

Reference Files

  • •references/topic-selection.md - The 3 Ps test, topic idea sources
  • •references/writing-skills-complete.md - Full skills reference with all details
  • •references/actionable-writing.md - Transform abstract → actionable
  • •references/human-voice.md - Sound human, not AI-generated
  • •references/native-english-style.md - Sentence optimization, clarity
  • •references/seo-metadata.md - Keywords, titles, meta descriptions
  • •references/visual-code-presentation.md - Headings, images, code
  • •references/working-with-reviewers.md - Selecting and working with reviewers
  • •references/pattern-examples.md - Real-world blog post examples