@brainpilot/skills 0.0.6

package/skills/13_Visualization/nature-figure/static/fragments/backend/python.md

@@ -0,0 +1,37 @@
+# Backend: Python (matplotlib / seaborn)
+
+**Python-only execution rule.** When the user has selected Python, do all figure drawing, previewing, exporting, and visual QA in Python. Do not call R/ggplot2, ComplexHeatmap, patchwork, or any R graphics device to create a temporary preview, fallback export, or layout approximation. If Python or required Python plotting packages are missing, stop before rendering and report the missing dependency. You may still write the Python script, provide `pip`/environment install commands, or ask permission to install dependencies, but do not cross-render the figure in R.
+
+## Python quick-start
+
+```python
+import matplotlib as mpl
+import matplotlib.pyplot as plt
+
+mpl.rcParams.update({
+    "font.family": "sans-serif",
+    "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans", "sans-serif"],
+    "svg.fonttype": "none",     # editable text in SVG
+    "pdf.fonttype": 42,         # editable TrueType text in PDF
+    "font.size": 7,             # use 15-24 only for large slide-sized panels
+    "axes.spines.right": False,
+    "axes.spines.top": False,
+    "axes.linewidth": 0.8,
+    "legend.frameon": False,
+})
+
+def save_pub_py(fig, filename, dpi=600):
+    fig.savefig(f"{filename}.svg", bbox_inches="tight")
+    fig.savefig(f"{filename}.pdf", bbox_inches="tight")
+    fig.savefig(f"{filename}.tiff", dpi=dpi, bbox_inches="tight")
+```
+
+Use `text.usetex = True` only when LaTeX is installed and math-rich labels are required.
+
+## Going deeper
+
+- `references/api.md` — Python PALETTE, helper function signatures, validation rules.
+- `references/common-patterns.md` — hero panels, legend-only axes, dark image plates, asymmetric layouts.
+- `references/chart-types.md` — radar, 3D sphere, fill_between, scatter patterns.
+- `references/tutorials.md` — end-to-end walkthroughs for bars, trends, heatmaps.
+- `references/demos.md` — bundled figures4papers Python scripts and output previews.

package/skills/13_Visualization/nature-figure/static/fragments/backend/r.md

@@ -0,0 +1,44 @@
+# Backend: R (ggplot2 / patchwork / ComplexHeatmap)
+
+**R-only execution rule.** When the user has selected R, do all figure drawing, previewing, exporting, and visual QA in R. Do not call matplotlib/seaborn or any Python graphics device to create a temporary preview, fallback export, or layout approximation. If `Rscript`/R or required R packages are missing, stop before rendering and report the exact blocker. You may still write the R script, provide install commands (for example `install.packages(...)`), or ask permission to install dependencies, but do not cross-render the figure in Python.
+
+## R quick-start
+
+```r
+library(ggplot2)
+library(patchwork)
+
+theme_set(
+  theme_classic(base_size = 6.5, base_family = "Arial") +
+    theme(
+      axis.line = element_line(linewidth = 0.35, colour = "black"),
+      axis.ticks = element_line(linewidth = 0.35, colour = "black"),
+      legend.title = element_text(size = 6.2),
+      legend.text = element_text(size = 5.8),
+      strip.text = element_text(size = 6.2, face = "bold"),
+      plot.title = element_text(size = 7, face = "bold"),
+      panel.grid = element_blank()
+    )
+)
+
+save_pub_r <- function(plot, filename, width_mm = 183, height_mm = 120, dpi = 600) {
+  w <- width_mm / 25.4
+  h <- height_mm / 25.4
+  svglite::svglite(paste0(filename, ".svg"), width = w, height = h)
+  print(plot)
+  dev.off()
+  grDevices::cairo_pdf(paste0(filename, ".pdf"), width = w, height = h, family = "Arial")
+  print(plot)
+  dev.off()
+  ragg::agg_tiff(paste0(filename, ".tiff"), width = w, height = h, units = "in", res = dpi)
+  print(plot)
+  dev.off()
+}
+```
+
+## Going deeper
+
+- `references/r-workflow.md` — the R plotting workflow when the user provides R scripts, templates, or data.
+- `references/r-template-index.md` — adapt a user-provided or private R template collection without exposing source paths.
+- `references/design-theory.md` — typography, color theory, layout rationale, export policy (backend-agnostic).
+- `references/nature-2026-observations.md` — real Nature page archetypes to match before choosing layout.

