From 602842d93714c4bdc8de23bb75f006dae2ec14a7 Mon Sep 17 00:00:00 2001
From: Sam Collins <81678+smcllns@users.noreply.github.com>
Date: Thu, 14 May 2026 18:21:48 -0700
Subject: [PATCH] docs: Add HTML authoring skill release artifact

---
 .agents/SKILL.md                              | 102 ++++++++++++++++++
 .../2026-05-14-authoring-skill-release.md     |  24 +++++
 .github/workflows/release.yml                 |   2 +
 README.md                                     |   7 ++
 docs/handoffs/authoring-skill-release.md      |  31 ++++++
 esbuild.config.mjs                            |   1 +
 6 files changed, 167 insertions(+)
 create mode 100644 .agents/SKILL.md
 create mode 100644 .agents/plans/2026-05-14-authoring-skill-release.md
 create mode 100644 docs/handoffs/authoring-skill-release.md

diff --git a/.agents/SKILL.md b/.agents/SKILL.md
new file mode 100644
index 0000000..eb766a9
--- /dev/null
+++ b/.agents/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: obsidian-html-docs
+description: Author HTML files for the Obsidian HTML Docs plugin (smcllns/obsidian-plugin-html-docs). Use when creating .html docs intended to render inline in Obsidian: theme tokens, sandbox constraints, asset rules, embed sizing, and things that silently do not work.
+---
+
+# Obsidian HTML Docs authoring guide
+
+The HTML Docs plugin lets users view `.html` files inside Obsidian tabs, markdown embeds, and Canvas cards. It renders each file in a sandboxed iframe via Blob URL. The iframe is sealed (`sandbox="allow-scripts allow-popups allow-forms"`, no `allow-same-origin`) so it cannot reach into Obsidian or the vault. Everything below works within that envelope.
+
+## Default to Obsidian context unless asked otherwise
+
+Before creating the Blob URL, the plugin appends a `<style data-html-docs-theme>` block to your HTML containing a snapshot of the user's current Obsidian design tokens. The iframe does not reach out for these values. They are written as static CSS into your document at load time, then the sandboxed iframe loads that document. **Security boundary unchanged**: no `allow-same-origin`, no reads from the iframe back into Obsidian.
+
+If the user just wants a styled doc that "fits" their vault, use these as your defaults. If they're asking for a specific aesthetic (brutalist poster, retro terminal, Linear-style, an exact brand palette), design freely — Obsidian context is a *hint*, not a constraint.
+
+Injected as static CSS:
+
+- A `color-scheme: light | dark` declaration matching the user's current Obsidian theme
+- `--obsidian-color-scheme`
+- `--obsidian-bg`
+- `--obsidian-bg-2`
+- `--obsidian-text`
+- `--obsidian-text-muted`
+- `--obsidian-accent`
+- `--obsidian-border`
+- `--obsidian-font`
+- `--obsidian-font-mono`
+
+Use Obsidian tokens if present, fall back if not:
+
+```css
+:root {
+  color-scheme: light dark;
+  --bg:   var(--obsidian-bg,   light-dark(#ffffff, #0e1014));
+  --text: var(--obsidian-text, light-dark(#16161a, #e7e9ec));
+}
+```
+
+Open HTML tabs and embeds re-render when the Obsidian theme changes, so the injected snapshot follows theme switches.
+
+## Assets: vault paths do not cross into the iframe
+
+The iframe has no base URL pointing into the vault. Obsidian themes, snippets, and `attachments/...` images don't reach the iframe.
+
+| Pattern | Works? |
+|---|---|
+| `<img src="attachments/foo.png">` | No — fails silently |
+| `<img src="data:image/png;base64,...">` | Yes — fully self-contained |
+| `<img src="https://example.com/foo.png">` | Yes — CORS permitting |
+| Inline `<svg>...</svg>` | Yes — best for icons / diagrams |
+| `<link rel="stylesheet" href="https://cdn...">` | Yes — HTTPS only |
+
+Rules of thumb:
+
+- Small graphics & icons → inline SVG or `data:` URL
+- Photos / large images → upload to a host (R2, CDN) and reference HTTPS
+- Fonts → system stack, or HTTPS CDN
+- Never reference `attachments/` or any vault path — the iframe can't see them
+
+## What works
+
+- HTML / CSS (grid, `light-dark()`, custom properties, animations, gradients, SVG with CSS animations)
+- JavaScript (ES2020+, fetch with CORS, Promises, DOM events, requestAnimationFrame, Canvas 2D)
+- Forms (`allow-forms` is set; intercept `submit` if you don't want navigation)
+- `window.parent.postMessage(msg, '*')` — works even with opaque origin
+- External HTTPS resources (images, fonts on CDNs, fetch APIs that allow CORS)
+- Anchor links (`#section`) and the History API — Blob URL preserves both
+
+## What's blocked
+
+- `localStorage`, `sessionStorage`, `IndexedDB` — `SecurityError`
+- `document.cookie` — throws or silently no-ops
+- Reading `window.parent.*` — cross-origin (postMessage still works)
+- Service workers, geolocation, clipboard, notifications, most permission-gated APIs
+- Top-level navigation from inside the iframe (no `allow-top-navigation`)
+- Vault-relative URLs (see Assets above)
+
+## Linking from markdown to HTML
+
+Wikilinks to `.html` files need the explicit extension:
+
+```markdown
+See: [[my-doc.html]]
+```
+
+`[[my-doc]]` won't resolve to `.html` in stock Obsidian.
+
+## Embed sizing
+
+```markdown
+![[doc.html|600x400]]
+```
+
+Sets the embed width and height. Default markdown embed height is about 600px; tab views fill the pane.
+
+## Pitfalls (skip the turn cost)
+
+- **Theme scripts that read `window.parent`** — always throw under this plugin's sandbox. Don't write them.
+- **Images via `attachments/foo.png`** — won't resolve. Inline as data URL or use HTTPS.
+- **`localStorage` / cookies for state** — blocked. Use URL hash or postMessage to parent.
+- **Hard-coding a palette when Obsidian tokens are available** — defeats the contextual fit. Use `var(--obsidian-*)` with `light-dark()` fallbacks.
+- **Assuming `prefers-color-scheme` == Obsidian theme** — use `--obsidian-color-scheme` or injected colors instead.
diff --git a/.agents/plans/2026-05-14-authoring-skill-release.md b/.agents/plans/2026-05-14-authoring-skill-release.md
new file mode 100644
index 0000000..1610b25
--- /dev/null
+++ b/.agents/plans/2026-05-14-authoring-skill-release.md
@@ -0,0 +1,24 @@
+# HTML Docs authoring skill release
+
+Scope:
+- [x] Sync `main` to merged PR #8.
+- [x] Rebase PR #7 branch onto theme-token work.
+- [x] Update canonical `.agents/SKILL.md` for real theme-token injection.
+- [x] Bundle `SKILL.md` into `dist/html-docs/` during build.
+- [x] Include bundled `SKILL.md` in release upload/provenance.
+- [x] Clarify README optional agent-skill install/discovery.
+- [x] Mirror skill to `smcllns/skills`.
+- [x] Run build/lint/test checks.
+- [x] Push PR branches.
+- [x] Merge `smcllns/skills` mirror first so PR #7 docs can point at a real install URL.
+- [x] Add `skills.sh` install command to README.
+
+Decisions:
+- Plugin repo is canonical source.
+- `smcllns/skills` is the installable mirror.
+- Obsidian plugin install does not install agent skills.
+- Plugin runtime must not write to agent install roots or dotfiles.
+- Merge/install order matters: public skills mirror first, plugin docs/release second.
+
+Unresolved questions:
+- None.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 2631d9d..a4012bc 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -38,6 +38,7 @@ jobs:
           subject-path: |
             dist/html-docs/main.js
             dist/html-docs/manifest.json
+            dist/html-docs/SKILL.md
             dist/html-docs/styles.css
 
       - name: Create GitHub Release
@@ -50,4 +51,5 @@ jobs:
             --generate-notes \
             dist/html-docs/main.js \
             dist/html-docs/manifest.json \
+            dist/html-docs/SKILL.md \
             dist/html-docs/styles.css
diff --git a/README.md b/README.md
index 385e720..e908755 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,13 @@ A demo page (`test/fixture.html`) demonstrates all the passing HTML features.
 
 Releases are built and signed by GitHub Actions ([.github/workflows/release.yml](.github/workflows/release.yml)) so the binaries carry a [build attestation](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds) you can verify against the source.
 
+### Optional Agent Skill
+
+There is an optional agent skill so your agent can author HTML that fits this plugin's sandbox, theme tokens, assets, and embeds.
+
+- Skills CLI: `npx skills add smcllns/skills --skill obsidian-html-docs`
+- Manual: [smcllns/skills/skills/obsidian-html-docs/SKILL.md](https://github.com/smcllns/skills/blob/main/skills/obsidian-html-docs/SKILL.md)
+
 ### Build and install from source
 
 ```bash
diff --git a/docs/handoffs/authoring-skill-release.md b/docs/handoffs/authoring-skill-release.md
new file mode 100644
index 0000000..36b44ca
--- /dev/null
+++ b/docs/handoffs/authoring-skill-release.md
@@ -0,0 +1,31 @@
+# Authoring Skill Release Handoff
+
+Goal:
+- Finish PR #7 as a small follow-up to merged PR #8.
+- Make the HTML authoring skill useful after theme-token injection shipped.
+- Be honest that Obsidian plugin installs do not activate agent skills.
+
+Implemented shape:
+- `.agents/SKILL.md` is the canonical source copy in this plugin repo.
+- `esbuild.config.mjs` copies `.agents/SKILL.md` to `dist/html-docs/SKILL.md`.
+- The release workflow uploads and attests `dist/html-docs/SKILL.md` alongside runtime files.
+- README has an optional agent-skill note explaining discovery roots and the `smcllns/skills` mirror.
+- `smcllns/skills` mirrors the canonical skill at `skills/obsidian-html-docs/SKILL.md`.
+- `smcllns/skills` PR #1 was merged first so README can point to the real `skills.sh` install URL.
+
+Important constraint:
+- Plugin runtime must not write to agent install roots, dotfiles, or any other user-level configuration. Agent skill activation belongs to the user's agent tooling, not the Obsidian plugin.
+- Merge order matters: public skills mirror first, then plugin docs/release work.
+
+Verification target:
+- `bun run build`
+- `bun run lint`
+- `bun run test`
+- Confirm `dist/html-docs/SKILL.md` matches `.agents/SKILL.md`.
+
+Current verification:
+- `bun run build` passed.
+- `bun run lint` passed.
+- `bun run test` passed against live Obsidian.
+- `.agents/SKILL.md`, generated `dist/html-docs/SKILL.md`, and the `smcllns/skills` mirror match.
+- Haiku critical review found one stale `light-dark()` wording mismatch; fixed by keeping `light-dark()` in the supported CSS list.
diff --git a/esbuild.config.mjs b/esbuild.config.mjs
index 1f44dc7..70ba133 100644
--- a/esbuild.config.mjs
+++ b/esbuild.config.mjs
@@ -16,6 +16,7 @@ const distDir = path.join("dist", "html-docs");
 fs.mkdirSync(distDir, { recursive: true });
 fs.copyFileSync("manifest.json", path.join(distDir, "manifest.json"));
 fs.copyFileSync("styles.css", path.join(distDir, "styles.css"));
+fs.copyFileSync(path.join(".agents", "SKILL.md"), path.join(distDir, "SKILL.md"));
 
 const context = await esbuild.context({
 	banner: { js: banner },