Skip to content

vale-cli/agent-tools / skills/write-guide

write-guide

Verified

Write a human-readable style guide from a project's Vale configuration — what the rules are, which ones block, the project's vocabulary, and why each choice was made — in Markdown, MDX, AsciiDoc, reStructuredText, Org or HTML. Use when the user says "write up our style guide", "document our vale rules", "what does our config actually enforce", or "generate a style guide for contributors".

Write the style guide the config already implies

When to use this

Vale is set up, and the rules live in .vale.ini and YAML that most writers will never open. The team wants a page a new contributor can read: what we expect, what will block your pull request, what words we use.

This is from-guide in reverse. If the team already has a guide and wants it enforced, use that one.

Prerequisites

  1. vale ls-config resolves and vale sync has run — the rules are read from StylesPath.
  2. You know where the guide should live and in which format. Default to the format the docs are already written in, beside them.

What is fact and what is prose

Two halves, kept apart on purpose.

The facts are read, not recalled. scripts/inventory.sh, beside this file, lists every rule the config turns on, the level it actually runs at after overrides, and the comment the project wrote above each override as its reason:

sh ${CLAUDE_SKILL_DIR}/scripts/inventory.sh           # tab-separated
sh ${CLAUDE_SKILL_DIR}/scripts/inventory.sh -f md     # a table, ready to paste
-fTable written as
md, mdxMarkdown pipe table
adocAsciiDoc table
rstreStructuredText list-table
orgOrg table
htmlHTML <table>, for anything else
tsvtab-separated, for your own use

${CLAUDE_SKILL_DIR} is the directory this file is in; if it reaches you as literal text, use that path. The script needs only a POSIX shell. Use its output for every claim about what is enforced and at what level. Do not describe a rule from memory of the package; packages change, and the project may have switched it off.

The prose is yours to write, from those facts: grouping forty rules into five sections a person can hold in their head, and saying each in a sentence.

Workflow: write

1. Take the inventory, and read the vocabulary: styles/config/vocabularies/<Project>/accept.txt and reject.txt.

2. Write the guide in this order. Short. A guide nobody finishes enforces nothing.

  1. How this works — three or four sentences: Vale checks these as you write and in CI; errors block a merge, warnings are raised in review, suggestions are advice; how to run it locally.
  2. What blocks a merge — the error rules only, each in one plain sentence. This is the section people need most, so it comes first.
  3. Style choices — the decisions teams argue about, in plain words: headings, contractions, person, voice. tune has the list. Include the ones switched off, with the reason from the config: "We write 'we' in tutorials" is as much house style as any rule.
  4. Words — the product names and their casing, the terms we do not use, and any "write X, not Y" pairs from the project's own rules.
  5. Rule reference — the table from inventory.sh, pasted between markers so it can be regenerated without touching the prose:
<!-- vale-inventory:start -->
…table…
<!-- vale-inventory:end -->

Use the comment syntax of the guide's format for the markers: // lines in AsciiDoc, .. in reStructuredText, # in Org, {/* */} in MDX.

Workflow: check

3. Give examples that are true. For the project's own rules, the test cases are the examples: an input that is flagged is the "don't", one with want: '' is the "do". For a package rule, write a pair and check it:

printf '%s\n' 'Simply run the installer.' | vale --ext=.md --no-exit --output=line

An example the linter does not actually flag teaches the wrong rule.

4. Put every "don't" in a code span or code block. Vale skips code, so the guide can quote what it bans without failing its own rules.

5. Lint the guide with the config it describes.

vale --output=line <guide>

It should pass at error, and anything else it reports is worth reading: a style guide that breaks its own rules is noticed.

6. Report where the guide is, how many rules it covers at each level, and anything in the config with no stated reason — those are the gaps for the team to fill in, not for you to guess.

Keeping it current

The reference table is the part that goes stale. To refresh it, re-run inventory.sh and replace what is between the markers; leave the prose alone unless a rule it describes changed level or was switched off. Say in the guide which commit the table was generated from.

Do not

  • Do not state a reason the config does not give. "Switched off — no reason recorded" is accurate. An invented rationale will be quoted back to the team as policy.
  • Do not document rules that are off as if they were on, or leave out the ones that block.
  • Do not paste forty rule names as the guide. The table is the appendix; the guide is the five sections above it.
  • Do not copy a package's guidance wholesale. Link to it. The value of this page is what the project chose, not what Microsoft wrote.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall