markdown-audit

name	markdown-audit
description	Audit and fix the organization of Markdown files in an mdsmith repository. Catches structural problems the built-in rules cannot see yet: manually maintained indexes that should be a `<?catalog?>` directive, directories of similar files with no declared kind, repositories with no `.mdsmith.yml`, duplicated sections that should use `<?include?>`, and kinds that are missing a `path-pattern` or `proto.md` schema. Trigger when the user asks to "audit my markdown organization", "review how my docs are laid out", "should I use a kind for this directory", "this directory has a bunch of similar files", "I keep updating this index by hand", "is my .mdsmith.yml missing anything", or any prompt about Markdown file layout, kinds, schemas, or generated sections. Skip this skill for line-length, heading-style, or readability issues — those are content rules already enforced by `mdsmith check`.
user-invocable	true
argument-hint	[audit | fix]
allowed-tools	Bash(mdsmith:*), Bash(ls:*), Bash(find:*), Bash(grep:*), Bash(git ls-files:*), Bash(git rev-parse:*), Bash(test:*)

Markdown audit

mdsmith ships rules for content (line length, heading hygiene, readability) and rules for structure (kinds, schemas, catalogs, includes). Content rules light up out of the box. Structure rules only fire once somebody has declared the structure. This skill audits a repository for missing structure — the patterns mdsmith would enforce if they were wired up.

The goal is not to relint what mdsmith check already lints. The goal is to surface the work that would let mdsmith check lint more.

When to run this skill

Run on any repository that uses mdsmith, or could plausibly start using it.

• A repo with no .mdsmith.yml. The audit proposes an initial config plus the kinds that fit the current layout.
• A repo with a .mdsmith.yml that has grown organically. The audit catches new directories that drifted past existing kinds, indexes somebody forgot to convert, and includes that never got wired up.

Skip a repo that is not using mdsmith and has no plans to. There is nothing to surface.

Modes

Pass the mode as the skill argument.

• audit (default). Read-only. Walks the checks below and prints a findings report grouped by severity. Applies nothing.
• fix. Runs the audit, then proposes a concrete patch per finding and waits for confirmation before applying.

Default to audit when no argument is given. Fix mode is opt-in because some fixes edit .mdsmith.yml or move files. The user sees the report first.

Workflow

1. Locate the repository root

git rev-parse --show-toplevel

Run every subsequent command from the printed path. Without git, use the current directory.

2. Detect the mdsmith CLI

Try, in order:

mdsmith version

go run ./cmd/mdsmith version

If only the second succeeds, the user is inside the mdsmith source tree. Substitute go run ./cmd/mdsmith for mdsmith in every command below.

3. Walk the checks

Load the rule-backed patterns once at the start, using the CLI detected in step 2:

mdsmith help patterns -f json

Each record is {id, name, signal, fix, for-diagnostic} for one of the five built-in rules that declare a maintainability pattern. Do not hard-code these signals or fixes; reading them here keeps the audit in sync as rules gain or change patterns.

Read patterns.md for the three config-level checks. It carries their signal, heuristic, false positives, severity, and fix recipe. The project skill ships it as a sibling file; the marketplace plugin appends the same content to this SKILL.md under the Detection patterns heading at the end.

