Add markdownlint analysis for local dev and CI (#534)

* Add markdownlint analysis for local dev and CI

- Add .markdownlint.jsonc with rule configuration
- Add .markdownlint-cli2.jsonc with ignore patterns
- Add package.json with markdownlint-cli2 and lint scripts
- Add GitHub Actions workflow running on PRs touching *.md files
- Add VS Code extension recommendation for vscode-markdownlint

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Address review comments: use markdownlint-cli2-action, merge configs, lint only changed files

- Replace manual Node.js + npm setup with DavidAnson/markdownlint-cli2-action (pinned to SHA)
- Use tj-actions/changed-files to lint only PR-changed markdown files
- Merge .markdownlint.jsonc into .markdownlint-cli2.jsonc (single config file)
- Remove package.json and package-lock.json (no longer needed)

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

.github/workflows/markdownlint.yml

@@ -0,0 +1,39 @@
+name: markdownlint
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+      - ".markdownlint-cli2.jsonc"
+      - ".github/workflows/markdownlint.yml"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: Get changed Markdown files
+        uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v47
+        id: changed-files
+        with:
+          files: "**/*.md"
+          separator: ","
+
+      - name: Run markdownlint
+        if: steps.changed-files.outputs.any_changed == 'true'
+        uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 # v23
+        with:
+          globs: ${{ steps.changed-files.outputs.all_changed_files }}
+          separator: ","

.markdownlint-cli2.jsonc

@@ -0,0 +1,30 @@
+{
+  // Glob patterns to ignore
+  "ignores": [
+    "node_modules/**",
+    "artifacts/**"
+  ],
+
+  // Inline markdownlint configuration (merged from .markdownlint.jsonc)
+  "config": {
+    // Default: enable all rules
+    "default": true,
+
+    // MD013 - Line length: disable because skill files and docs routinely have long lines
+    "MD013": false,
+
+    // MD024 - Multiple headings with the same content: allow siblings with same text
+    "MD024": {
+      "siblings_only": true
+    },
+
+    // MD033 - Inline HTML: allow specific elements commonly used in docs
+    "MD033": {
+      "allowed_elements": ["br", "details", "summary", "img", "a", "sub", "sup"]
+    },
+
+    // MD041 - First line in a file should be a top-level heading:
+    // Disable because SKILL.md files start with YAML frontmatter
+    "MD041": false
+  }
+}

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "DavidAnson.vscode-markdownlint"
+  ]
+}