Skip to content

vale-cli/agent-tools / skills/doctor

doctor

Verified

Check a Vale setup end to end and say what is working, what is broken, and the command that fixes each thing. Use when the user says "vale isn't working", "why is the hook silent", "is vale set up right", "vale reports nothing", or after cloning a repository that uses Vale.

Check a Vale setup

When to use this

Something about Vale is not behaving, or someone wants to know a setup is sound before relying on it. Most Vale problems are silent: a config that lints nothing, styles that were never synced, a hook with nothing to say. This skill turns silence into a checklist.

It diagnoses. It does not fix anything without being asked.

Workflow

1. Run the check from the repository root:

sh ${CLAUDE_SKILL_DIR}/scripts/doctor.sh
sh ${CLAUDE_SKILL_DIR}/scripts/doctor.sh docs/guide/install.md   # try a particular file

${CLAUDE_SKILL_DIR} is the directory this file is in; if it reaches you as literal text, use that path. The script only reads.

ok    vale 3.27.0 at /usr/local/bin/vale
ok    configuration loads: .vale.ini
FAIL  styles named in the configuration are not on disk: Microsoft
      -> vale sync
ok    vocabulary Docs: 12 terms accepted
warn  a run on README.md reports nothing
      -> if that is a surprise, check that a [section] glob in the configuration matches this file

It checks, in order: the binary, whether the configuration loads, whether every style it names is on disk, the vocabulary and whether git tracks it, whether a real run on a real file works, whether a user-level configuration changes the result, the markup parsers AsciiDoc and reStructuredText need, and the hooks.

2. Report it as it is. Lead with the FAIL lines and their fixes, then the warnings, then one line saying the rest is fine. Do not turn a warning into a problem or a clean result into a longer one.

3. Fix only what the user asks for, and only what the script named. Each -> line is the fix. vale sync is safe to run. Anything that edits .vale.ini or .gitignore is the team's file: say what you would change.

What the silent cases usually are

  • "The hook does nothing." It reports errors only, by default, and only on files the assistant edits. A file with warnings and no errors is silence by design. The level is a plugin setting.
  • "Vale reports nothing on this file." No [section] glob matches it. vale ls-config shows the sections; a glob is matched against the path from the config's directory.
  • "It worked yesterday." StylesPath is not in git, and a fresh clone or a cleaned checkout has no styles until vale sync runs.
  • "It passes locally and fails in CI", or the reverse. A user-level config on one machine is being merged in. The check names the file and gives the alert count with and without it; vale ls-dirs shows where Vale looks.
  • "Every word is a spelling error." A file in another language read as English, or a dictionary file that is not a dictionary. See setup and vocab.

Do not

  • Do not "fix" a silent hook by widening its level unless the user wants warnings on every edit.
  • Do not edit the configuration to make a check pass. A missing style is synced, not removed from BasedOnStyles.
  • Do not report a setup as healthy from the first three lines. The run on a real file is the check that matters.
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