Skip to content

erode-app/erode / .agents/skills/docs-voice

docs-voice

Verified

Enforce the project's documentation voice when writing or reviewing public-facing content. Triggers on edits to doc files (packages/web/src/content/docs/**/*.md) and README.md. Catches LLM prose patterns, marketing language, and messaging drift.

FileKindSize
SKILL.mdskill md8.7 KB
---
name: docs-voice
description: >-
  Enforce the project's documentation voice when writing or reviewing public-facing
  content. Triggers on edits to doc files (packages/web/src/content/docs/**/*.md) and
  README.md. Catches LLM prose patterns, marketing language, and messaging drift.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# Documentation Voice

Keep Erode's public-facing docs in a consistent, honest voice. Every doc should
read like it was written by the same person who wrote `why-it-matters.md`.

## North Star

Before writing or reviewing any doc, read the voice calibration source:

```
packages/web/src/content/docs/docs/why-it-matters.md
```

That page sets the tone, the messaging, and the level of honesty. Match it.

## When to Activate

Trigger proactively when any of these files are created or edited (staged,
unstaged, or in recent commits):

- `packages/web/src/content/docs/**/*.md`
- `README.md`

When detected, say:

> Doc files changed. Want me to run docs-voice to check the writing?

## Core Messaging

These are the project's core claims. New docs should reinforce them, not
contradict or dilute them.

1. **The core story.** Architecture models rot because updating them is
   disconnected from coding. AI makes this worse by shipping structural changes
   faster than humans can review. Erode closes the loop by checking PRs
   automatically.

2. **Visibility, not enforcement.** Erode exists to make drift visible. It does
   not enforce rules or block merges.

3. **Violations are not necessarily problems.** Software evolves. New
   dependencies are natural. What matters is that changes are conscious and
   documented, not accidental.

4. **Thin models win.** The model should be nodes and connections at the system
   level. A thin model that stays true beats a detailed one nobody trusts.

5. **Connect features to the core problem.** When describing what Erode does,
   tie it back to the problem (drift goes unnoticed) and the solution (make it
   visible during code review).

## Voice Rules

### 1. Short paragraphs

Two to three sentences. One idea per paragraph. If a paragraph needs a fourth
sentence, split it.

### 2. Active voice

The subject does the action. "Erode checks every PR" not "Every PR is checked
by Erode."

### 3. Concrete over abstract

Name the thing. "Erode flags undeclared dependencies in PRs" not "The tool
provides architectural governance capabilities."

### 4. Problem first, then solution

State the pain before the fix. The reader needs to feel the problem before they
care about the answer.

### 5. No hedging

Say what it does. "Erode catches drift" not "Erode can help you potentially
identify possible drift scenarios."

### 6. Honest about limitations

If something does not work yet, say so plainly. Do not hide limitations behind
vague language or skip them entirely.

### 7. No marketing language

Banned words and phrases:

- "revolutionary", "game-changing", "cutting-edge", "next-generation"
- "best-in-class", "world-class", "industry-leading"
- "seamless", "seamlessly", "effortless", "effortlessly"
- "supercharge", "turbocharge", "unlock", "unleash"
- "leverage" (use "use"), "utilize" (use "use")
- "robust", "scalable", "enterprise-grade"
- "empower", "transform", "reimagine"
- "comprehensive solution", "holistic approach"

If you catch yourself reaching for these words, describe what the thing actually
does instead.

### 8. Blockquotes for principles only

Use `>` for short, quotable statements that express a core belief or insight.
Not for emphasis, not for callouts, not for tips. Starlight callouts
(`:::note`, `:::tip`) handle those.

## Anti-Patterns to Flag

Each pattern below includes examples. Flag every occurrence.

### Em dashes

Banned entirely. Use commas, periods, semicolons, or parentheses.

- BAD: `Erode checks PRs β€” flagging undeclared dependencies β€” before merge.`
- GOOD: `Erode checks PRs, flagging undeclared dependencies, before merge.`

### Hyperbole

- BAD: `This completely eliminates architecture drift forever.`
- GOOD: `This catches drift when it's introduced.`

### Filler phrases

Remove without replacement. The sentence is stronger without them.

- BAD: `It's worth noting that Erode checks every PR.`
- GOOD: `Erode checks every PR.`
- BAD: `As a matter of fact, the model stays current.`
- GOOD: `The model stays current.`

Other fillers to catch: "It should be noted that", "Needless to say",
"At the end of the day", "In order to" (use "to"), "Due to the fact that"
(use "because"), "At this point in time" (use "now").

### Overqualification

- BAD: `Erode essentially analyzes your PRs to actually find drift.`
- GOOD: `Erode analyzes your PRs to find drift.`

Words to catch: "actually", "essentially", "basically", "really", "very",
"quite", "rather", "somewhat", "just" (when used as filler).

### Artificial enthusiasm

No exclamation marks in body text. Reserve them for nothing.

- BAD: `Erode catches drift automatically!`
- GOOD: `Erode catches drift automatically.`

### "Let's" imperatives

- BAD: `Let's set up your first analysis.`
- GOOD: `Set up your first analysis.`

### Passive voice (when active works)

- BAD: `PRs are analyzed by the tool for architectural violations.`
- GOOD: `The tool analyzes PRs for architectural violations.`

Not all passive voice is wrong. Use judgment. "The model is defined in a
`.c4` file" is fine because the model is the subject.

### Weasel words

- BAD: `Many teams find that architecture drift causes problems.`
- GOOD: `Architecture drift causes problems.`

Words to catch: "many", "most", "some", "often", "generally", "typically"
when used to avoid making a direct statement.

### Emoji

No emoji in docs. Not in headings, not in body text, not in lists.

- BAD: `## Getting Started πŸš€`
- GOOD: `## Getting started`

## Structure Conventions

### Front matter

Every doc page needs YAML front matter with `title` and `description`:

```yaml
---
title: Page Title Here
description: One-sentence summary of what this page covers.
---
```

### Headings

- Start at `##` (Starlight uses `title` from front matter as `h1`)
- Sentence case: "How it works" not "How It Works"
- No trailing punctuation
- No emoji

### Tables

Use tables for structured reference data (env vars, flags, options). Do not use
tables for prose or explanations.

### Code blocks

Always include a language label:

````markdown
```bash
npm run build
```
````

### Callouts

Use Starlight callout syntax for tips, notes, and warnings:

```markdown
:::tip
Short, actionable tip here.
:::

:::note
Context or background the reader might need.
:::

:::caution
Something that could go wrong if ignored.
:::
```

Do not use blockquotes (`>`) for this purpose.

### Internal links

Use relative paths, not absolute URLs:

- GOOD: `[configuration](../guides/configuration.md)`
- BAD: `[configuration](https://erode.dev/docs/guides/configuration)`

### "What's next" sections

Guides should end with a short section pointing to the next logical step:

```markdown
## What's next

- [Configure environment variables](../guides/configuration.md)
- [Set up CI integration](../ci/github-actions.md)
```

## Writing Workflow

1. **Read the north star.** Open `why-it-matters.md` and absorb the tone.
2. **Draft.** Write the content.
3. **Run the checklist.** Go through every item in the review checklist below.
4. **Fix violations.** Rewrite anything that fails.

## Review Checklist

Run this after every draft. Every item is a yes/no check.

### Messaging

- [ ] Content reinforces (or at least does not contradict) the five core
      messaging points above
- [ ] Features are connected to the core problem (drift) and solution
      (visibility)
- [ ] Erode is described as making drift visible, not enforcing or blocking
- [ ] Violations are framed as information, not as errors or failures
- [ ] The model is described as thin (nodes and connections), not exhaustive

### Voice

- [ ] No em dashes anywhere
- [ ] No exclamation marks in body text
- [ ] No banned marketing words
- [ ] No filler phrases
- [ ] No overqualification words used as filler
- [ ] No "Let's" imperatives
- [ ] No weasel words used to avoid direct statements
- [ ] No emoji
- [ ] No passive voice where active voice works
- [ ] Paragraphs are two to three sentences
- [ ] Blockquotes used only for principles

### Structure

- [ ] Front matter has `title` and `description`
- [ ] Headings start at `##` and use sentence case
- [ ] Code blocks have language labels
- [ ] Callouts use Starlight syntax, not blockquotes
- [ ] Internal links use relative paths
- [ ] Tables used only for reference data
- [ ] Guides end with a "What's next" section

### Content

- [ ] No claims that are not supported by what Erode actually does
- [ ] Limitations stated plainly, not hidden or omitted
- [ ] Technical terms used consistently (same word for the same concept)
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product β€” it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product β€” not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial β€” a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK β€” model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER β€” read BEFORE opening the target file; don't skip because it "looks like a one-liner" β€” whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) β€” never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named β€” don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall