Purpose
Setup for /docs-hygiene:compress. It has two parts:
- The one external prerequisite,
markdownlint-cli2, whichcompressruns as its post-edit ship gate and stops without.checkresolves the binary, runs it, and reports the remediation. Installing is the operator's. - The
compress_articlessetting, which decides whethercompressmay removea,anandthe. It has two homes: the plugin's nativeuserConfigoption, which Claude Code prompts for and stores, and which this skill reads but never writes; and one tracked consumer file,docs/conventions/docs-hygiene.yaml, the repository layer (keys, values and layers:${CLAUDE_PLUGIN_ROOT}/reference/config.md; schema:${CLAUDE_PLUGIN_ROOT}/schemas/docs-hygiene.schema.json). A value set in the file wins over the user'suserConfigvalue.
Action routing: no argument or check runs the check; apply runs the check, then writes the
repository file and nothing else. With complete <key>=<value> arguments nothing asks a question;
the one confirmation is a diff to an existing file (apply step 4).
Official contract for userConfig: https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration.
check (read-only)
Report a PASS/INFO/WARN/FAIL table with one remediation line per FAIL. Modify nothing.
- Resolve
markdownlint-cli2the waycompressdoes: firstcommand -v markdownlint-cli2(onPATH), thennode_modules/.bin/markdownlint-cli2under the repository root. Report which one resolved. FAIL when neither does. - Run it. Execute the resolved binary with
--helpand no other argument. The probe must read no markdownlint configuration and touch no file, so never pass--versionor any argument but--help. Judge the output, never the exit code: PASS when the first line of stdout is the tool's version banner, namingmarkdownlint-cli2and its version. A shim can resolve and still be broken (a missing Node interpreter, a dangling target), so resolution without the banner is FAIL, with the stderr text in the remediation line.- Pointer: when the probe's argument handling, help output or exit code is in question,
fetch markdownlint-cli2: Command Line
and the argument parsing in
markdownlint-cli2.mjsat v0.24.0 live; this decision was derived for markdownlint-cli2 v0.12.0 and later. As of: 2026-11-04. Recheck trigger: a markdownlint-cli2 release changes its argument parsing, its help banner or the exit code of--help.
- Pointer: when the probe's argument handling, help output or exit code is in question,
fetch markdownlint-cli2: Command Line
and the argument parsing in
- Repository settings. Run
"${CLAUDE_SKILL_DIR}/scripts/setup-apply.mjs" --checkfrom the project root and report each line it prints under its own INFO, PASS or WARN prefix: INFO whendocs/conventions/docs-hygiene.yamlis absent, with no other line; otherwise a WARN for each problem in the file (a value outside the key's list, a key set twice, an empty or null value, a map or list where one string belongs, a key the schema does not list, or a line that does not parse), quoting the file, key and value; then one line per schema key:PASS <key>: <value>orPASS <key>: (unset), orWARN <key>: dropped ...when the file's value for that key is invalid or the file does not parse. A key the schema does not list gets its own WARN and leaves the other keys' values in force, the same way/docs-hygiene:compressreads them. An invalid value never stops/docs-hygiene:compress, which names it and drops that layer, so these rows are WARNs.applyfixes only a value that is outside the list, empty or null, and leaves an unknown key's line as written; every other WARN needs a hand edit first. - Effective
compress_articles. Read the rendered${user_config.compress_articles}; a literal unexpanded token means unset. Do not inspect or editsettings.json,settings.local.json, managed settings orpluginConfigs. Resolve ascompressdoes (${CLAUDE_PLUGIN_ROOT}/reference/config.md), highest layer first, and state the value and the layer that supplied it:- Step 3 printed
PASS compress_articles: <value>withkeeporcut: the file's value. - Step 3 printed
WARN compress_articles: dropped: the file layer is dropped, and no valid layer sits above it, so the value iskeep(default). Never use theuserConfigvalue in its place. - Otherwise (no file, or the key unset in it): the
userConfigvalue when it iskeeporcut. Any otheruserConfigvalue is named (userConfig,compress_articles, the value) and dropped, and the value iskeep(default). - Otherwise
keep(default).
- Step 3 printed
Remediation for a markdownlint-cli2 FAIL: install it explicitly, npm install --save-dev markdownlint-cli2 in the repository or a global install, then rerun check. Without it
/docs-hygiene:compress stops at its entry point before touching a file. No other skill in this
plugin needs the binary.
To change the userConfig value, reconfigure through Claude Code's native flow per the
plugin-reconfiguration convention
(https://github.com/melodic-software/claude-code-plugins/blob/main/docs/contracts/plugin-reconfiguration/README.md,
which owns the verified-version record): /plugin configure docs-hygiene@<marketplace>
interactively. Headless, preferred on Claude Code 2.1.285 or later:
claude plugin configure docs-hygiene@<marketplace> --values-stdin < values.json, where
values.json holds {"compress_articles": "<value>"}. Headless fallback, before 2.1.285: rerun
claude plugin install docs-hygiene@<marketplace> -s <scope> --config compress_articles=<value>.
- Never uninstall to reconfigure.
- Scope:
claude plugin configurehas no scope flag, so run it from the project the plugin is installed in. For the rerun, pass the scopeclaude plugin listreports (from the home directory passuser); a rerun at another scope adds an install record there and enables the plugin. - Rendered values are injected at skill load, so rerun
checkin a fresh session after a change and report the observed value, never an unobserved change. - Whichever route ran, read both its exit code and its output before reporting the value saved: the two routes signal a rejected value differently.
- Pointer: when checking how a route reports a rejected value, what the rerun prints, where the value is stored, or what an uninstall deletes, fetch § plugin configure, § plugin install, § Where values are stored and § What an uninstall deletes and keeps live. As of: 2026-11-10. Recheck trigger: one of those sections changes how a route reports a rejection, the rerun's output, where a value is stored, or what an uninstall deletes.
To set the value for the whole repository instead, use apply.
apply (writes docs/conventions/docs-hygiene.yaml only)
Run
checkand show its table.Resolve the value. With a complete
compress_articles=<value>argument, use it. Otherwise ask, recommendation first:keep, the default, for docs people read;cutonly when the team wants the shortest text and its readers are agents. Never invent a key the schema does not list.Write. One call:
"${CLAUDE_SKILL_DIR}/scripts/setup-apply.mjs" compress_articles=keepPass a key the operator accepts at the plugin default as
--default <key>instead of<key>=<value>, so a later change to that default reaches it;<key>=<value>records the team's choice, which the script never changes. The script also recordswritten_againstandprovenance:, so a file with no record, or one written against another plugin version, shows a diff even when no value changes.The script writes only the keys named on the command line and keeps every other line of an existing file. It validates the existing file first, and over it fixes only a value that is outside the key's list, empty or null. It refuses with one line, exits 1 and leaves the file untouched when a command-line key is outside the schema or given twice, a command-line value is outside the key's list, or the existing file sets a key twice (
key : vcounts askey: v), holds a map or list in any form, holds an empty quoted string, names a key the schema does not list twice or with a map or list, does not parse, or mixes CRLF and LF line endings (a file written with CRLF throughout is updated in place and keeps CRLF). Any other unknown key is named in one warning and its line kept as written. It writes only<git toplevel>/docs/conventions/docs-hygiene.yaml: it resolves a symlinked root first, then refuses a root that is$HOMEor an ancestor of it (wherecompressdoes not read the file), a symlinkeddocs,docs/conventionsor target, a directory that resolves outside the repository, and a target with more than one hard link, and checks the path again before each directory it creates and before the write, which goes to a new temp file beside the target and is renamed over it. A missing file is created. A value already in place printsalready configuredand writes nothing.An existing file that would change exits 3 and prints a unified diff without writing. Show the operator that diff and ask whether to write it. Only on an explicit yes, re-run the same call with
--yes; on anything else, stop with the file unchanged. When the convention-home offer prints below the diff, ask about it too (the next step) before any re-run, since--yeswrites both.The convention-home offer. When the repository's
AGENTS.mdorCLAUDE.mdbinds no convention home, the script prints an offer: with the operator's confirmation it adds a convention-home pointer region to that instruction file (creatingAGENTS.mdwhen neither exists orCLAUDE.mdonly imports it) and the personal override ignore linedocs/conventions/**/*.local.*to.gitignore, the only filesapplywrites outsidedocs/conventions/. It prints the offer at the end of an exit 0 run and below the diff of an exit 3 run, so show the operator stdout on exit 0 too. Ask whether to add the region and the ignore line. Only on an explicit yes, re-run the same call with--yes, which also writes any diff shown with it. On a no, run"${CLAUDE_SKILL_DIR}/scripts/setup-apply.mjs" --declinealone: it records the decline in the instruction file, and the next run does not offer again. To write a shown diff without the region, run--declinefirst, then the same call with--yes. When the instruction file or.gitignoreis a symlink or hard link the script will not write through, it prints a one-line refusal in place of the offer, with the same exit code: show it, and do not re-run with--yes, which that refusal stops with exit 1. A refused instruction file refuses--declinetoo, so the operator fixes the link or adds the region by hand.Verify. Re-run
checkand report the value from its table, not from the write. Thengit check-ignore -v docs/conventions/docs-hygiene.yamlreports no match (a match means the team never receives the file: say so, and leave.gitignoreto the operator), andgit ls-files --error-unmatch docs/conventions/docs-hygiene.yamlexits 0. Non-zero right after a fresh write means "written but untracked: commit it to share with the team", never success.
Next
/docs-hygiene:compress
Gotchas
- A missing binary is not a lint failure.
compressnever ships unverified output, so absence stops it;checkis how to see why before that happens. - Never install on the operator's behalf. This skill runs no
npm, nonpx, and no download. applydoes not fix a missing binary. It writes only the settings file.
What this skill does NOT do
- Run
markdownlint-cli2over repository files. The only execution is the--helpliveness probe. - Check the consuming repository's markdownlint configuration. Which rules a repository adopts is its own decision.
- Write the plugin cache, Claude Code user settings, or
pluginConfigs.