AgentSkillsCN

writing

基于津瑟原则的清晰写作标准。用于文档、提交消息、PR 描述和技术交流。

SKILL.md
--- frontmatter
name: writing
description: Clear writing standards based on Zinsser's principles. Use for documentation, commit messages, PR descriptions, and technical communication.

Writing Standards

Based on William Zinsser's "On Writing Well".

Core Principles

Clarity

  • •One idea per sentence
  • •Short sentences (<25 words)
  • •Active voice ("We fixed" not "was fixed")

Brevity

  • •Every word must earn its place
  • •Cut redundant words
  • •Delete clutter

Simplicity

  • •Simple words over complex
  • •Concrete over abstract
  • •Specific over vague

Patterns

Commit Messages

code
<verb> <what>
  • •Add user authentication
  • •Fix payment validation
  • •Refactor database queries

Never: "Fixed stuff", "Updates", "Claude Code"

PR Descriptions

code
## Summary
[One sentence: what changed]

## Why
[One paragraph: motivation]

## Testing
[How to verify]

Error Messages

code
<What happened>. <What to do>.
  • •User not found. Check the email.
  • •Payment failed. Retry or contact support.

Documentation

  1. •What it does (one sentence)
  2. •Why it exists (one paragraph)
  3. •How to use it (clear steps)
  4. •Examples (if needed)

Avoid

  • •Passive voice
  • •Redundant words ("in order to" → "to")
  • •Jargon without explanation
  • •Hedging ("might", "possibly")
  • •Long paragraphs (>5 sentences)

Test Your Writing

  • •Can you cut 30%?
  • •Is every word necessary?
  • •Would you say this to a friend?
  • •Can someone skim and understand?