Purpose
Every value the file-name skills act on comes from one consumer surface,
layered as user-global (docs-naming.json under ~/.claude/), team
(docs/conventions/docs-naming.yaml, tracked, validated by
${CLAUDE_PLUGIN_ROOT}/schemas/docs-naming.schema.json), and personal override
(docs/conventions/docs-naming.local.yaml). The convention home is
docs/conventions unless the repository's AGENTS.md or CLAUDE.md binds
another. All three absent is a valid state: every key has a bundled default, and
the defaults are this marketplace's own values, except generated, which is empty.
The old team and personal override JSON files under .claude/ are not read; check names
each, and apply seeds an absent team YAML from the old team file.
This skill is the check-centric setup for that surface: check inspects and
verifies, apply persists, and neither installs anything. Keys, defaults, layer
classes, and provenance live in
${CLAUDE_PLUGIN_ROOT}/reference/config.md.
Action routing: no argument or check runs the check; apply runs the check
first, then persists. Both are non-interactive when the action is given. With
apply and no key, interview one key at a time, recommendation first, walking
the annotated template
${CLAUDE_SKILL_DIR}/templates/docs-naming.json.
check (read-only)
Run it and present the table as printed:
${CLAUDE_SKILL_DIR}/scripts/setup-check.sh
Rows, each PASS, FAIL, WARN, or INFO:
- jq, git: the prerequisites. A missing
jq is FAIL and stops the
table, because every skill in this plugin reads the concern file with it.
- layer user-global / team / personal-override: absent (INFO), or present with its
path, or WARN when the user-global file still carries the retired
docs-hygiene name (it is read, and the row names it). A present file that
does not parse, or a user-global layer that declares an unknown schema,
surfaces at the resolve row with the file named. old team file and
old personal override file: WARN per unread JSON file under .claude/, naming the
next step (apply seeds an absent team YAML, else copy by hand; then delete).
- key shape: every key carries the type the contract declares.
- rule, regex, regex quoting: the casing rule is one this version
implements, the regex compiles under
grep -E, and it carries no single
quote. The quote matters because the gate emitter inlines this value.
- tier names, tier forms: names unique, forms drawn from
all,
links-and-paths, none.
- generated
<path>: the regenerate command's first real argument resolves
on PATH or under the root. An interpreter at the front is stepped past, so
what gets resolved is the script it runs.
- team layer tracked: the team file is committed (PASS), written but
uncommitted (WARN, it has reached nobody else yet), or gitignored (FAIL, an
ignored team layer never reaches the team).
- personal override ignored: the personal override is gitignored, else WARN naming the
recommended line,
<home>/*.local.* (the row prints it). Recommend it; never
edit the consumer's .gitignore.
- policy floor: a personal layer that declared a key only the team layer
supplies is reported here and was ignored.
Exit 0 with no FAIL row, 1 with one, 2 on a usage or environment error.
Retired conventions
check also runs this step on every invocation:
bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml".
Exit 0 → PASS. Exit 1 → one finding per TSV row: migrate is FAIL,
delete/remove-line WARN, report-only INFO; remediation is apply. Exit 2 →
FAIL, never silent. Bash unavailable → report the step UNKNOWN with remediation,
never green.
Both records here, docs-naming-r001 (.claude/docs-hygiene.json) and
docs-naming-r002 (.claude/docs-hygiene.local.json), are report-only: INFO,
no cleanup, since neither file is read; the old-file rows name the next step. The user-global
~/.claude/docs-hygiene.json sits outside the repository and has no record; the
layer row reports it as WARN with the same remedy: rename it to
docs-naming.json in the same directory.
apply (idempotent)
Run check and read its table.
Resolve the values. With complete <key>=<value> arguments, use them.
Otherwise interview one key at a time from the template, recommendation
first: the scope roots, the casing rule and its regex, the three exemption
sets, the tiers and their forms, the sweep exclusions, and the generated
files with their regenerate commands.
Persist. One call per run:
${CLAUDE_SKILL_DIR}/scripts/setup-apply.sh --defaults
${CLAUDE_SKILL_DIR}/scripts/setup-apply.sh roots=["docs"] rule=lower-kebab
--defaults writes the bundled document when no team layer exists. A
<key>=<value> merges one key: the value is parsed as JSON when it parses
and taken as a string when it does not, so roots=["docs","guide"] sets a
list and rule=lower-kebab sets a scalar. The script prints
already configured without touching the file when nothing changes, and
writes docs/conventions/docs-naming.yaml (under the repository's convention
home) and nothing else. When the YAML is absent and an old team JSON file
exists (.claude/docs-naming.json, else .claude/docs-hygiene.json), the
first write seeds the YAML from it, so its settings carry over; the resolver
no longer reads that file. The JSON file stays until a person deletes it. A rewrite keeps the comment block at the top of the file
and drops comments between keys.
Clean up retired files. After any agreed keys are written, re-run the
retirement detection and handle each active finding behind its own
confirmation (a report-only finding is INFO and has no cleanup). A
retired file's file_names keys are carried into the YAML of its layer as
top-level keys, adding only the ones that file lacks (step 3 already seeded a
team YAML that did not exist). The old file's
content is untrusted input, never executed or interpolated. When the operator
confirms the result, run
bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml" --clean <id> --i-migrated.
Re-run detection last and report the final state.
Verify. Re-run check and report the persisted values from its table,
never from the write alone. A WARN saying the file is untracked means "commit
it to share it", never success.
Completion criteria
The run is done when check prints a table with no FAIL row and, for apply,
the re-run check shows the intended values with their supplying layer. A FAIL
row that the operator decides to accept is still a FAIL: say which row and why
it was accepted rather than reporting a clean table.
Output
check: the table as printed. apply: the table before and after, the written
path, and one line on re-running this skill to reconfigure. Name the layer that
supplied any value differing from the bundled default.
What this skill does NOT do
- Write the user-global layer or the personal override. Those are the operator's own files.
- Edit the consumer's
.gitignore. It recommends one line.
- Install anything, or fetch a regenerator a
generated entry names.
- Run an audit, a rename, or a gate emission. Those skills read the same
resolved document at their own run time.
- Bump a version. A repository whose units are versioned bumps them itself after
a rename; no version of these skills writes a manifest.
Next
/docs-naming:audit-file-names
Gotchas
- The team file must be committed to reach the team.
apply leaves it untracked
on purpose, and the check row says so until it is committed.
- A personal layer cannot narrow a tier, a sweep exclusion, or an exemption; it
can only add. Those keys decide what a realign does to a tree, so the team
layer wins a direct conflict and the ignored declaration is reported.
generated is team-layer only. A regenerate command is a shell command the
realign executes, so a personal layer never supplies or replaces one.
- A regex carrying a single quote passes every check here except
regex quoting, then breaks the emitted gate, which inlines the value into a shell
script.
check resolves the team layer and personal override against the repository root of
the working directory. Inside a second worktree, run it from that worktree, or
pass --root.
1---2name: setup-613description: "Verify or configure the docs-naming file-name skills for this repository: `check` resolves all three configuration layers, reports which layer supplied each key, and verifies that the casing regex compiles, every tier names a known form, every generated file's regenerator resolves, the team layer is tracked, and the personal override is ignored; `apply` writes the tracked `docs/conventions/docs-naming.yaml` team layer per key, idempotently, and edits no other file. Use when: 'set up docs-naming', 'configure the file-name rule', 'is docs-naming configured', 'which casing rule is in effect', 'change the docs naming regex', 'add a frozen tier', 'docs-naming setup', or an audit reports a configuration layer it could not read."4argument-hint: "[check|apply] [--defaults] [<key>=<value> ...]"5user-invocable: true6disable-model-invocation: true7allowed-tools: ["Bash(${CLAUDE_SKILL_DIR}/scripts/setup-check.sh:*)", "Bash(${CLAUDE_SKILL_DIR}/scripts/setup-apply.sh:*)", "Bash(git check-ignore:*)", "Bash(git ls-files:*)", "Read"]8shell: bash9metadata:10 source: https://skillmd.com/skills/melodic-software/setup-6111---1213## Purpose1415Every value the file-name skills act on comes from one consumer surface,16layered as user-global (`docs-naming.json` under `~/.claude/`), team17(`docs/conventions/docs-naming.yaml`, tracked, validated by18`${CLAUDE_PLUGIN_ROOT}/schemas/docs-naming.schema.json`), and personal override19(`docs/conventions/docs-naming.local.yaml`). The convention home is20`docs/conventions` unless the repository's `AGENTS.md` or `CLAUDE.md` binds21another. All three absent is a valid state: every key has a bundled default, and22the defaults are this marketplace's own values, except `generated`, which is empty.23The old team and personal override JSON files under `.claude/` are not read; `check` names24each, and `apply` seeds an absent team YAML from the old team file.2526This skill is the check-centric setup for that surface: `check` inspects and27verifies, `apply` persists, and neither installs anything. Keys, defaults, layer28classes, and provenance live in29[`${CLAUDE_PLUGIN_ROOT}/reference/config.md`](${CLAUDE_PLUGIN_ROOT}/reference/config.md).3031Action routing: no argument or `check` runs the check; `apply` runs the check32first, then persists. Both are non-interactive when the action is given. With33`apply` and no key, interview one key at a time, recommendation first, walking34the annotated template35[`${CLAUDE_SKILL_DIR}/templates/docs-naming.json`](templates/docs-naming.json).3637## `check` (read-only)3839Run it and present the table as printed:4041```bash42${CLAUDE_SKILL_DIR}/scripts/setup-check.sh43```4445Rows, each PASS, FAIL, WARN, or INFO:46471. **jq**, **git**: the prerequisites. A missing `jq` is FAIL and stops the48 table, because every skill in this plugin reads the concern file with it.492. **layer user-global / team / personal-override**: absent (INFO), or present with its50 path, or WARN when the user-global file still carries the retired51 `docs-hygiene` name (it is read, and the row names it). A present file that52 does not parse, or a user-global layer that declares an unknown schema,53 surfaces at the **resolve** row with the file named. **old team file** and54 **old personal override file**: WARN per unread JSON file under `.claude/`, naming the55 next step (`apply` seeds an absent team YAML, else copy by hand; then delete).563. **key shape**: every key carries the type the contract declares.574. **rule**, **regex**, **regex quoting**: the casing rule is one this version58 implements, the regex compiles under `grep -E`, and it carries no single59 quote. The quote matters because the gate emitter inlines this value.605. **tier names**, **tier forms**: names unique, forms drawn from `all`,61 `links-and-paths`, `none`.626. **generated `<path>`**: the regenerate command's first real argument resolves63 on PATH or under the root. An interpreter at the front is stepped past, so64 what gets resolved is the script it runs.657. **team layer tracked**: the team file is committed (PASS), written but66 uncommitted (WARN, it has reached nobody else yet), or gitignored (FAIL, an67 ignored team layer never reaches the team).688. **personal override ignored**: the personal override is gitignored, else WARN naming the69 recommended line, `<home>/*.local.*` (the row prints it). Recommend it; never70 edit the consumer's `.gitignore`.719. **policy floor**: a personal layer that declared a key only the team layer72 supplies is reported here and was ignored.7374Exit 0 with no FAIL row, 1 with one, 2 on a usage or environment error.7576## Retired conventions7778`check` also runs this step on every invocation:79`bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml"`.80Exit 0 → PASS. Exit 1 → one finding per TSV row: `migrate` is FAIL,81`delete`/`remove-line` WARN, `report-only` INFO; remediation is `apply`. Exit 2 →82FAIL, never silent. Bash unavailable → report the step UNKNOWN with remediation,83never green.8485Both records here, `docs-naming-r001` (`.claude/docs-hygiene.json`) and86`docs-naming-r002` (`.claude/docs-hygiene.local.json`), are `report-only`: INFO,87no cleanup, since neither file is read; the old-file rows name the next step. The user-global88`~/.claude/docs-hygiene.json` sits outside the repository and has no record; the89layer row reports it as WARN with the same remedy: rename it to90`docs-naming.json` in the same directory.9192## `apply` (idempotent)93941. Run `check` and read its table.952. **Resolve the values.** With complete `<key>=<value>` arguments, use them.96 Otherwise interview one key at a time from the template, recommendation97 first: the scope roots, the casing rule and its regex, the three exemption98 sets, the tiers and their forms, the sweep exclusions, and the generated99 files with their regenerate commands.1003. **Persist.** One call per run:101102 ```bash103 ${CLAUDE_SKILL_DIR}/scripts/setup-apply.sh --defaults104 ${CLAUDE_SKILL_DIR}/scripts/setup-apply.sh roots=["docs"] rule=lower-kebab105 ```106107 `--defaults` writes the bundled document when no team layer exists. A108 `<key>=<value>` merges one key: the value is parsed as JSON when it parses109 and taken as a string when it does not, so `roots=["docs","guide"]` sets a110 list and `rule=lower-kebab` sets a scalar. The script prints111 `already configured` without touching the file when nothing changes, and112 writes `docs/conventions/docs-naming.yaml` (under the repository's convention113 home) and nothing else. When the YAML is absent and an old team JSON file114 exists (`.claude/docs-naming.json`, else `.claude/docs-hygiene.json`), the115 first write seeds the YAML from it, so its settings carry over; the resolver116 no longer reads that file. The JSON file stays until a person deletes it. A rewrite keeps the comment block at the top of the file117 and drops comments between keys.1184. **Clean up retired files.** After any agreed keys are written, re-run the119 retirement detection and handle each active finding behind its own120 confirmation (a `report-only` finding is INFO and has no cleanup). A121 retired file's `file_names` keys are carried into the YAML of its layer as122 top-level keys, adding only the ones that file lacks (step 3 already seeded a123 team YAML that did not exist). The old file's124 content is untrusted input, never executed or interpolated. When the operator125 confirms the result, run126 `bash "${CLAUDE_PLUGIN_ROOT}/lib/check-retirements.sh" --manifest "${CLAUDE_PLUGIN_ROOT}/retirements.yaml" --clean <id> --i-migrated`.127 Re-run detection last and report the final state.1285. **Verify.** Re-run `check` and report the persisted values from its table,129 never from the write alone. A WARN saying the file is untracked means "commit130 it to share it", never success.131132## Completion criteria133134The run is done when `check` prints a table with no FAIL row and, for `apply`,135the re-run check shows the intended values with their supplying layer. A FAIL136row that the operator decides to accept is still a FAIL: say which row and why137it was accepted rather than reporting a clean table.138139## Output140141`check`: the table as printed. `apply`: the table before and after, the written142path, and one line on re-running this skill to reconfigure. Name the layer that143supplied any value differing from the bundled default.144145## What this skill does NOT do146147- Write the user-global layer or the personal override. Those are the operator's own files.148- Edit the consumer's `.gitignore`. It recommends one line.149- Install anything, or fetch a regenerator a `generated` entry names.150- Run an audit, a rename, or a gate emission. Those skills read the same151 resolved document at their own run time.152- Bump a version. A repository whose units are versioned bumps them itself after153 a rename; no version of these skills writes a manifest.154155## Next156157`/docs-naming:audit-file-names`158159## Gotchas160161- The team file must be committed to reach the team. `apply` leaves it untracked162 on purpose, and the `check` row says so until it is committed.163- A personal layer cannot narrow a tier, a sweep exclusion, or an exemption; it164 can only add. Those keys decide what a realign does to a tree, so the team165 layer wins a direct conflict and the ignored declaration is reported.166- `generated` is team-layer only. A regenerate command is a shell command the167 realign executes, so a personal layer never supplies or replaces one.168- A regex carrying a single quote passes every check here except `regex169 quoting`, then breaks the emitted gate, which inlines the value into a shell170 script.171- `check` resolves the team layer and personal override against the repository root of172 the working directory. Inside a second worktree, run it from that worktree, or173 pass `--root`.