diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
new file mode 100644
index 0000000..0d032c1
--- /dev/null
+++ b/.github/workflows/lint.yml
@@ -0,0 +1,77 @@
+name: Lint
+
+# Two roles for this workflow:
+#
+# 1. Self-test: triggers on pull_request + push to main of *this repo* so that
+#    typos in the reusable workflows here get caught before they break every
+#    downstream consumer.
+#
+# 2. Reusable: other repos can call it via
+#       jobs:
+#         lint:
+#           uses: topcoder1/ci-workflows/.github/workflows/lint.yml@main
+#    See callers/lint.yml in the templates dir for a copy-paste-ready caller.
+#
+# What it checks:
+#   - actionlint on every .github/workflows/*.yml (catches GHA-specific bugs +
+#     embedded shellcheck for `run:` blocks)
+#   - prettier --check on the markdown glob (default **/*.md)
+#
+# Why no husky/lint-staged: this is meant to plug into repos with mixed
+# tooling (or none). CI-only enforcement keeps the dependency surface flat.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_call:
+    inputs:
+      markdown_glob:
+        description: "Glob passed to prettier --check. Default '**/*.md'."
+        required: false
+        type: string
+        default: "**/*.md"
+      run_actionlint:
+        description: "Run actionlint job. Default true."
+        required: false
+        type: boolean
+        default: true
+      run_prettier:
+        description: "Run prettier --check on markdown. Default true."
+        required: false
+        type: boolean
+        default: true
+
+permissions:
+  contents: read
+
+jobs:
+  actionlint:
+    name: actionlint
+    if: ${{ github.event_name != 'workflow_call' || inputs.run_actionlint }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download actionlint
+        id: get_actionlint
+        run: bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
+        shell: bash
+
+      - name: Run actionlint
+        run: ${{ steps.get_actionlint.outputs.executable }} -color
+        shell: bash
+
+  prettier:
+    name: prettier (markdown)
+    if: ${{ github.event_name != 'workflow_call' || inputs.run_prettier }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: prettier --check ${{ inputs.markdown_glob || '**/*.md' }}
+        run: npx --yes prettier@3 --check "${{ inputs.markdown_glob || '**/*.md' }}"
diff --git a/.github/workflows/pr-classify.yml b/.github/workflows/pr-classify.yml
index 31a6ac1..39fa198 100644
--- a/.github/workflows/pr-classify.yml
+++ b/.github/workflows/pr-classify.yml
@@ -68,6 +68,7 @@ jobs:
           echo "class=$class" >> "$GITHUB_OUTPUT"
           echo "Computed risk class: $class"
           echo "Changed files:"
+          # shellcheck disable=SC2001 # multiline indent — sed is clearer than ${var//.../...}
           echo "$changed" | sed 's/^/  /'
 
       - name: Set risk label on PR
diff --git a/README.md b/README.md
index 5e39ce2..aae8e4e 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,7 @@ Reusable GitHub Actions workflows for solo-dev fleet management.
 Runs Anthropic's [`claude-code-action@v1`](https://github.com/anthropics/claude-code-action) on PRs to post inline review comments. Caller passes `ANTHROPIC_API_KEY` as a secret.
 
 **Inputs:**
+
 - `review_focus` (string, optional) — appended to the base review prompt for project-specific guidance
 - `checkout_depth` (number, default `0`) — git fetch-depth (0 = full history)
 
@@ -19,6 +20,7 @@ Runs Anthropic's [`claude-code-action@v1`](https://github.com/anthropics/claude-
 Auto-merges Dependabot PRs for patch (and optionally minor) version bumps once required checks pass.
 
 **Inputs:**
+
 - `merge_method` (string, default `squash`) — `merge` | `squash` | `rebase`
 - `allow_minor` (bool, default `true`) — also merge minor bumps