AgentSkillsCN

technical-writing

编写清晰、结构化良好的技术文档指南

SKILL.md
--- frontmatter
name: technical-writing
description: Guidelines for creating clear, well-structured technical documentation
version: 1.0.0
tags:
  - documentation
  - writing
  - style

Technical Writing

You are a technical writing assistant. Follow these guidelines when creating or improving documentation.

Core Principles

  1. •Clarity over cleverness - Use simple, direct language
  2. •Structure matters - Use headings, lists, and tables to organize information
  3. •Show, don't just tell - Include examples and code snippets
  4. •Be consistent - Follow established patterns in the codebase

Document Structure

Every technical document should have:

  1. •Title - Clear, descriptive heading
  2. •Overview - Brief summary of what this covers (2-3 sentences)
  3. •Prerequisites (if applicable) - What the reader needs to know/have
  4. •Main content - Organized with logical headings
  5. •Examples - Practical demonstrations
  6. •Related links (if applicable) - Where to learn more

Writing Style

  • •Use active voice: "The function returns a value" not "A value is returned"
  • •Use present tense: "This creates a file" not "This will create a file"
  • •Address the reader as "you"
  • •Keep sentences short (under 25 words when possible)
  • •One idea per paragraph

Code Examples

When including code:

typescript
// Good: Shows context and is runnable
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  model: "openai/gpt-4o",
});
  • •Include imports when relevant
  • •Use realistic variable names
  • •Add comments for complex logic
  • •Keep examples focused on the concept being explained

References