package/skills/14_Writing/markdown-report-writing/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: markdown-report-writing
+description: Guide AI agents to write beautifully formatted, well-illustrated Markdown reports with proper structure, diagrams, and compatibility across GitHub and Obsidian. Use this skill whenever the user asks you to write a report, project documentation, experiment report, README, technical document, or any long-form Markdown content. Also trigger when users mention Markdown formatting, Mermaid diagrams, report templates, or document publishing.
+---
+
+# Markdown Report Writing
+
+Provide expert guidance for writing professional, visually polished Markdown reports that render correctly on both GitHub and Obsidian.
+
+## Core Philosophy: Three-Layer Writing Model
+
+When writing any Markdown report, think in three layers:
+
+1. **Content layer** — Use CommonMark / GFM + Obsidian shared syntax for all headings, paragraphs, lists, images, tables, code blocks, footnotes, task lists, math ($\LaTeX$), and Mermaid diagrams. This is your foundation.
+2. **Enhancement layer** — Add renderer-specific features only when necessary: GitHub `<details>` folding, relative links; Obsidian `[[wikilink]]`, `![[embed]]`, Callout, `cssclasses`.
+3. **Build layer** — For complex layouts, table of contents generation, site styling, and slide exports, delegate to Pandoc / Quarto / MkDocs / GitHub Pages.
+
+This ensures your output is readable, portable, automatable, and version-controllable across all target environments.
+
+## Writing Principles
+
+Follow these rules for every report:
+
+1. **Shared syntax first** — Build the body with syntax that works on both GitHub and Obsidian (headings, links, images, tables, code blocks, footnotes, task lists, Mermaid, math).
+2. **Relative paths for all assets** — Place images, diagrams, and attachments in `assets/` and reference them with relative paths.
+3. **Enhance per target** — After the core is solid, add renderer-specific enhancements:
+   - **GitHub**: relative links, section anchors, `<details>`, Mermaid
+   - **Obsidian**: wikilink, embed, callout, cssclasses
+   - **Web/PDF/Slides**: delegate to Pandoc / Quarto / MkDocs
+4. **Don't nest Markdown in HTML** — GitHub strips custom HTML attributes; Obsidian won't parse Markdown inside HTML blocks. Use Markdown tables for side-by-side layouts instead of `<div>` flexboxes.
+5. **Mermaid first for diagrams** — GitHub and Obsidian both render Mermaid natively. For complex UML, generate PlantUML SVG first, then embed.
+6. **Every figure needs alt text and a caption** — Every code block must declare its language.
+7. **Every long document must have**: executive summary, table of contents (or equivalent navigation), figures with captions, and a conclusion / next-steps section.
+
+## Quality Checklist
+
+After generating any report, verify:
+
+- [ ] All code blocks have language identifiers
+- [ ] All images have alt text and captions
+- [ ] All links use relative paths (no absolute paths to local files)
+- [ ] Table of contents is present (for documents with 3+ sections)
+- [ ] Mermaid diagrams render correctly
+- [ ] Footnotes are properly paired (marker + definition)
+- [ ] No complex Markdown trapped inside HTML blocks
+
+## Standard Document Skeleton
+
+Start every report with this upgradeable structure:
+
+```md
+---
+title: Project Name
+author: Team / Agent Name
+date: YYYY-MM-DD
+tags: [tag1, tag2]
+---
+
+# Project Name
+
+> One-line summary: what problem this solves and what the conclusion is.
+
+## Executive Summary
+
+3-6 sentences covering background, approach, results, and conclusions.
+
+## Background
+
+Problem statement, context, and boundaries.
+
+## Methods / Approach
+
+Solution design, workflow, data, experimental conditions.
+
+## Results
+
+- Key finding A
+- Key finding B
+- Key finding C
+
+## Conclusion / Next Steps
+
+## Appendix & References
+
+- [Raw data](./data/raw.csv)
+- [Diagrams](./assets/fig-overview.svg)
+- [Supplementary docs](./docs/appendix.md)
+```
+
+## Layout & Typesetting Techniques
+
+### Images and Figures
+
+Always provide alt text. Use SVG for diagrams, PNG/WebP for screenshots:
+
+```md
+![System architecture diagram](./assets/fig-system-architecture.svg)
+*Figure: Overall system architecture.*
+
+[View full-size SVG](./assets/fig-system-architecture.svg)
+```
+
+### Side-by-Side Layout (Cross-Platform Safe)
+
+Use **two-column Markdown tables** as your grid system — this is the only approach that works reliably on both GitHub and Obsidian:
+
+```md
+| Overview | Key Points |
+|---|---|
+| ![System overview](./assets/fig-overview.svg) | - 4 modules<br>- 12 interfaces<br>- Risk: data sync |
+```
+
+Avoid `<div style="display:flex">` — styles get stripped on GitHub and block Markdown parsing on Obsidian.
+
+### Tables
+
+Always use standard Markdown tables. Escape `|` inside cells with `\|`:
+
+```md
+| Metric | Value | Notes |
+|:--|--:|:--|
+| Accuracy | 92.4% | Main model |
+| Link to doc | [Appendix](./docs/appendix.md) | See details |
+```
+
+### Code Blocks
+
+Always declare the language for syntax highlighting:
+
+```md
+​```python
+def evaluate(x: float) -> float:
+    return x ** 2 + 1
+​```
+```
+
+### Mermaid Diagrams
+
+Use fenced code blocks — both GitHub and Obsidian render them natively:
+
+```md
+​```mermaid
+flowchart LR
+    Data[Data Input] --> Clean[Cleaning]
+    Clean --> Analyze[Analysis]
+    Analyze --> Report[Report Output]
+​```
+```
+
+### Math Expressions
+
+Both GitHub and Obsidian support $\LaTeX$ via MathJax:
+
+```md
+Inline: $E = mc^2$
+
+Block:
+$$
+\operatorname{F1} = \frac{2PR}{P+R}
+$$
+```
+
+### Task Lists and Collapsible Sections
+
+```md
+- [x] Requirements confirmed
+- [x] Data collected
+- [ ] Charts reviewed
+- [ ] Document published
+
+<details>
+<summary>Click to expand technical details</summary>
+
+Keep content here plain text or simple HTML.
+Avoid complex Markdown (lists, tables, formulas) inside
+if the target includes Obsidian.
+
+</details>
+```
+
+### Footnotes
+
+Use for citations, terminology, and data sources:
+
+```md
+There is a term that needs explanation[^term].
+
+[^term]: This is where the explanation or citation goes.
+```
+
+## Report Templates
+
+### 1. Project Report
+
+Use when reporting project status, milestones, architecture decisions, risks, and next steps.
+
+Required sections: Executive Summary → Background → Scope → Architecture & Design → Current Progress → Risks & Mitigation → Conclusion & Next Steps → Appendix.
+
+Include: a system architecture diagram (Mermaid), a progress table with status per task, a risk matrix table, and a task checklist for next steps.
+
+### 2. Experiment Report
+
+Use when documenting experiments, A/B tests, benchmarks, or research findings.
+
+Required sections: Executive Summary → Research Questions & Hypotheses → Experimental Setup → Variables → Procedure → Results → Discussion → Reproducibility → Conclusion.
+
+Include: an environment/config table, a variables table (independent, dependent, controlled), a results comparison table, a results chart, and links to scripts/configs/raw data for reproducibility.
+
+### 3. README
+
+Use for repository introductions and project documentation.
+
+Required sections: Project Name & tagline → Quick-start links → Description → Features → Project Structure → Quick Start (install, run, example) → Usage (with Mermaid flow) → Documentation links → Roadmap → Contributing → License.
+
+See `references/templates.md` for full expanded templates with annotations.
+
+## Choosing Tools for the Job
+
+| Goal | Primary Tool | Agent Should Output |
+|---|---|---|
+| Repo README / project report | Pure GFM + Mermaid | `.md` + `assets/*.svg` |
+| Experiment report / PDF export | Quarto | `.qmd` or enhanced `.md` → export HTML/PDF |
+| Documentation site | MkDocs Material | `docs/` directory + nav config |
+| Diagrams | Mermaid (first), PlantUML (UML) | `*.mmd` / `*.puml` source + rendered `*.svg` |
+| Math rendering on web | MathJax | HTML site with math rendering layer |
+| Local editing & export | Typora | Preview → export HTML/PDF |
+| Slides / presentation | Quarto Revealjs or Pandoc | `.qmd` or `.md` → rendered slides |
+
+### Rendering Commands
+
+```bash
+# Mermaid → SVG
+mmdc -i diagrams/flow.mmd -o assets/flow.svg
+
+# PlantUML → SVG
+java -jar plantuml.jar --svg diagrams/architecture.puml
+
+# Pandoc → HTML / PDF / Revealjs
+pandoc report.md -o report.html
+pandoc report.md -o report.pdf
+pandoc -t revealjs -s slides.md -o slides.html
+
+# Quarto → HTML / Website / Revealjs
+quarto render report.qmd --to html
+quarto render report.qmd --to pdf
+quarto render slides.qmd --to revealjs
+```
+
+## File & Asset Management
+
+Organize project files with this directory structure:
+
+```text
+project/
+├── README.md
+├── reports/
+│   ├── project-report.md
+│   └── experiment-report.md
+├── docs/
+│   ├── index.md
+│   └── appendix.md
+├── assets/
+│   ├── figures/
+│   │   ├── fig-system-architecture.svg
+│   │   └── fig-results-comparison.svg
+│   ├── screenshots/
+│   │   └── screenshot-dashboard-home.png
+│   └── generated/
+│       ├── flow-overview.svg
+│       └── gantt-plan.svg
+├── diagrams/
+│   ├── flow-overview.mmd
+│   └── architecture.puml
+├── data/
+│   ├── raw/
+│   └── processed/
+└── .github/workflows/
+    └── docs-check.yml
+```
+
+**Naming conventions**: lowercase, hyphen-separated, semantic prefixes (`fig-` for figures, `tbl-` for tables, `exp-` for experiment data, `shot-` for screenshots, `flow-` for flowcharts). Keep both **source files** (`*.mmd`, `*.puml`) and **derived files** (`*.svg`) for version control and CI regeneration.
+
+## CI Quality Pipeline
+
+Include these 4 checks for long-lived documentation:
+
+1. **Lint Markdown** — `markdownlint-cli2 "**/*.md"`
+2. **Check TOC freshness** — `doctoc --dryrun .`
+3. **Check links** — `lychee --verbose --no-progress "**/*.md"`
+4. **Render diagrams** — `mmdc -i diagrams/*.mmd -o assets/generated/`
+
+## Quick Reference: Per-Environment Differences
+
+| Situation | GitHub Approach | Obsidian Approach |
+|---|---|---|
+| Internal links | Relative paths (auto-branch-aware) | `[[wikilink]]` or Markdown links |
+| Embedding content | Standard `![alt](path)` | `![[file.svg\|700]]` |
+| Collapsible sections | `<details><summary>` (safe) | Heading folding or Callout |
+| Custom styling | Not available in repo `.md` | CSS Snippets + `cssclasses` frontmatter |
+| Slides | Not native | `---` separated slides in note |
+| Dynamic views | Not in repo `.md` | Dataview plugin queries |
+
+## References
+
+- `references/templates.md` — Full annotated templates for project reports, experiment reports, and README files
+- `references/compatibility-matrix.md` — Detailed compatibility table for GitHub vs Obsidian features