Run all eight checks (see ## Checks) in order.

For each <?directive?> fix, read the rule's pattern/bad/ and pattern/good/ folders. They hold the canonical before/after pair. The list below is generated from every rule whose front matter declares nature: directive, so it stays in sync with the rule catalog automatically:

• internal/rules/MDS019-catalog/pattern/ (catalog)
• internal/rules/MDS021-include/pattern/ (include)
• internal/rules/MDS038-toc/pattern/ (toc)
• internal/rules/MDS039-build/pattern/ (build)

Do not paraphrase directive syntax from memory. The integration test TestDirectiveRulesHaveExamples enforces that each pattern folder pair is present.

Do not run mdsmith check . from this skill. That is the content-lint surface and runs separately.

4. Emit findings

Group findings by severity (see ## Severity). Print all three buckets even when empty — an empty bucket is signal that the check ran.

Audit mode stops here. Fix mode continues to step 5.

5. Fix loop (fix mode only)

For each finding in severity order:

1. Print the proposed patch (diff or YAML snippet).
2. Ask the user to confirm.
3. Apply the patch.
4. Re-run the same check on the same path to confirm the finding is cleared.

After every .mdsmith.yml edit, run mdsmith check . once to surface any rule-level regression the new config exposes. On a clean pass, move on. Otherwise roll back the last edit and ask the user.

The audit only adds structure. It does not retune rules the user has already chosen.

Checks

The audit runs eight checks from two sources.

Config-level checks

No built-in rule backs these three. patterns.md (see step 3) carries the full signal, heuristic, false positives, severity, and fix recipe.

1. No .mdsmith.yml — the repo has no config; propose mdsmith init.
2. Similar files, no kind — a directory of three or more .md files with shared front matter and no kind-assignment: entry.
3. Kind without path-pattern — a kind whose files share a naming shape, but the body declares no path-pattern:.

Rule-backed checks

Five built-in rules each declare a maintainability pattern. mdsmith help patterns (step 3) supplies the signal and fix wording for each; treat that output as the source of truth. The list below only maps each rule to its check — new rule-backed patterns show up in the command output automatically.

• catalog (MDS019) — a hand-maintained index of sibling files that should be a <?catalog?> directive.
• required-structure (MDS020) — a kind whose files share a shape but declare no required-structure.schema:.
• include (MDS021) — near-duplicate sections that drift across files and should use <?include?>.
• directory-structure (MDS033) — a .md file outside an allowed directory.
• duplicated-content (MDS037) — repeated paragraphs or sections with the same content.

Severity

The rubric below maps every finding to one of three buckets.

• blocker — the repo silently breaks something an agent or reader depends on. Examples: no .mdsmith.yml in a repo with many .md files; a kind declared but with no matching glob, so no file ever resolves to it.
• tax — works today; costs maintainer attention on every edit. Examples: a hand-maintained index; a duplicated section; a misplaced file.
• nice-to-have — cosmetic or aspirational. Examples: a kind missing path-pattern:; a kind missing a proto schema.

Reporting format

Audit mode emits one Markdown report.

## Audit YYYY-MM-DD

### Blockers
- `path`: pattern — fix sketch.

### Tax
- `path`: pattern — fix sketch.

### Nice-to-have
- `path`: pattern — fix sketch.

Summary: N blockers, N tax, N nice-to-have.

Keep the report tight. Skip the full diff in audit mode — the diff belongs in fix mode where the user is about to approve it.

In fix mode, after each applied fix append one line to the report: applied → path.

Notes

• Detection heuristics here are deliberately loose. False positives are cheaper than missed findings because the user reviews the report before any fix runs.
• When the user pushes back on a finding ("that is intentional"), do not add an ignore: entry for an audit-only pattern. These checks are not enforced by mdsmith check, so silently skipping the path next run is enough. Only add to ignore: when a real rule would otherwise fail.
• This skill ships in two places. The project copy at .claude/skills/markdown-audit/ is the canonical source for both the SKILL body and patterns.md. The marketplace plugin mdsmith-audit mirrors the SKILL body and appends patterns.md via <?include?>, so end users get the same workflow and config-level recipes in a single file. Edit the canonical SKILL.md or patterns.md and run mdsmith fix to regenerate the plugin SKILL.md.

Detection patterns

These three checks have no backing rule, so their signal and fix live here rather than in a rule README. Each section covers one numbered config-level check from the sibling SKILL.md workflow: the signal, the heuristic, false positives to skip, the severity bucket, and the fix recipe.

The other five checks live elsewhere. A built-in rule backs each one. Load its signal and fix from mdsmith help patterns. SKILL.md step 3 has the call.

Check 1 — No .mdsmith.yml

Signal: .mdsmith.yml does not exist at the repo root (test -f .mdsmith.yml).

False positives: a repo with one or two top-level Markdown files and nothing else. Skip with a one-line note.

Severity: blocker when the repo has five or more .md files. Nice-to-have otherwise.

Fix: run mdsmith init to create a default config. Then walk the remaining audit checks to populate kinds, overrides, and assignments.

Check 2 — Similar files, no kind

Signal: a directory holds three or more .md files with a similar front matter shape. The files share the same required keys. No kind-assignment: entry covers the directory.

Heuristic: list directories with three or more .md files (git ls-files '*.md' | xargs -n1 dirname | sort | uniq -c). For each candidate, sample every file's front matter. The directory is a kind candidate when 70% of files share the same key set, and no glob in .mdsmith.yml already covers it.

False positives:

• A directory of one-off Markdown without shared front matter (research spikes, ad-hoc notes).
• A directory already covered by a glob in kind-assignment:, even when the kind body is empty. The assignment alone counts.
• Bad fixtures inside internal/rules/*/bad/, intentionally malformed and under ignore:.

Severity: tax. Drop to nice-to-have when the shared shape is small.

Fix: add an entry to kinds: plus a matching kind-assignment: glob.

kinds:
  runbook:
    rules:
      max-file-length:
        max: 400

kind-assignment:
  - glob: ["runbooks/*.md"]
    kinds: [runbook]

Start with the settings the files actually share right now. Do not over-engineer. After applying, run mdsmith kinds resolve runbooks/example.md to confirm the file picks up the new kind.

Check 3 — Kind without path-pattern

Signal: a declared kind whose files share an obvious naming convention, but the kind body has no path-pattern:.

Heuristic: read kinds: and kind-assignment: from .mdsmith.yml. For each kind, walk the files that resolve to it. The kind is a candidate when 80% of those files share a regex-shaped filename. Examples: \d+_[a-z-]+\.md, RFC-\d{4}\.md.

False positives: a kind with intentionally heterogeneous membership — a "doc" kind covering README, index, and topic pages qualifies.

Severity: nice-to-have.

Fix: add path-pattern: to the kind body.

kinds:
  plan:
    path-pattern: "plan/[0-9][0-9]*_*.md"

Glob syntax has no "exactly digits" class, so the pattern is an approximation. For tighter constraints, combine path-pattern: with a <?require filename:?> directive on the kind's schema. Re-run mdsmith check . to confirm no existing file fails the new pattern.