feat(docs): extend docs with AI skills

Author: azasypkin

AGENTS.md

@@ -151,8 +151,19 @@ do not skip steps even when the previous stage was green.
 - **Nginx `types {}` in server scope replaces, not merges.** When adding `text/markdown
   md;` to serve the per-page companions, you must `include /etc/nginx/mime.types;` first
   in the same `server { … }` block, otherwise `.txt` (and everything else) regresses to
-  `application/octet-stream`. `llms.txt` is `text/plain` per spec; the per-page
-  companions are `text/markdown`.
+  `application/octet-stream`. The per-page `.md` companions are `text/markdown`. `llms.txt`
+  and `llms-index.txt` are **also** served as `text/markdown` despite the `.txt` extension
+  (they are llmstxt.org-format markdown files, and the promo site's `Accept: text/markdown`
+  content-negotiation 302 lands here -- Cloudflare's "Markdown for Agents" check at
+  isitagentready.com rejects a `text/plain` final response). Achieved with a regex
+  `location ~ ^/docs/llms(-index)?\.txt$ { types { } default_type text/markdown; }`
+  override that empties the inherited MIME map for that one location so `default_type`
+  wins. **The `/docs/` prefix matters**: the production Traefik route for the public
+  `secutils.dev/llms.txt` (and `/llms-index.txt`) URLs carries an `addPrefix: /docs`
+  middleware, so by the time the request reaches the docs nginx the URI is
+  `/docs/llms.txt`. A bare `location = /llms.txt` will silently never match -- if you
+  smoke-test this from inside the pod (e.g. `kubectl exec ... -- wget /llms.txt`), curl
+  the **prefixed** path instead.
 
 #### Docker (stages 4 & 10)
 

components/secutils-docs/README.md

@@ -8,3 +8,40 @@ Install all the required dependencies with `npm install` and run the UI in watch
 
 The docs website should be accessible at http://localhost:7373.
 
