agentleFS
NeuroAIHubNeuroAIHub/awesome_cognitive_and_neuroscience_skills/skills/markdown-report-writing/SKILL.md

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.

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
  1. Distinctive:

    When writing any Markdown report, think in three layers:

    line 12
  2. Distinctive:

    Follow these rules for every report:

    line 22
  3. Distinctive:

    After generating any report, verify:

    line 37
  4. Distinctive:

    Start every report with this upgradeable structure:

    line 49
  5. Distinctive:

    Always provide alt text. Use SVG for diagrams, PNG/WebP for screenshots:

    line 94
  6. Distinctive:

    Use two-column Markdown tables as your grid system — this is the only approach that works reliably on both GitHub and Obsidian:

    line 105
  7. Very specific:

    Avoid <div style="display:flex"> — styles get stripped on GitHub and block Markdown parsing on Obsidian.

    line 113
  8. Very specific:

    Always use standard Markdown tables.

    line 117
  9. Distinctive:

    Always declare the language for syntax highlighting:

    line 128
  10. Distinctive:

    Use fenced code blocks — both GitHub and Obsidian render them natively:

    line 139
  11. Distinctive:

    Use for citations, terminology, and data sources:

    line 183
  12. Distinctive:

    Use when reporting project status, milestones, architecture decisions, risks, and next steps.

    line 195
  13. Distinctive:

    Use when documenting experiments, A/B tests, benchmarks, or research findings.

    line 203
  14. Distinctive:

    Use for repository introductions and project documentation.

    line 211

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

---
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:

![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:

| 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 \|:

| 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

GoalPrimary ToolAgent Should Output
Repo README / project reportPure GFM + Mermaid.md + assets/*.svg
Experiment report / PDF exportQuarto.qmd or enhanced .md → export HTML/PDF
Documentation siteMkDocs Materialdocs/ directory + nav config
DiagramsMermaid (first), PlantUML (UML)*.mmd / *.puml source + rendered *.svg
Math rendering on webMathJaxHTML site with math rendering layer
Local editing & exportTyporaPreview → export HTML/PDF
Slides / presentationQuarto 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 revealjs

File & 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.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

SituationGitHub ApproachObsidian Approach
Internal linksRelative paths (auto-branch-aware)[[wikilink]] or Markdown links
Embedding contentStandard ![alt](path)![[file.svg|700]]
Collapsible sections<details><summary> (safe)Heading folding or Callout
Custom stylingNot available in repo .mdCSS Snippets + cssclasses frontmatter
SlidesNot native--- separated slides in note
Dynamic viewsNot in repo .mdDataview 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.