diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index c0499d0..33d817a 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -13,6 +13,9 @@ on:
       - 'LICENSE'
       - 'SECURITY.md'
       - 'CHANGELOG.md'
+      - 'AGENTS.md'
+      - 'CLAUDE.md'
+      - '**/SKILL.md'
     tags:
       - 'v*'
   workflow_dispatch:
diff --git a/AGENTS.md b/AGENTS.md
index 8c1114f..9ae874c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,4 +1,5 @@
 # AGENTS.md
+
 Guidance for AI agents (including Claude Code) working in this repository.
 
 ## Project Overview
@@ -25,7 +26,7 @@ It is a direct port of [FastAPI Guard](https://github.com/rennf93/fastapi-guard)
 
 FlaskAPI Guard is a **thin adapter** over [guard-core](https://github.com/rennf93/guard-core). All security logic (models, handlers, decorators, detection engine, protocols, utilities) lives in the `guard_core` package; this repo contains only the Flask/WSGI integration layer.
 
-```
+```text
 guard-core (engine, PyPI dependency >=3.15.0)   <- all security logic
 └── flaskapi-guard (this repo)                  <- Flask extension adapter
     ├── fastapi-guard                           <- sibling adapter (ASGI middleware)
diff --git a/CLAUDE.md b/CLAUDE.md
index 8c1114f..9ae874c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,4 +1,5 @@
 # AGENTS.md
+
 Guidance for AI agents (including Claude Code) working in this repository.
 
 ## Project Overview
@@ -25,7 +26,7 @@ It is a direct port of [FastAPI Guard](https://github.com/rennf93/fastapi-guard)
 
 FlaskAPI Guard is a **thin adapter** over [guard-core](https://github.com/rennf93/guard-core). All security logic (models, handlers, decorators, detection engine, protocols, utilities) lives in the `guard_core` package; this repo contains only the Flask/WSGI integration layer.
 
-```
+```text
 guard-core (engine, PyPI dependency >=3.15.0)   <- all security logic
 └── flaskapi-guard (this repo)                  <- Flask extension adapter
     ├── fastapi-guard                           <- sibling adapter (ASGI middleware)
diff --git a/pyproject.toml b/pyproject.toml
index 26714b9..23b7338 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -126,6 +126,10 @@ warn_unreachable = true
 exclude = ["vulture_whitelist.py", ".venv"]
 
 
+[tool.pymarkdown.extensions]
+# Enable YAML front matter parsing (agent skill files use front matter)
+front-matter = {enabled = true}
+
 [tool.pymarkdown.plugins.md007]
 # MD007 - Unordered list indentation (set to 2 spaces)
 enabled = true