+## Agent skill files (`static/guides/.../SKILL.md`)
+
+Alongside each `.mdx` guide we publish a hand-authored `SKILL.md` file at `static/guides/<area>/<name>/SKILL.md` that 
+conforms to the [Cloudflare Agent Skills Discovery RFC v0.2.0](https://github.com/cloudflare/agent-skills-discovery-rfc).
+Docusaurus copies the `static/` tree verbatim into `build/`, so the file is served at 
+`https://secutils.dev/docs/guides/<area>/<name>/SKILL.md` with `Content-Type: text/markdown`.
+
+The promo site at https://secutils.dev aggregates these URLs into its `/.well-known/agent-skills/index.json` discovery 
+document. The aggregator lives in a separate repository under `components/secutils-dev-webui/src/skills.source.json` and
+keys off each SKILL.md's frontmatter `name:` field. When adding or editing a SKILL.md here:
+
+1. Use a unique `name:` slug (lowercased, hyphen-separated). It must match the corresponding entry in the promo repo's 
+   `skills.source.json`.
+2. Keep the YAML frontmatter minimal: `name:` and `description:` only. Use the folded scalar form (`description: >-`) 
+   for descriptions longer than one line.
+3. Author the body in clean Markdown. Avoid em-dashes, use commas instead. Do not wrap lines aggressively, aim for
+   roughly 120 columns at sentence boundaries.
+4. After editing, ask the promo repo's maintainer to rerun `npm run regenerate-skills` so the agent-skills index picks 
+   up the new sha256 digest. The promo script defaults to reading the bytes from this repo through a sibling 
+   working-tree `localPath`, so the digest matches the file the docs build will serve.
+
+When adding an entirely new SKILL.md, also add a corresponding entry (`name`, `description`, `url`, `localPath`) to
+`components/secutils-dev-webui/src/skills.source.json` in the promo repo and regenerate.
+
+### "Skill" badge on the rendered guide
+
+Every guide whose frontmatter declares `skill: true` automatically renders a small "Skill" pill in the top-right of the
+page that links to the companion SKILL.md (computed as`<page-permalink>/SKILL.md`). The badge mirrors the styling of the
+header pill used by the static tools at `tools.secutils.dev/*.html`, so the affordance is recognisable across both surfaces.
+
+The implementation is a Docusaurus swizzle:
+
+- `src/components/SkillBadge.tsx` / `.scss` - the standalone link/pill component.
+- `src/theme/DocItem/Content/index.tsx` - wraps the default `@theme-original/DocItem/Content` component, reads the 
+  current doc's `frontMatter` via `useDoc()`, and prepends the badge when `frontMatter.skill === true`.
+
+When adding a new SKILL.md, remember to add `skill: true` to the sibling `.mdx` so the badge appears.

components/secutils-docs/config/nginx.conf

@@ -6,9 +6,14 @@ server {
     # Re-include the global mime map so we can extend it with `.md` below without overriding the inherited
     # types map (nginx's `types {}` directive in server scope replaces, not merges).
     include /etc/nginx/mime.types;
-    # Serve per-page `.md` companion files (generated by docusaurus-plugin-llms) with the spec-compliant
-    # `text/markdown` content type so LLM crawlers and browsers render them as text instead of triggering a
-    # download. `.txt` (used by `llms.txt` / `llms-index.txt`) already maps to `text/plain` via mime.types.
+
+    # Serve per-page `.md` companion files (generated by docusaurus-plugin-llms) with the spec-compliant `text/markdown`
+    # content type so LLM crawlers and browsers render them as text instead of triggering a download. The `.txt` (used
+    # by `llms.txt` / `llms-index.txt`) maps to `text/plain` via mime.types by default, but the two llmstxt.org files
+    # are overridden in the `location = ...` block below to advertise `text/markdown` - their content IS markdown
+    # despite the `.txt` extension, and Cloudflare's "Markdown for Agents" check (isitagentready.com) refuses
+    # `text/plain` when an agent issued `Accept: text/markdown` and was redirected here from the main site's
+    # `location = /` block.
     types {
         text/markdown md;
     }
@@ -19,6 +24,24 @@ server {
 
     #access_log  /var/log/nginx/host.access.log  main;
 
+    # llmstxt.org files: override the inherited `.txt -> text/plain` MIME mapping with `text/markdown` so an agent that
+    # asked for `Accept: text/markdown` on `/` (and got 302'd here by the promo nginx) sees the correct content type.
+    # The `types { }` empties the inherited map for the location so `default_type` wins, this is the only safe way to
+    # override a single extension without disturbing the rest of the types map. The location regex covers both
+    # `llms.txt` and `llms-index.txt` in one block.
+    #
+    # The path prefix is `/docs/` because the production Traefik route for `secutils.dev/llms.txt` and
+    # `secutils.dev/llms-index.txt` carries an `addPrefix: /docs` middleware (Docusaurus is configured with
+    # `baseUrl: '/docs/'`, so all build output and every internal URL inside the docs container already lives under
+    # `/docs/`). A literal `location = /llms.txt` block would never match because the docs nginx never sees a bare
+    # `/llms.txt` URI - the rewrite happens at the edge before us.
+    location ~ ^/docs/llms(-index)?\.txt$ {
+        root   /usr/share/nginx/html;
+        types { }
+        default_type text/markdown;
+        try_files $uri =404;
+    }
+
     location / {
         root   /usr/share/nginx/html;
         try_files $uri $uri/index.html $uri/ $uri.html =404;

components/secutils-docs/docs/guides/digital_certificates/certificate_templates.mdx

@@ -3,6 +3,7 @@ sidebar_position: 1
 sidebar_label: Certificate Templates
 title: Digital Certificates ➔ Certificate templates
 description: Learn how to create and use digital certificate templates in Secutils.dev.
+skill: true
 ---
 
 import Steps from '@site/src/components/Steps';

components/secutils-docs/docs/guides/digital_certificates/private_keys.mdx

@@ -3,6 +3,7 @@ sidebar_position: 2
 sidebar_label: Private Keys
 title: Digital Certificates ➔ Private keys
 description: Learn how to create and use private keys in Secutils.dev.
+skill: true
 ---
 
 import Steps from '@site/src/components/Steps';

components/secutils-docs/docs/guides/platform/api_keys.mdx

@@ -3,6 +3,7 @@ sidebar_position: 2
 sidebar_label: API Keys
 title: API Keys
 description: Create and manage API keys for programmatic access to the Secutils.dev API from scripts, CI pipelines, and AI agents.
+skill: true
 ---
 
 import Steps from '@site/src/components/Steps';

components/secutils-docs/docs/guides/platform/deno_runtime.mdx

@@ -3,6 +3,7 @@ sidebar_position: 2
 sidebar_label: Deno Runtime
 title: Deno Sandbox Runtime
 description: Reference for the Deno Core APIs available in responder and tracker scripts.
+skill: true
 ---
 
 import CodeBlock from '@theme/CodeBlock';

components/secutils-docs/docs/guides/platform/export_import.mdx

@@ -3,6 +3,7 @@ sidebar_position: 3
 sidebar_label: Export & Import
 title: Export & Import Data
 description: Export and import your Secutils.dev data for backup, migration, or configuration management.
+skill: true
 ---
 
 import Steps from '@site/src/components/Steps';

components/secutils-docs/docs/guides/platform/secrets.mdx

@@ -3,6 +3,7 @@ sidebar_position: 1
 sidebar_label: Secrets
 title: User Secrets
 description: Store and manage encrypted secrets (API keys, tokens, credentials) for use in responder scripts, tracker scripts, and responder templates.
+skill: true
 ---
 
 import Steps from '@site/src/components/Steps';

components/secutils-docs/docs/guides/platform/tags.mdx

@@ -3,6 +3,7 @@ sidebar_position: 0
 sidebar_label: Tags
 title: Tags
 description: Organize your responders, trackers, policies, certificates, scripts, and secrets with tags.
+skill: true
 ---
 
 import Steps from '@site/src/components/Steps';