markdown-report-writing
Skill39 starsChanged 9 months agoMITView on GitHub
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.
In this repository49 other files it gives its agents.
- act-r-model-builderSkill
- alternative-uses-task-designerSkill
- bayesian-cognitive-model-builderSkill
- brain-connectivity-modelerSkill
- calcium-imaging-analysis-guideSkill
- cognitive-paradigm-designSkill
- cogsci-power-analysisSkill
- cogsci-statisticsSkill
- cogsci-visualizationSkill
- contribute-skillSkill
- contribute-skills-via-prSkill
- creativity-self-efficacy-mediationSkill
- deeplabcutSkill
- divergent-thinking-scoringSkill
- drift-diffusion-modelSkill
- eeg-paradigm-designerSkill
- eeg-preprocessing-pipeline-guideSkill
- erp-analysisSkill
- evidence-accumulation-selectorSkill
- fmri-glm-analysis-guideSkill
- fmri-preprocessing-pipeline-guideSkill
- fmriprepSkill
- fmri-task-design-guideSkill
- infant-looking-time-designerSkill
- lesion-symptom-mapping-guideSkill
- mne-python-guideSkill
- netneurotools-guideSkill
- neural-decoding-analysisSkill
- neural-population-analysis-guideSkill
- neuroimaging-power-guideSkill
- neuroimaging-sample-size-calculatorSkill
- neuropsych-battery-selectorSkill
- optogenetics-protocol-designerSkill
- paper-to-skillSkill
- parameter-recovery-checkerSkill
- pycortex-guideSkill
- reading-time-analysisSkill
- repo-to-skillSkill
- research-literacySkill
- self-paced-reading-designerSkill
- sentence-stimulus-normingSkill
- share-caseSkill
- share-usageSkill
- signal-detection-analysisSkill
- spikeinterface-skillSkill
- spiking-network-model-builderSkill
- tom-task-selectorSkill
- verify-skillSkill
- visual-search-array-generatorSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 12 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
When writing any Markdown report, think in three layers:
- Distinctive: line 22
Follow these rules for every report:
- Distinctive: line 37
After generating any report, verify:
- Distinctive: line 49
Start every report with this upgradeable structure:
- Distinctive: line 94
Always provide alt text. Use SVG for diagrams, PNG/WebP for screenshots:
- Distinctive: line 105
Use two-column Markdown tables as your grid system — this is the only approach that works reliably on both GitHub and Obsidian:
- Very specific: line 113
Avoid <div style="display:flex"> — styles get stripped on GitHub and block Markdown parsing on Obsidian.
- Very specific: line 117
Always use standard Markdown tables.
- Distinctive: line 128
Always declare the language for syntax highlighting:
- Distinctive: line 139
Use fenced code blocks — both GitHub and Obsidian render them natively:
- Distinctive: line 183
Use for citations, terminology, and data sources:
- Distinctive: line 195
Use when reporting project status, milestones, architecture decisions, risks, and next steps.
- Distinctive: line 203
Use when documenting experiments, A/B tests, benchmarks, or research findings.
- Distinctive: line 211
Use for repository introductions and project documentation.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
- 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.
- Enhancement layer — Add renderer-specific features only when necessary: GitHub
<details>folding, relative links; Obsidian[[wikilink]],![[embed]], Callout,cssclasses. - 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:
- 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).
- Relative paths for all assets — Place images, diagrams, and attachments in
assets/and reference them with relative paths. - 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
- GitHub: relative links, section anchors,
- 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. - Mermaid first for diagrams — GitHub and Obsidian both render Mermaid natively. For complex UML, generate PlantUML SVG first, then embed.
- Every figure needs alt text and a caption — Every code block must declare its language.
- 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:
---
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:

*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:
| Overview | Key Points |
|---|---|
|  | - 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 \|:
| 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:
```python
def evaluate(x: float) -> float:
return x ** 2 + 1
```Mermaid Diagrams
Use fenced code blocks — both GitHub and Obsidian render them natively:
```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:
Inline: $E = mc^2$
Block:
$$
\operatorname{F1} = \frac{2PR}{P+R}
$$Task Lists and Collapsible Sections
- [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:
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
# 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 revealjsFile & Asset Management
Organize project files with this directory structure:
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.ymlNaming 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:
- Lint Markdown —
markdownlint-cli2 "**/*.md" - Check TOC freshness —
doctoc --dryrun . - Check links —
lychee --verbose --no-progress "**/*.md" - 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  | ![[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 filesreferences/compatibility-matrix.md— Detailed compatibility table for GitHub vs Obsidian features
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

