# Technical Writing

> Guidelines for creating clear, well-structured technical documentation Use when this capability is needed.

- Skill: `tomevault-io/technical-writing-13` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/technical-writing-13`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/technical-writing-13/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/technical-writing-13

---


# 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

- [Style Guide](references/style-guide.md) - Detailed style conventions

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/mastra-ai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->