mdsmith

Write Markdown documentation that picks the right Diátaxis type (tutorial, how-to, reference, background), derives matching title and summary fragments, and passes a global-English and anti-slop polish. Trigger when the user asks to "draft a doc", "write a how-to", "draft a reference", "write a background page", "rewrite this in the house voice", "summary for this page", "title for this page", "polish for non-native readers", "this reads like AI", "remove AI tells / slop", "what type of doc is this", or "polish the README or landing page". Skip this skill for content-rule fixes (line length, heading hygiene, readability) — those are enforced by `mdsmith check`.

Security-review methodology specialized for mdsmith - the Go Markdown linter/formatter and its surfaces (CLI binary, the mdsmith lsp language server, the VS Code extension, the Obsidian plugin, the npm/PyPI/Homebrew/Flatpak distribution wrappers, and the Git merge-driver/pre-merge-commit hooks). Use this skill whenever the user asks for a security review, threat assessment, vulnerability audit, or PR security sign-off on mdsmith or any of its components - even when they name only one surface (e.g. review the VS Code extension, audit the LSP server, check this PR for security problems). Also use when reviewing code that parses untrusted Markdown, resolves the include and catalog path directives, statically lints the build recipe directive, or wires mdsmith into an editor or CI pipeline. Prefer this over a generic code review for anything mdsmith-related: it encodes the project's attack surface and current defenses so reviews stay consistent and accurate.

Build the mdsmith.dev Hugo site, serve it locally, and run the Playwright end-to-end suite or drive it interactively. The same `serve.sh` entrypoint is used by Playwright's webServer, the CI job, and this skill, so the site rendered here is byte-identical to what CI and production render. Trigger when the user asks to "test the site", "run playwright", "drive the install picker", "screenshot the homepage", "check the Windows command swap", or "run the e2e suite".

Push changes, monitor CI, and address review comments until the PR is clean. Run after creating or updating a PR, or when CI fails or reviewers leave comments.

Pick the next plan to start work on. Reads PLAN.md from origin/main, cross-references open PRs and existing branches, reads each non-completed plan's `depends-on:` frontmatter, filters out plans whose dependencies are not yet completed, splits the rest into "structurally important" (other plans depend on them) and "quick wins" (smaller-model plans), presents the top 4, then creates a branch, opens a draft PR, and dispatches an implementation Agent at the model the plan declares. Use when asked to "pick a plan", "start the next plan", "what plan should I work on", "begin a new plan", or "open a draft PR for plan N".

Enqueue a PR into the merge queue after CI is green and reviews are resolved.

Run `mdsmith check` on Markdown files in the current workspace and surface lint diagnostics. Useful without the `mdsmith-lsp` plugin — gives the same findings in a text report. Trigger when the user asks to "check my markdown", "run mdsmith check", "lint these files", or "show lint errors".

Run `mdsmith fix` on Markdown files in the current workspace. Auto-fixes whitespace, headings, code fences, bare URLs, list indentation, table alignment, and generated sections (catalog, include, toc, build) in place, looping until edits stabilize. Trigger when the user asks to "fix my markdown", "run mdsmith fix", "clean up lint", or "regenerate sections".

Inspect how mdsmith resolves file kinds in the current workspace. `resolve` shows the effective kind and merged rule config for one file; `list` enumerates all declared kinds. Trigger when the user asks "what kind is this file", "which rules apply here", "show me the kinds", or "resolve this file's config".

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`.

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`.

Apply SOLID principles and clean architecture to Go and TypeScript codebases. Use when generating or revising a multi-step plan so the plan respects package boundaries; when designing a new package, splitting an existing one, or wiring a new cross-system surface (LSP, CLI, distribution shim, plugin); and when auditing a branch for accumulated boundary violations that should be scheduled as fixes. Trigger phrases include "design a package", "is this clean architecture", "refactor the boundary", "architecture audit", "plan a feature", "check main for arch debt", "review architecture", "solid principles".

Canonical workflow for resolving pull request review threads via the gh CLI — single source of truth that other skills (e.g. pr-fixup) should defer to instead of duplicating. MUST use whenever you need to resolve, fetch, or interact with PR review threads. GitHub MCP CANNOT resolve review threads and CANNOT retrieve thread IDs — do NOT attempt GitHub MCP for anything thread-related. Trigger on "resolve threads", "mark as resolved", "address review comments", "clean up the PR", "which comments are still open", or any reference to PR review feedback.