vale-cli/agent-tools / skills/write-guide
write-guide
VerifiedWrite 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
vale ls-configresolves andvale synchas run — the rules are read fromStylesPath.- 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
-f | Table written as |
|---|---|
md, mdx | Markdown pipe table |
adoc | AsciiDoc table |
rst | reStructuredText list-table |
org | Org table |
html | HTML <table>, for anything else |
tsv | tab-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.
- 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.
- What blocks a merge — the
errorrules only, each in one plain sentence. This is the section people need most, so it comes first. - Style choices — the decisions teams argue about, in plain words:
headings, contractions, person, voice.
tunehas 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. - 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.
- 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |