docs: Add HTML authoring skill release artifact

Author: smcllns

.agents/SKILL.md

@@ -1,24 +1,32 @@
 ---
 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 — covers the context the plugin provides, sandbox constraints, asset rules, and the things that silently don't work.
+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
+# Obsidian HTML Docs authoring guide
 
-The plugin enables the user to view html files inside Obsidian, similar to md files. The plugin renders `.html` in a sandboxed iframe via Blob URL. The iframe is sealed (`sandbox="allow-scripts allow-popups allow-forms"`, no `allow-same-origin`) so it can't reach into Obsidian or the vault. Everything below works within that envelope.
+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's context — unless asked otherwise
+## Default to Obsidian context unless asked otherwise
 
-Before sealing the iframe, the plugin can prepend a `<style>` block to your HTML containing a snapshot of the user's current Obsidian design tokens. The iframe doesn't reach out for these values — they're written as static CSS into your document at load time, then the sandbox is applied. **Security boundary unchanged** (no `allow-same-origin`, no reads from the iframe back into Obsidian); the iframe just has a few extra CSS variables declared in its own document.
+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** (proposed plugin enhancement; today only `color-scheme: light dark` via OS preference works):
+Injected as static CSS:
 
 - A `color-scheme: light | dark` declaration matching the user's current Obsidian theme
-- A small set of `--obsidian-*` CSS variables holding snapshot values from the user's active Obsidian theme: `--obsidian-bg`, `--obsidian-bg-2`, `--obsidian-text`, `--obsidian-text-muted`, `--obsidian-accent`, `--obsidian-border`, `--obsidian-font`, `--obsidian-font-mono`
-
-**Graceful pattern** — use Obsidian tokens if present, fall back if not:
+- `--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 {
@@ -28,9 +36,9 @@ If the user just wants a styled doc that "fits" their vault, use these as your d
 }
 ```
 
-Today this CSS already follows OS light/dark via `prefers-color-scheme`. Once the plugin ships theme injection, the snapshot reflects the user's exact Obsidian theme — including custom themes and snippets — and your variable fallbacks resolve to those values automatically. No code change needed on the HTML side.
+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
+## 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.
 
@@ -80,15 +88,15 @@ See: [[my-doc.html]]
 ## Embed sizing
 
 ```markdown
-![[doc.html|width=600 height=400]]
+![[doc.html|600x400]]
 ```
 
-Sets `--html-docs-width` / `--html-docs-height` on the embed container. Default embed height is ~600px; tab views fill the pane.
+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** — usually true, sometimes not. Once the plugin ships theme injection, this is fully resolved.
+- **Assuming `prefers-color-scheme` == Obsidian theme** — use `--obsidian-color-scheme` or injected colors instead.

.agents/plans/2026-05-14-authoring-skill-release.md

@@ -0,0 +1,21 @@
+# 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.
+- [ ] Push PR branches.
+
+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 `~/.claude`, `~/.agents`, `~/.codex`, or dotfiles.
+
+Unresolved questions:
+- None.

.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

README.md

@@ -30,6 +30,12 @@ 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 authoring skill
+
+The plugin repo keeps the canonical source skill at `.agents/SKILL.md`, and releases include the same file as `dist/html-docs/SKILL.md` for reference. That file teaches agents how to author HTML that fits the plugin's sandbox, theme tokens, asset rules, and embed behavior.
+
+Installing or updating the Obsidian plugin does **not** automatically install an agent skill. Claude, Codex, and other agents discover skills from their own configured roots, not from `<vault>/.obsidian/plugins/html-docs/`. The installable mirror lives in [smcllns/skills](https://github.com/smcllns/skills) as `obsidian-html-docs`; install it with your agent's normal skill installer, or ask your agent to read the bundled `SKILL.md` and integrate the guidance into your workflow.
+
 ### Build and install from source
 
 ```bash

docs/handoffs/authoring-skill-release.md

@@ -0,0 +1,29 @@
+# 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.
+- `/Users/smcllns/Projects/agent-skills/skills/obsidian-html-docs/SKILL.md` mirrors the canonical skill.
+
+Important constraint:
+- Plugin runtime must not write to `~/.claude`, `~/.agents`, `~/.codex`, dotfiles, or any other agent install root. Agent skill activation belongs to the user's agent tooling, not the Obsidian plugin.
+
+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.

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 },