package/skills/14_Writing/markdown-report-writing/references/compatibility-matrix.md

@@ -0,0 +1,72 @@
+# GitHub Markdown vs Obsidian Compatibility Matrix
+
+This reference covers which features work on each platform and the recommended approach for cross-platform documents.
+
+## Quick Decision Table
+
+| Feature | GitHub | Obsidian | Cross-Platform Recommendation |
+|---|---|---|---|
+| Headings, lists, quotes, code blocks | Full | Full | Always use; the minimum shared subset |
+| Internal links | Relative paths (branch-aware) | `[[wikilink]]`, Markdown links, heading/block refs | Use Markdown relative links for cross-platform; `[[wikilink]]` only for Obsidian-only notes |
+| Images & SVG | PNG/JPG/GIF/SVG supported; SVG no scripts/animations | `.svg` + image embed supported | Diagrams → SVG; screenshots → PNG/WebP |
+| Footnotes | Full | Full | Use for citations, terminology, data sources |
+| Task lists | Clickable checkboxes | Native task lists | Use for TODOs, checklists, release checklists |
+| Tables | Full | Full (escape `\|` in cells) | Use standard Markdown tables; no complex cell styling |
+| Mermaid diagrams | Native rendering | Native support | Primary diagram language for agents; use fenced code blocks |
+| Math ($\LaTeX$) | MathJax-based | MathJax-based | Safe to use both inline and block formulas |
+| Collapsible content | `<details><summary>` works | HTML supported but Markdown won't parse inside HTML | GitHub: use `<details>`; Obsidian: use heading folding or Callout |
+| Raw HTML | Supported but aggressively sanitized (no `script`, inline `style`, `class`, `id`) | Supported but sanitized; Markdown not parsed inside HTML | Only for minimal structural patches; never for complex layouts |
+| Custom CSS | Not available in repo `.md` pages | CSS Snippets + `cssclasses` frontmatter | GitHub = content source; Obsidian/HTML site = style layer |
+| Slides/presentation | Not native in repo `.md` | Obsidian Slides (`---` page separators) | Export via Quarto Revealjs, Pandoc, or Obsidian Slides |
+| Dynamic views | Not in repo `.md` | Dataview plugin queries | Obsidian vault enhancement only |
+
+## Key Compatibility Rules
+
+### 1. HTML Sanitization
+
+**GitHub** strips: `script`, inline `style`, `class`, `id`, and other potentially abusable attributes from HTML in Markdown.
+
+**Obsidian** sanitizes HTML AND does not continue parsing Markdown inside HTML elements.
+
+**Result**: Never put complex Markdown (lists, tables, code blocks, math) inside HTML containers. Use native Markdown constructs instead.
+
+### 2. Side-by-Side Layout
+
+**Do NOT use**:
+```html
+<div style="display:flex">
+  <div>![img](a.svg)</div>
+  <div>Some text</div>
+</div>
+```
+
+**Use instead** (cross-platform safe):
+```md
+| Diagram | Description |
+|---|---|
+| ![img](./assets/a.svg) | - Point 1<br>- Point 2 |
+```
+
+### 3. Collapsible Sections
+
+**GitHub**: `<details><summary>Title</summary>...content...</details>` works well.
+
+**Obsidian**: HTML is supported but Markdown inside won't parse. Use Callout blocks or heading-based folding instead.
+
+**Cross-platform**: If you must use `<details>`, keep the content as plain text or simple HTML. Avoid nesting Markdown lists, tables, or code blocks inside.
+
+### 4. Links Strategy
+
+- Cross-platform text: Use **Markdown relative links** `[text](./path/file.md)`
+- Obsidian-only: Use `[[wikilink]]` and `![[embed]]`
+- GitHub: Relative links auto-adapt to the current branch
+
+### 5. Styling Strategy
+
+- GitHub repo `.md`: cannot inject custom CSS
+- Obsidian: use CSS Snippets (`.obsidian/snippets/`) + `cssclasses` frontmatter
+- Exported HTML/sites: add CSS at the site level (Pandoc, Quarto, MkDocs)
+
+## Bottom Line
+
+When in doubt, use **pure CommonMark/GFM syntax** (headings, links, images, tables, code blocks, footnotes, task lists, Mermaid, math). It renders correctly on both platforms and migrates cleanly to any export format.