opencode-skills-collection 3.1.11 → 3.1.13

package/bundled-skills/huggingface-zerogpu/references/concurrency.md

@@ -0,0 +1,79 @@
+# Concurrency Safety
+
+Gradio handlers run **in parallel by default on ZeroGPU**. Code that works fine in single-user testing can silently corrupt or leak data in production. Always assume handlers execute concurrently.
+
+## No mutable global state
+
+Per-request or per-user data must not live in module-level mutable variables. Concurrent requests will overwrite each other.
+
+```python
+# BAD — concurrent requests overwrite each other
+results = {}
+
+def process(text):
+    results["output"] = expensive_compute(text)  # race condition
+    return results["output"]
+```
+
+```python
+# GOOD — pure function, no shared mutable state
+def process(text):
+    return expensive_compute(text)
+```
+
+For state that must persist within a single user session, use `gr.State`:
+
+```python
+with gr.Blocks() as demo:
+    history = gr.State(value=[])
+
+    def add_message(msg, hist):
+        hist.append(msg)
+        return hist, hist
+
+    btn.click(fn=add_message, inputs=[msg, history], outputs=[chatbot, history])
+```
+
+Note that on ZeroGPU, `gr.State` is pickled across the worker boundary on every yield — see "Process Isolation and Pickle" in SKILL.md for the implications.
+
+## No fixed file paths for outputs
+
+Hardcoded output filenames cause concurrent requests to overwrite each other's files. This corrupts outputs and, worse, can leak one user's data to another.
+
+```python
+# BAD — concurrent calls clobber the same file
+def generate_image(prompt):
+    image = pipe(prompt).images[0]
+    image.save("output.png")
+    return "output.png"
+```
+
+```python
+# GOOD — unique path per invocation
+import tempfile
+
+def generate_image(prompt):
+    image = pipe(prompt).images[0]
+    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+        image.save(f.name)
+        return f.name
+```
+
+The same applies to any intermediate files (audio, video, CSV exports). Always generate a unique path per invocation.
+
+## Read-only globals are safe
+
+Model objects, tokenizers, and configs loaded once at startup and only read during requests are safe and encouraged. This is the standard ZeroGPU pattern: load at module scope, read inside `@spaces.GPU` handlers.
+
+```python
+# SAFE — loaded once at module scope, read-only during requests
+model = load_model().to("cuda")
+tokenizer = load_tokenizer()
+
+@spaces.GPU
+def predict(text):
+    tokens = tokenizer(text, return_tensors="pt").to("cuda")
+    return model.generate(**tokens)
+```
+
+The "no mutable global state" rule targets *writes* from handlers, not reads. A handler that only reads from a global is concurrency-safe.

package/bundled-skills/huggingface-zerogpu/references/cuda-and-deps.md

@@ -0,0 +1,66 @@
+# CUDA Dependencies on ZeroGPU
+
+Detailed guidance for installing CUDA-dependent packages on ZeroGPU. SKILL.md establishes the bottom line — wheels are the recommended path because the ZeroGPU build phase has no `nvcc`. This document covers wheel filename tag reading, the kernels-community fallback, and torch-family side-car drift.
+
+## When no wheel is available on PyPI
+
+Common workarounds, in preference order:
+
+1. **Pre-built wheel via direct URL.** For `flash-attn`, the upstream project ships a fairly complete matrix at https://github.com/Dao-AILab/flash-attention/releases — check there first and pin the matching wheel URL.
+2. **Build the wheel yourself and host it** (e.g. on a public HF Hub repo) when no upstream wheel matches the Space environment.
+3. **Use a kernels-community kernel** (see below) — handles ABI matching for you, no version pinning needed.
+
+## Reading a CUDA wheel filename
+
+A wheel filename like
+
+```
+flash_attn-2.8.0.post2+cu12torch2.8cxx11abiFALSE-cp312-cp312-linux_x86_64.whl
+```
+
+encodes four build-time choices:
+
+| Tag | Meaning |
+|-----|---------|
+| `cu12` | CUDA major version |
+| `torch2.8` | torch major.minor the wheel was compiled against |
+| `cxx11abiFALSE` | C++ stdlib ABI choice (`TRUE` or `FALSE`) |
+| `cp312-cp312` | CPython version (3.12) |
+
+The wheel's compiled C-extension will `ImportError` on ABI/symbol mismatches if any of these drift at install time.
+
+If you hand pip a wheel URL without pinning the surrounding environment, pip may resolve `torch` to a version different from the wheel's build target, and the Space will fail on first import. Therefore:
+
+- Pin `torch==X.Y.Z` in `requirements.txt` to match the wheel's `torch2.X` tag.
+- Set `python_version:` in the Space frontmatter to match the `cp3XX` tag.
+- Check the runtime's cxx11-ABI choice against the wheel; if unsure, try the opposite ABI wheel.
+
+## Prefer kernels-community when unsure
+
+If you are not sure about the ZeroGPU runtime's torch / Python / ABI combination, prefer a [kernels-community](https://huggingface.co/kernels-community) kernel (e.g. `kernels-community/flash-attn2`) instead of a raw wheel URL. The kernels runtime handles ABI matching on your behalf, so no version pinning is required in your Space.
+
+## torch-family side-car drift
+
+`torchvision`, `torchaudio`, `torchcodec`, and similar side-car packages are built against a specific `torch` major.minor (and CUDA major). On ZeroGPU, the runtime's supported `torch` list lags behind PyPI, so projects often pin a non-latest `torch` — and a bare `uv add <side-car>` can silently resolve to a newer release that targets a different `torch` / CUDA, producing ABI/import failures even though `uv lock` succeeded without warnings.
+
+Concretely observed (2026-04) with `torch==2.9.1` pinned:
+
+- `torchaudio` resolves to `2.11.0`, which targets torch 2.11 / CUDA 13. The `2.11.0` release **dropped the `Requires-Dist: torch==X.Y.Z` line** that every earlier release had, so uv sees no constraint and picks it.
+- `torchcodec` resolves to a release targeting torch 2.11. No torchcodec release on PyPI declares a `torch` dependency at all; the compatibility table lives only in the project README.
+- `torchvision` happens to resolve correctly because torchvision still declares `Requires-Dist: torch==X.Y.Z`. Which side-cars are affected changes over time — treat every torch-family package as suspect, not just these.
+
+### Verify at add/upgrade time
+
+After any `uv add <torch-side-car>` or `uv lock --upgrade`, verify the resolved version targets the same `torch` major.minor as pinned. Two-step fallback because PyPI metadata is not always sufficient:
+
+1. Query PyPI for the resolved version's `requires_dist`:
+   ```bash
+   curl -s https://pypi.org/pypi/<pkg>/<version>/json \
+     | python3 -c "import json,sys,re; rd=json.load(sys.stdin)['info'].get('requires_dist') or []; print('\n'.join(x for x in rd if re.match(r'^torch(?![a-z])', x)) or '(no torch constraint declared)')"
+   ```
+   If a `torch==X.Y.Z` line appears and matches the pinned torch, good. If it appears and does NOT match, the side-car is wrong — pin it down explicitly.
+2. If the query prints `(no torch constraint declared)`, PyPI metadata is silent and cannot be trusted. Fall back to the project's own compatibility table (GitHub README / docs site) — torchcodec, for example, maintains one at https://github.com/pytorch/torchcodec. Pick the side-car version the table maps to the pinned torch major.minor, and pin it explicitly.
+
+### Preventive pin
+
+Once the correct side-car version is known, pin it in `pyproject.toml` alongside torch so uv cannot drift on future `uv lock --upgrade`. The side-car version numbers for a given torch major.minor change each release; always re-verify, do not copy a mapping from an older project.

package/bundled-skills/huggingface-zerogpu/references/how-quota-works.md

@@ -0,0 +1,74 @@
+# How ZeroGPU duration and quota are checked
+
+Mechanism for `duration` validation and quota pre-checks. Useful when choosing `duration` values, debugging `illegal duration` vs `quota exceeded` errors, and understanding why the default 60s is pessimistic for short tasks.
+
+For per-tier numerical thresholds (free vs Pro vs Team vs Enterprise quota minutes), the daily quota window length, runs-per-day limits, and pay-as-you-go pricing, see [the ZeroGPU docs](https://huggingface.co/docs/hub/spaces-zerogpu) — those values change over time and are deliberately kept out of this skill.
+
+## What `duration` actually requests
+
+Whatever value is passed to `@spaces.GPU(duration=N)` (or the default 60s when unspecified) becomes the `requested duration` the platform checks against. For `xlarge`, the request is doubled internally:
+
+```
+requested = N * 2 if size == "xlarge" else N
+```
+
+So `@spaces.GPU(duration=60, size="xlarge")` is internally a 120-second request — both for the tier-max check and the quota pre-check below.
+
+## Two distinct error modes
+
+Two failure messages can come back from the scheduler before the call runs:
+
+| Error | Trigger | What helps |
+|---|---|---|
+| **`ZeroGPU illegal duration`** | `requested duration > visitor's tier per-call cap` | Lower `duration`. Sign in / upgrade tier. **Waiting does not help.** |
+| **`ZeroGPU quota exceeded`** | `remaining quota < requested duration`, OR runs-per-day cap reached | Wait for the quota window to reset. For Pro / Team / Enterprise, pay-as-you-go credits cover the overflow. |
+
+The error wording for `quota exceeded` includes the explicit numbers, e.g.:
+
+```
+You have exceeded your Pro ZeroGPU quota
+(60s requested vs. 30s left). Try again in 1:23:45.
+```
+
+The comparison is **`requested` vs `remaining`** — not `actual run time` vs `remaining`. A 10-second task left at the default 60s requests 60s of quota; once `remaining < 60s` the call fails even though the actual work would have fit.
+
+## Why the default 60s is pessimistic for short tasks
+
+`DEFAULT_SCHEDULE_DURATION` in the `spaces` package is **60 seconds**. So an undecorated `@spaces.GPU` (or `@spaces.GPU()` with no `duration=`) requests 60s of quota.
+
+For a task that actually takes ~10 seconds:
+
+- The user's 60s quota gets reserved up front.
+- Once their remaining quota drops below 60s, your Space fails for them — even though they could have run many more 10s tasks if the request matched reality.
+- Your call also ranks lower in the queue than equivalent calls declaring smaller durations.
+
+The fix is to declare the realistic duration explicitly:
+
+```python
+@spaces.GPU(duration=15)
+def fast_task(...):
+    ...
+```
+
+For workloads where runtime depends on inputs, use a callable (per-request estimator):
+
+```python
+def estimate_duration(prompt, steps):
+    return int(steps * 3.5)
+
+@spaces.GPU(duration=estimate_duration)
+def variable_task(prompt, steps):
+    ...
+```
+
+This preserves quota for light inputs and reserves more only when needed.
+
+## Quota window: 24h fixed from first use
+
+The quota window's TTL is set when the first call of a fresh window lands and counts down unconditionally — it is not a sliding window, not a calendar-day reset, and not extended by subsequent use. A user who runs a call at 14:00 sees their next reset at 14:00 the following day, regardless of how heavily or lightly they use the Space in between.
+
+For exact tier thresholds, runs-per-day caps, and pay-as-you-go billing rates, see the [ZeroGPU docs](https://huggingface.co/docs/hub/spaces-zerogpu).
+
+## Queue priority
+
+The queue is **node-level** — requests from every Space scheduled on the same physical node compete for that node's GPU slots. Among queued requests, **shorter declared `duration` ranks higher**. So tight per-request `duration` estimates serve two goals at once: they preserve the user's quota and move the request up the queue.

package/bundled-skills/huggingface-zerogpu/references/how-zerogpu-works.md

@@ -0,0 +1,50 @@
+# How ZeroGPU works (mechanism)
+
+Conceptual lifecycle of model weights, processes, and worker reuse on ZeroGPU. Useful when reasoning about cold-starts, why module-scope warmup does not carry over to requests, why returning CUDA tensors hangs the call, or why `gr.State` mutations do not persist across the worker boundary.
+
+For numerical limits (concurrency slots per Space, queue priority by tier, etc.), see [the ZeroGPU docs](https://huggingface.co/docs/hub/spaces-zerogpu) — those values change over time and are deliberately kept out of this skill.
+
+## Two processes, two lifetimes
+
+A ZeroGPU Space runs as **two separate processes**:
+
+- **Main web process** — long-lived. Imports `app.py`, launches Gradio, stays up for the life of the Space. Holds no VRAM and, after the startup "pack" step, holds no model weights in RAM either.
+- **GPU worker processes** — short-lived. Forked per `@spaces.GPU` request (or reused if warm). Run the task and are eventually killed by the ZeroGPU scheduler when another Space needs the GPU slot. Your Space code never kills its own worker.
+
+## Module-scope `.to("cuda")` is captured to disk
+
+When `import spaces` is active, `model.to("cuda")` at module scope is intercepted. The call is rewritten to `to("cpu")`, so the tensor data physically lives in main process RAM at this point. A "fake" CUDA-presenting tensor is registered alongside the original CPU tensor.
+
+At a startup "pack" step, the backend writes those original CPU tensors to disk via direct I/O (`O_DIRECT`), then frees the corresponding RAM. After pack, the main process holds no model weights anywhere — the data lives only on disk.
+
+This is why module-scope `pipe(...)` / `model.generate(...)` / `model(...)` calls do not run on a real GPU: there is no GPU attached to the main process, and after pack there are no weights to compute against either. Such calls either fail or silently fall back to CPU on the fake tensors.
+
+## Worker init: disk → pinned memory → VRAM
+
+When a `@spaces.GPU` call lands, the scheduler routes it to a worker:
+
+1. **Cold worker** — forked from the main process. The patched torch is unpatched, real CUDA is initialized, and weights are read from the disk offload directory into pinned host memory and streamed onto VRAM through a double-buffered pipeline (essentially `pin_memory().cuda(non_blocking=True)` per batch). This is the "cold-start" cost.
+2. **Warm worker (reused)** — an alive worker bound to the same GPU slot is reused if the scheduler reports it idle. Init is skipped; weights stay on VRAM from the previous call. Subsequent requests within a burst hit this path.
+
+A warm worker is eventually killed by the scheduler when another Space needs the GPU slot. The next call after that point pays the disk → VRAM cost again. Occasional cold-starts on a low-traffic Space are normal.
+
+## Why module-scope warmup does not help
+
+A common instinct is to call `pipe("warmup")` at module scope to "prepare" the model. This does not work on ZeroGPU:
+
+- At module scope, no real GPU is attached. The fake CUDA tensors do not have data after pack, so `pipe(...)` either fails or silently runs on something other than a real GPU.
+- Even if you wrap the warmup in `@spaces.GPU`, the worker that ran the warmup will eventually be killed before the first real user request lands — leaving them with a cold worker anyway.
+
+The right answer is to load eagerly at module scope (`pipe = pipeline(..., device="cuda")`) and accept that the first user request after a quiet period will be a cold worker. Cold-start is fast on ZeroGPU because of the pinned-memory disk pipeline; it is not free, but it is not "minutes of model download" either.
+
+## Why returning CUDA tensors hangs the call
+
+The main process never has a CUDA context — it has no GPU attached and its torch never initialized CUDA. When a worker returns a CUDA tensor, unpickling it in the main process triggers `torch.cuda._lazy_init()`, which would attempt to initialize CUDA in the main process. ZeroGPU blocks this, and the call hangs.
+
+The fix is purely client-side: convert to CPU before returning (`.cpu()`, `.cpu().numpy()`, etc.). See "Process Isolation and Pickle" in SKILL.md.
+
+## Why `gr.State` does not share by reference across the boundary
+
+Worker processes are forked separately and exchange data with the main process via pickle. `gr.State` values cross this boundary on every yield, so mutations inside a `@spaces.GPU` generator are local to the worker until the mutated state is explicitly yielded back. The main process gets a fresh deserialized copy each time — `id()` differs, in-place mutations are invisible across the boundary.
+
+See "Process Isolation and Pickle" in SKILL.md for the practical implications and `references/concurrency.md` for related parallel-handler concerns.

package/bundled-skills/hugo-to-markdown/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: hugo-to-markdown
+description: Convert Hugo documentation sites and Hugo-managed content into standard Markdown. Use when Agent needs to inspect a local Hugo repository, read hugo.toml or config files, content/, archetypes/, layouts/_shortcodes/, layouts/_markup/, and related docs content, then produce Markdown...
+risk: unknown
+source: https://github.com/chaunsin/agent-skills/tree/master/skills/hugo-to-markdown
+source_repo: chaunsin/agent-skills
+source_type: community
+date_added: 2026-07-01
+license: Apache-2.0
+license_source: https://github.com/chaunsin/agent-skills/blob/master/LICENSE
+---
+
+# Hugo To Markdown
+## When to Use
+
+Use this skill when you need convert Hugo documentation sites and Hugo-managed content into standard Markdown. Use when Agent needs to inspect a local Hugo repository, read hugo.toml or config files, content/, archetypes/, layouts/_shortcodes/, layouts/_markup/, and related docs content, then produce Markdown...
+
+
+## Overview
+
+Use this skill when Markdown output must be derived from the local Hugo site, not guessed from generic Hugo knowledge. The conversion rules are the combination of Hugo's official behavior and the repository's own configuration, shortcode templates, render hooks, archetypes, and content conventions.
+
+The target output is standard Markdown:
+
+- Keep plain Markdown and YAML front matter.
+- Replace or materialize Hugo-only constructs.
+- Preserve meaning when exact rendering is not safely reproducible.
+- Prefer explicit Markdown text over live Hugo template syntax.
+- Distinguish literal Hugo syntax examples from active Hugo features before rewriting anything.
+
+## Official Basis
+
+Treat the repository's own Hugo configuration and templates as the primary ruleset. For any site under conversion, inspect these rule sources in the user's provided site root:
+
+- `hugo.toml` (or `hugo.yaml`, `hugo.yml`, `hugo.json`, or `config/*`)
+- `archetypes/*`
+- `data/*`
+- `layouts/_shortcodes/*` or `layouts/shortcodes/*`
+- `layouts/_markup/*`
+- `content/**`
+
+Also read any local docs that define shortcode, front matter, bundle, resource, and render-hook behavior.
+
+Do not assume built-in Hugo defaults if the repository overrides them locally.
+
+## Workflow
+
+### 1. Inventory the site before converting files
+
+Always inspect the site-level rules first.
+
+```bash
+python3 scripts/inventory_hugo_rules.py --site-root /path/to/hugo-site
+```
+
+Example invocation for the user's site:
+
+```bash
+python3 skills/hugo-to-markdown/scripts/inventory_hugo_rules.py \
+  --site-root /path/to/your-hugo-site
+```
+
+This inventory step is mandatory for batch work. It identifies:
+
+- active config files
+- module mounts and content roots
+- custom shortcodes
+- custom render hooks
+- front matter keys seen in content
+- shortcode usage across content files
+
+### 2. Convert with repository rules, not generic heuristics
+
+Read `references/conversion-workflow.md` before changing files. Then:
+
+1. Resolve the real content root from `hugo.toml`, `config.*`, and module mounts.
+2. Read archetypes to understand expected front matter shape.
+3. Read the front matter configuration to understand date aliases, fallback order, filename-derived dates, and other inferred metadata.
+4. Read site data sources in `data/` when shortcodes or partials pull structured content from them.
+5. Read custom shortcode templates in `layouts/_shortcodes/` or `layouts/shortcodes/`.
+6. Classify each encountered shortcode as embedded, custom, or inline, then check whether it uses named or positional arguments, block syntax, or self-closing syntax.
+7. Read render hooks in `layouts/_markup/`.
+8. Check whether the repo already defines Markdown- or JSON-facing export templates and partials; if it does, use those as evidence for how the site itself downgrades Hugo constructs.
+9. Follow `include`-style shortcodes into referenced content files when the docs site composes content from shared fragments.
+10. Convert one file or one coherent section at a time.
+
+### 3. Preserve semantics during conversion
+
+Use these rules by default:
+
+- Keep YAML front matter unless the user explicitly asks for front-matter-free Markdown.
+- Preserve core fields such as `title`, `description`, `date`, `draft`, `aliases`, `slug`, `url`, `weight`, and nested `params` when they still carry meaning.
+- Preserve `publishDate`, `lastmod`, `expiryDate`, and page resource metadata when they still affect meaning or downstream routing.
+- Normalize reserved Hugo front matter keys to their canonical names when the repo mixes casing, for example `Title` to `title`, `Description` to `description`, and `LinkTitle` to `linkTitle`.
+- Account for Hugo front matter aliases and tokens before deciding a field is unused. The official Hugo docs recognize aliases such as `pubdate`, `published`, `modified`, and `unpublishdate`, plus tokens such as `:default`, `:filename`, `:fileModTime`, and `:git`.
+- Convert Hugo internal links to normal Markdown links with resolved destinations.
+- Replace Hugo shortcodes with plain Markdown, HTML, or explicit notes only after reading the local shortcode implementation.
+- Preserve or materialize shortcode arguments according to the shortcode's real calling convention. Do not assume every shortcode is named-argument, self-closing, or block-capable.
+- Materialize dynamically generated lists and tables when the shortcode renders content from sections or data files.
+- Leave literal Hugo examples unchanged when the document is documenting Hugo syntax rather than invoking it. This applies both inside fenced code blocks and to escaped forms such as `{{</* foo */>}}` or `{{%/* foo */%}}` that appear in prose, tables, or notation examples.
+- Preserve block attribute semantics such as `{.class #id}` and code-fence attributes when the destination Markdown flavor supports them. If not, downgrade explicitly instead of silently dropping them.
+
+### 4. Apply Hugo-specific body rules carefully
+
+Many Hugo documentation sites use complex local behaviors. Be alert for these common patterns:
+
+- `hugo.toml` mounts `content/en` to the logical `content` root, so link and include resolution must use Hugo logical paths instead of preserving `/en/` blindly.
+- The docs basis depends on Hugo front matter configuration for date resolution, aliases, and filename-derived metadata; read `configuration/front-matter.md` and `[frontmatter]` in `hugo.toml` before normalizing dates or slugs.
+- `include` renders another page through `RenderShortcodes`; follow the referenced content file and inline the resulting Markdown.
+- `quick-reference`, `render-list-of-pages-in-section`, and `render-table-of-pages-in-section` generate navigation content from sections; replace them with materialized Markdown lists or tables.
+- `glossary-term`, `glossary`, `get-page-desc`, `module-mounts-note`, `new-in`, and `deprecated-in` expand to prose or badges; convert them into explicit Markdown text or callouts.
+- `code-toggle` may read config snippets and data-backed examples; preserve the underlying code sample, not the UI toggle.
+- `datatable`, `per-lang-config-keys`, `root-configuration-keys`, `syntax-highlighting-styles`, `chroma-lexers`, `newtemplatesystem`, and `hl` are also local shortcodes; inspect their implementations before deciding whether to materialize, flatten, or downgrade.
+- if the repo has data-backed or example-extraction shortcodes such as `features-table`, `optional-features-table`, `clients-example`, or `jupyter-example`, inspect the referenced `data/` files, local example sources, and Markdown-export partials before deciding whether to materialize or downgrade.
+- glossary links can use the special Markdown destination `(g)`; resolve these to stable glossary links instead of leaving the placeholder.
+- `img` and `imgproc` are presentation helpers around page, global, or remote resources; preserve the underlying image reference and caption semantics.
+- `eturl` emits links to embedded template sources; convert to a normal Markdown link if the destination is known, otherwise preserve as a textual note.
+- the local link render hook resolves destinations in this order: content page, page resource, section resource when the page is not a leaf bundle, then global resource. It also validates fragments and glossary shorthand.
+- blockquote and code-block render hooks add alert, file-label, summary, and detail semantics; preserve these semantics in Markdown or explicit notes.
+- embedded `ref` and `relref` are obsolete for Markdown in modern Hugo docs and can interact poorly with the custom link render hook; resolve the final destination instead of preserving the shortcode.
+- the local docs use Markdown attributes and code-fence options that can change rendered output. Keep these semantics when the destination flavor supports them.
+
+Read `references/shortcodes-and-render-hooks.md` before converting any file that contains Hugo syntax.
+
+### 5. Validate the output
+
+After conversion, scan the generated Markdown for leftover Hugo-only syntax.
+
+```bash
+python3 skills/hugo-to-markdown/scripts/check_standard_markdown.py \
+  --root /path/to/output
+```
+
+If the validator reports active Hugo syntax outside code fences, either:
+
+- resolve it fully, or
+- replace it with a safe textual explanation
+
+Do not silently ship unresolved `{{< ... >}}`, `{{% ... %}}`, or Go template expressions.
+
+### 6. Downgrade explicitly when full materialization is not safe
+
+If a shortcode depends on build-time data, generated examples, or external source files that you cannot resolve deterministically from the local repo snapshot, replace it with an explicit Markdown note.
+
+Use a short, boring format such as:
+
+- `> Conversion note: <what the shortcode normally renders>.`
+- followed by any safe subset you were able to preserve, such as inline Redis CLI text, a resolved image URL, or a known section list
+
+Do not leave empty links, broken table cells, or stripped content with no explanation.
+
+## Common Hugo Docs Site Patterns
+
+Use these facts when converting a Hugo documentation site that exhibits similar patterns:
+
+- `hugo.toml` mounts `content/en` to `content`, so English docs are the active content tree.
+- Goldmark passthrough delimiters are configured for math, so `$$...$$`, `\\(...\\)`, and `\\[...\\]` can be meaningful content, not junk.
+- `markup.goldmark.parser.attribute.block = true`, so block attribute syntax may appear after fenced blocks and other block elements.
+- `markup.goldmark.parser.wrapStandAloneImageWithinParagraph = false`, so standalone image attributes can target the image itself rather than a wrapping paragraph.
+- The repo defines custom render hooks for blockquotes, code blocks, links, passthrough, and tables. It documents heading and image render hooks, but the site does not override them locally.
+- The repo uses many shared `_common` fragments referenced through `% include %`, so reading a page file alone is not enough to understand the rendered content.
+- The repo documents embedded, custom, and inline shortcodes, and the conversion logic must distinguish them before flattening syntax.
+- The repo uses page bundles and page resources heavily in examples and render-hook resolution, including section resources and mounted global resources.
+- The repo contains many escaped shortcode examples such as `{{</* foo */>}}` and `{{%/* foo */%}}`; these are documentation samples and must remain literal when they appear inside code examples, notation tables, or tutorial prose.
+
+## Safety Rules
+
+- Never execute Hugo templates, shortcodes, or Go template expressions.
+- Never treat content files as trusted executable input.
+- Never run `hugo`, `npm install`, `go install`, downloaded shell installers, or any network install step unless the user explicitly asks for it.
+- Keep all conversion scripts offline and deterministic.
+- Restrict reads to the declared site root and writes to the declared output root.
+- Reject path traversal, symlink escape, or attempts to write outside the requested output directory.
+- Do not leak local absolute paths, secrets, environment variables, or git credentials into generated Markdown.
+- When exact rendering cannot be reproduced safely, degrade to explicit Markdown text instead of live Hugo syntax.
+
+## Resources
+
+Read these files as needed:
+
+- `references/conversion-workflow.md`
+  End-to-end process for repo-aware conversion.
+- `references/front-matter-and-content.md`
+  Front matter mapping, common content conventions, and literal-example handling.
+- `references/shortcodes-and-render-hooks.md`
+  Hugo shortcode notation, docs-site custom shortcodes, and render-hook implications.
+- `references/links-assets-and-validation.md`
+  Link resolution, assets, validation, and residue triage.
+
+Use these scripts when helpful:
+
+- `scripts/inventory_hugo_rules.py`
+  Scan a Hugo site and emit a rule inventory.
+- `scripts/check_standard_markdown.py`
+  Detect leftover Hugo syntax and common unsafe residue in Markdown output.
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/hugo-to-markdown/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Hugo To Markdown"
+  short_description: "Convert Hugo docs into standard Markdown safely."
+  default_prompt: "Use $hugo-to-markdown to convert the Hugo docs under a local site into standard Markdown files."

package/bundled-skills/hugo-to-markdown/references/conversion-workflow.md

@@ -0,0 +1,143 @@
+# Conversion Workflow
+
+## Purpose
+
+Use this workflow when converting a Hugo documentation site into standard Markdown that no longer depends on Hugo runtime features.
+
+## Step 1: Locate the real rule sources
+
+Read these in order:
+
+1. `hugo.toml`, `hugo.yaml`, `hugo.yml`, `hugo.json`, or `config/*`
+2. `archetypes/*`
+3. `data/*`
+4. official or local docs that define shortcode, front matter, bundle, resource, and render-hook behavior
+5. `layouts/_shortcodes/*` or `layouts/shortcodes/*`
+6. `layouts/_markup/*`
+7. Markdown- or JSON-facing export templates and partials such as `layouts/_default/*.md`, `layouts/_default/*.json`, or `layouts/partials/markdown-*.html`
+8. `content/*`
+
+## Step 2: Build a site inventory
+
+Run:
+
+```bash
+python3 skills/hugo-to-markdown/scripts/inventory_hugo_rules.py \
+  --site-root /path/to/your-hugo-site
+```
+
+Inspect the output for:
+
+- content root and module mounts
+- active shortcode names
+- render hook names
+- frequently used shortcodes
+- front matter keys
+- front matter alias or token usage that changes visible dates or slugs
+- whether shortcode usage clusters around content graph expansion, section listings, data-backed tables, or external example extraction
+
+Use the inventory to batch files by complexity:
+
+- plain Markdown only
+- front matter only
+- literal Hugo documentation examples
+- pages with Markdown attributes or code-fence options that must be preserved
+- built-in shortcode usage
+- content-graph shortcodes such as `include`, `embed-md`, `glossary-term`, and `table-children`
+- custom shortcode usage
+- data-backed shortcode usage
+- render-hook-sensitive links and assets
+
+## Step 3: Convert one slice at a time
+
+Preferred order:
+
+1. plain pages
+2. pages with only front matter normalization
+3. pages that mostly document Hugo syntax and contain literal shortcode examples
+4. pages using shared includes
+5. pages using custom shortcodes
+6. pages whose content is partially generated from sections or data files
+7. pages whose content depends on generated code examples or external local sources
+
+This keeps regressions local and makes validation easier.
+
+## Step 4: Materialize dynamic content
+
+If a shortcode generates prose, lists, tables, or badges, replace it with the resulting Markdown.
+
+Examples from the Hugo docs site:
+
+- `include` pulls another content file and renders its shortcodes
+- `quick-reference` expands section content
+- `render-list-of-pages-in-section` builds a list from a section
+- `render-table-of-pages-in-section` builds a table from section pages
+- `glossary` materializes glossary content
+
+Do not keep these as live Hugo shortcodes in the final standard Markdown.
+
+When evaluating a shortcode, classify it first:
+
+1. Static wrapper around inner Markdown or a simple asset
+2. Content graph expansion into other pages or sections
+3. Data-backed expansion using `data/*`
+4. Generated example extraction from files outside the current page
+
+This classification determines whether you can materialize the output directly, need recursive page resolution, need data-file reads, or must degrade to an explicit note.
+
+Also determine whether the shortcode is:
+
+- embedded, custom, or inline
+- block, self-closing, or dual-form
+- named-argument, positional-argument, or dual-mode
+
+These choices affect how you parse the call and how much of the surrounding Markdown Hugo would have rendered.
+
+## Step 5: Keep literal Hugo examples literal
+
+The docs site frequently documents Hugo syntax itself. Distinguish:
+
+- live shortcode calls that affect rendering
+- escaped shortcode examples intended for readers
+
+Common literal-example pattern:
+
+```text
+{{</* shortcode arg=value */>}}
+```
+
+When the construct is inside a fenced code block or otherwise clearly documentation, preserve it literally.
+
+Also preserve escaped forms such as these when they appear in prose or tables:
+
+```text
+{{%/* foo */%}}
+{{</* foo */>}}
+```
+
+Do not strip them just because they match a loose shortcode regex.
+
+## Step 6: Normalize front matter before building derived content
+
+Before using front matter to populate generated tables or lists:
+
+- map reserved keys case-insensitively, for example `Title` to `title`
+- treat `linkTitle` and `LinkTitle` as the same logical field
+- account for aliases such as `publishdate` or `modified`
+- account for front matter tokens such as `:filename` and `:fileModTime` when deciding whether metadata is derived
+- preserve unknown custom keys as-is
+
+This prevents empty links and missing descriptions when a repo mixes Hugo key casing conventions.
+
+## Step 7: Validate aggressively
+
+After each batch:
+
+```bash
+python3 skills/hugo-to-markdown/scripts/check_standard_markdown.py \
+  --root /path/to/output
+```
+
+Treat validator hits as unresolved work unless they are deliberate examples inside code fences.
+
+If you intentionally downgraded a shortcode to an explanatory note, that note should remain in the output and the original shortcode should not.