Agent skill
ggterm-markdown
Generate markdown reports with embedded ggterm visualizations. Use when creating analysis reports, documenting results, exporting findings, or when the user wants plots in markdown format for sharing or documentation.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/ggterm-markdown
SKILL.md
Markdown Reports with ggterm
Generate analysis reports with embedded terminal visualizations and reproducible plot specifications.
Report Structure
A well-structured analysis report includes:
- Title and Overview - What was analyzed and why
- Data Summary - Shape, columns, key statistics
- Visualizations - Embedded plots with interpretations
- Findings - Key insights from the analysis
- Appendix - Plot specifications for reproducibility
Basic Report Template
typescript
import { gg, geom_point, geom_line } from '@ggterm/core'
import { writeFileSync } from 'fs'
// Create plots
const scatterPlot = gg(data)
.aes({ x: 'x', y: 'y', color: 'category' })
.geom(geom_point())
.labs({ title: 'Relationship Analysis' })
const trendPlot = gg(data)
.aes({ x: 'time', y: 'value' })
.geom(geom_line())
.labs({ title: 'Trend Over Time' })
// Render plots to strings
const scatter = scatterPlot.render({ width: 72, height: 18 })
const trend = trendPlot.render({ width: 72, height: 18 })
// Build markdown report
const report = `# Analysis Report: ${datasetName}
## Overview
This report analyzes ${data.length} observations across ${Object.keys(data[0]).length} variables.
## Data Summary
| Metric | Value |
|--------|-------|
| Rows | ${data.length} |
| Columns | ${Object.keys(data[0]).length} |
| Date Range | ${minDate} to ${maxDate} |
## Visualizations
### Scatter Plot
\`\`\`
${scatter}
\`\`\`
**Interpretation**: The scatter plot shows [describe the relationship observed].
### Trend Analysis
\`\`\`
${trend}
\`\`\`
**Interpretation**: The trend indicates [describe the pattern observed].
## Key Findings
1. **Finding 1**: Description of first key insight
2. **Finding 2**: Description of second key insight
3. **Finding 3**: Description of third key insight
## Appendix: Plot Specifications
<details>
<summary>Scatter Plot Spec (JSON)</summary>
\`\`\`json
${JSON.stringify(scatterPlot.spec(), null, 2)}
\`\`\`
</details>
<details>
<summary>Trend Plot Spec (JSON)</summary>
\`\`\`json
${JSON.stringify(trendPlot.spec(), null, 2)}
\`\`\`
</details>
---
*Generated with ggterm*
`
writeFileSync('analysis-report.md', report)
console.log('Report saved to analysis-report.md')
Embedding Multiple Plots
For reports with many visualizations:
typescript
interface PlotSection {
title: string
plot: GGPlot
interpretation: string
}
function generateReport(
title: string,
overview: string,
sections: PlotSection[],
findings: string[]
): string {
const plotSections = sections.map(({ title, plot, interpretation }) => `
### ${title}
\`\`\`
${plot.render({ width: 72, height: 16 })}
\`\`\`
**Interpretation**: ${interpretation}
`).join('\n')
const findingsList = findings
.map((f, i) => `${i + 1}. ${f}`)
.join('\n')
const specs = sections.map(({ title, plot }) => `
<details>
<summary>${title} Spec</summary>
\`\`\`json
${JSON.stringify(plot.spec(), null, 2)}
\`\`\`
</details>
`).join('\n')
return `# ${title}
## Overview
${overview}
## Visualizations
${plotSections}
## Key Findings
${findingsList}
## Appendix: Reproducibility
${specs}
---
*Generated with ggterm*
`
}
Width Guidelines
Choose plot width based on target context:
| Context | Width | Height | Notes |
|---|---|---|---|
| GitHub README | 72-80 | 16-20 | Standard terminal width |
| GitHub Issues | 72 | 14-18 | Compact for discussions |
| Documentation | 80-100 | 20-24 | More detail |
| Presentations | 60-70 | 12-16 | Readable at distance |
Including Data Tables
typescript
function markdownTable(data: Record<string, unknown>[], columns?: string[]): string {
const cols = columns || Object.keys(data[0])
const header = `| ${cols.join(' | ')} |`
const separator = `| ${cols.map(() => '---').join(' | ')} |`
const rows = data.map(row =>
`| ${cols.map(c => String(row[c] ?? '')).join(' | ')} |`
).join('\n')
return `${header}\n${separator}\n${rows}`
}
// Usage
const summaryTable = markdownTable([
{ metric: 'Mean', value: mean.toFixed(2) },
{ metric: 'Median', value: median.toFixed(2) },
{ metric: 'Std Dev', value: std.toFixed(2) },
])
Full Example: EDA Report
typescript
import { gg, geom_histogram, geom_boxplot, geom_point, facet_wrap } from '@ggterm/core'
import { writeFileSync } from 'fs'
// Assume data is loaded
const numericCols = ['age', 'income', 'score']
const categoricalCols = ['region', 'segment']
// Generate distribution plots
const distributions = numericCols.map(col => ({
title: `Distribution of ${col}`,
plot: gg(data).aes({ x: col }).geom(geom_histogram({ bins: 20 })),
interpretation: `Shows the distribution of ${col} values.`
}))
// Generate comparison plots
const comparisons = categoricalCols.map(cat => ({
title: `Score by ${cat}`,
plot: gg(data).aes({ x: cat, y: 'score' }).geom(geom_boxplot()),
interpretation: `Compares score across ${cat} groups.`
}))
// Correlation scatter
const correlation = {
title: 'Age vs Income',
plot: gg(data)
.aes({ x: 'age', y: 'income', color: 'region' })
.geom(geom_point({ alpha: 0.6 })),
interpretation: 'Shows relationship between age and income by region.'
}
const report = generateReport(
'Exploratory Data Analysis',
`Analysis of ${data.length} customer records.`,
[...distributions, ...comparisons, correlation],
[
'Income is right-skewed with median $X',
'Region A shows significantly higher scores',
'Age and income show moderate positive correlation'
]
)
writeFileSync('eda-report.md', report)
Tips
- Keep plots compact - Use 16-20 lines height for readability
- Include interpretations - Don't just show plots, explain them
- Save specs - Always include PlotSpec JSON for reproducibility
- Use collapsible sections -
<details>tags keep reports clean - Match audience - Adjust technical depth to readers
For report templates, see templates/.
Didn't find tool you were looking for?