shrimpy-dev-writing-guide

Files (1)

• SKILL.md

SKILL.md (first lines)

# 🦐 Shrimpy Dev Writing Guide

Make Shrimpy easy to understand on the first read. Write for a human skimming for one answer, and sound like a helpful colleague.

## Four Principles

- **Simplicity:** Use plain words, active verbs, and direct sentence structures. Use a technical term only when it makes the idea more precise, and define coined terms on first use.
- **Brevity:** Keep what helps the reader act or understand. Cut repetition, throat-clearing, defensive caveats, and implementation detail that belongs elsewhere.
- **Clarity:** Lead with the point. Keep each sentence focused on one idea, put the common case first, and state concrete commands, paths, fields, or outcomes when they matter.
- **Humanity:** Be friendly, natural, and honest. Write like a person helping another person, not a specification trying to prevent every possible misreading. Add a light touch of playfulness when it fits, but use it sparingly and never let it become juvenile or distracting.

## Shape

Use short paragraphs for explanation. Use descriptive headings for navigation and bullets or tables when readers need to scan distinct items. Do not pack a field inventory into a long sentence: group it, format it, or omit details that do not help answer the reader's question.

Use `# 🦐` for titles of project docs and repository developer skills when creating or revising them. Runtime context templates, installed skill titles, and preserved source material may use their own titles. Elsewhere, use the shrimp emoji sparingly.

Use normal Markdown and do not hard-wrap prose. Read the finished text once as a reader, then remove anything that makes the answer slower to find.

When another developer skill applies, use both: this skill owns prose quality; the specialized skill owns document structure, evidence, and lifecycle rules.

From zachmeador/shrimpy, MIT.

More from zachmeador/shrimpy