Add markdown output, CSS-verbatim, and GitHub sharing

SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-deep-dive
-description: Research any topic within a GitHub repo and generate a polished HTML deep-dive document. Use when the user wants to learn about a codebase feature, understand architecture, onboard to a new area, or says "deep dive into ..." or "teach me about ...".
+description: Research any topic within a GitHub repo and generate a polished HTML deep-dive document or GitHub-native markdown for sharing via PRs and issues. Use when the user wants to learn about a codebase feature, understand architecture, onboard to a new area, or says "deep dive into ..." or "teach me about ...".
 triggers:
   - "deep dive into"
   - "teach me about"
@@ -9,11 +9,13 @@ triggers:
   - "onboard me to"
   - "explore the codebase"
   - "how does X work in repo"
+  - "post a deep dive on the PR"
+  - "share a deep dive with the team"
 ---
 
 # Deep-Dive Researcher
 
-Research a topic inside a GitHub repository and produce a self-contained HTML reference document. Works with any repo accessible via the `gh` CLI.
+Research a topic inside a GitHub repository and produce a reference document — either a self-contained HTML page (for polished local viewing) or GitHub-flavored markdown (for sharing via PRs, issues, and repos). Works with any repo accessible via the `gh` CLI.
 
 ## When to Use
 
@@ -22,6 +24,8 @@ Research a topic inside a GitHub repository and produce a self-contained HTML re
 - "I want to learn about the router in remix-run/remix"
 - "Generate a reference doc for the detection rules engine"
 - "Onboard me to [feature] in [repo]"
+- "Deep dive into X and post it on the PR"
+- "Create a deep-dive I can share with the team"
 
 ## Prerequisites
 
@@ -36,7 +40,15 @@ Ask the user three things conversationally (do not assume defaults without askin
 
 1. **Topic** — What do you want to learn about? (e.g., "Attack Discovery", "the router", "plugin lifecycle")
 2. **Repository** — Which GitHub repo? (e.g., `elastic/kibana`, `vercel/next.js`). If there is a local clone in the workspace, confirm that the user wants to use it.
-3. **Output directory** — Where to save the HTML file? Suggest `./deep-dives/` as the default.
+3. **Output directory** — Where to save the file? Suggest `./deep-dives/` as the default.
+
+**Output format** — Infer from the prompt. Do not ask unless ambiguous.
+
+| Signal in prompt | Format | Why |
+|---|---|---|
+| "post on the PR", "attach to the issue", "share with the team", "comment on", "add to the PR" | **Markdown** | Renders natively in GitHub PRs, issues, and repo files |
+| "reference page", "HTML doc", "polished doc", "open in browser" | **HTML** | Self-contained styled document for local viewing |
+| No signal either way | **HTML** (default) | At Step 5, mention markdown is available for sharing |
 
 ### Step 2: Research
 
@@ -102,11 +114,17 @@ Organize findings into the following sections. Skip sections that don't apply; a
 | **Related Issues & PRs** | Table of relevant GitHub activity with links |
 | **Further Reading** | Links to READMEs, external docs, related features |
 
-### Step 4: Generate HTML
+### Step 4: Generate Output
+
+Generate either HTML or markdown based on the format determined in Step 1.
+
+#### 4a. HTML format
 
 Read the template at `template.html` (in this skill's directory). It contains the full CSS and page structure with placeholder markers.
 
-Replace the placeholders with generated content:
+**CRITICAL: Copy the entire `<style>` block from `template.html` verbatim.** Do not modify, regenerate, "improve", or restyle the CSS. The only things you create are the content sections — everything else comes from the template unchanged. This prevents drift, saves tokens, and keeps output consistent.
+
+Replace only the placeholders with generated content:
 
 | Placeholder | Replace with |
 |-------------|-------------|
@@ -128,14 +146,77 @@ Replace the placeholders with generated content:
 - Keep the page self-contained — no external links for CSS/JS, no images.
 - Do NOT use placeholder markers literally in the output — replace every one.
 
-### Step 5: Save and offer
+#### 4b. Markdown format
+
+Generate GitHub-flavored markdown with the same content structure. This renders natively in PRs, issues, and repo files — no hosting required.
+
+**Markdown structure:**
+
+```markdown
+# {Title}
+
+> {Subtitle} — Generated {date} from [{repo}](https://github.com/{repo})
+
+## Table of Contents
+- [Overview](#overview)
+- [Architecture](#architecture)
+...
+
+## Overview
+{content}
+
+## Architecture
+{content — use mermaid code blocks for diagrams if appropriate}
+
+## Key Files & Directories
+| Path | Description |
+|------|-------------|
+| `path/to/file` | What it does |
+
+## How It Works
+{numbered steps}
+
+## Key Concepts & Types
+{content — use code blocks for type signatures}
+
+## Configuration & Setup
+{content}
+
+## Related Issues & PRs
+| # | Title | Status |
+|---|-------|--------|
+| [#123](url) | Title | Merged |
+
+## Further Reading
+- [Link text](url)
+
+---
+*Deep-dive reference for {topic} in {repo} — Generated {date}*
+```
+
+**Markdown guidelines:**
+- Use `##` for top-level sections, `###` for subsections
+- Use GFM tables (pipes) for structured data
+- Use fenced code blocks with language hints (```typescript, ```bash)
+- Use `> blockquote` for callouts (equivalent to summary-box in HTML)
+- Use mermaid code blocks for flow diagrams when the GitHub context supports it
+- All links must be full URLs (`https://github.com/owner/repo/...`)
+
+### Step 5: Save and share
 
 1. Create the output directory if it doesn't exist.
-2. Save the file as `<topic-kebab-case>-deep-dive.html` (e.g., `attack-discovery-deep-dive.html`).
-3. Tell the user the file path and offer:
-   - Open it in the browser to review
+2. Save with the appropriate extension:
+   - HTML: `<topic-kebab-case>-deep-dive.html`
+   - Markdown: `<topic-kebab-case>-deep-dive.md`
+3. **If markdown and the user mentioned a PR or issue**, offer to post it directly:
+   - PR comment: `gh pr comment <number> --repo owner/name --body-file <path>`
+   - Commit to branch: `git add <path> && git commit -m "Add deep-dive: <topic>"`
+4. Tell the user the file path and offer:
+   - Open to review
    - Refine or expand specific sections
    - Add more detail on a particular area
+   - **If HTML was generated**: "Want a markdown version for sharing on GitHub?"
+   - **If markdown was generated**: "Want an HTML version for polished local viewing?"
 
 ## Security: Handling Untrusted Content