Skip to content
Back to search

agent-skills

A collection of AI agent skills and plugins for Hermes Agent — research, creative, productivity, devops, and more. Each skill is self-contained and tested.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/moonlight-lupin/agent-skills with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/moonlight-lupin/agent-skills'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/moonlight-lupin--agent-skills/badge.svg)](/listings/moonlight-lupin--agent-skills)

HTML

<a href="/listings/moonlight-lupin--agent-skills"><img src="/api/listings/moonlight-lupin--agent-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One-command: install the whole catalog (`npx`)

npx skills add moonlight-lupin/agent-skills

Installs every skill into `.agents/skills/` (works for Cursor, Codex, Gemini CLI, Copilot, OpenCode, and more; Claude Code gets a symlinked copy) plus `.claude/skills/`, with a hash-pinned `skills-lock.json` so `npx skills update` can refresh later. Install one skill with `--skill <name>` — or omit it for an interactive pick-list.

Pick a skill from GitHub (`gh`)

# Install one skill by exact path (fastest, no tree scan)
gh skill install moonlight-lupin/agent-skills creative/image-studio/SKILL.md

# ...or by name into a specific agent's directory
gh skill install moonlight-lupin/agent-skills creative/image-studio/SKILL.md --agent claude-code --scope user

Manual

git clone https://github.com/moonlight-lupin/agent-skills.git
cd agent-skills

Each skill folder has a `SKILL.md` with setup and usage instructions — copy the ones you want into your agent's skills directory (e.g. `~/.claude/skills/`, `~/.cursor/skills/`, `~/.agents/skills/`).

> **Never commit credentials.** API keys, config files with secrets, and generated artifacts are all gitignored.

> **Spec compliance:** all skills validate against the [Agent Skills spec](https://agentskills.io/specification) (`npx skills-ref validate`). Author, version, and platform metadata live under `metadata:`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 191 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Agent Skills
  2. [![Tests](https://github.com/moonlight-lupin/agent-skills/actions/workflows/test.yml/badge.svg)](https://github.com/moonlight-lupin/agent-skills/actions/workflows/test.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
  5. A collection of AI agent skills built for [Hermes Agent](https://hermes-agent.nousresearch.com), organised by domain. Each skill is self-contained in its own folder — pick and choose which to install.
  6. > **Portability:** These skills are written for Hermes's tool architecture (`web_search`, `web_extract`, `terminal`, `delegate_task`, `cronjob`, etc.) and SKILL.md format. However, the workflows, prompts, and scripts are agent-agnostic — an AI agent on any platform (Claude Code, Codex, OpenCode, LangGraph, etc.) should be able to adapt them by mapping the tool names and adjusting the skill loader conventions to their own environment.
  7. ## Repository structure
  8. ```text
  9. agent_skills/
  10. ├── README.md ← you are here (repo-level)
  11. ├── LICENSE
  12. ├── creative/ ← image and video generation workflows
  13. │ ├── image-studio/ ← staged fal.ai image generation/editing/cleanup
  14. │ ├── clips-studio/ ← staged fal.ai short-video generation/animation/camera moves
  15. │ └── pexels-stock-photos/ ← free real-world stock photo search + download (Pexels API)
  16. ├── research/ ← source-grounded research, enrichment, and RAG skills
  17. │ ├── deep-research/ ← iterative research engine with structured evidence, source quality ranking, refute polarity, four-label evidence-basis discipline, deterministic validation gates, verbatim quote anchoring, per-round search budgets
  18. │ ├── entity-research/ ← cited entity/person background dossiers + sanctions signals
  19. │ ├── news-monitoring/ ← recurring news digests with cron delivery + multi-language
  20. │ ├── notebooklm-mode/ ← NotebookLM-style source vault + grounded answers
  21. │ ├── people-enrichment/ ← PDL person/company enrichment/search to styled .xlsx
  22. │ ├── library-rag/ ← Nemotron-3-Embed-1B + sqlite-vec semantic search engine
  23. │ └── endpoint-probe/ ← API/MCP surface discovery (REST, GraphQL, SOAP, JSON-RPC)
  24. ├── mlops/ ← model evaluation and ops skills
  25. │ ├── model-compare/ ← blind multi-model A/B comparison + embedding benchmark
  26. │ └── paired-agent-eval/ ← paired A/B pilot harness: matched task pairs, blinded defect scoring, behavioral text-variant batteries
  27. ├── web-scraping/ ← web data-extraction skills
  28. │ └── website-scraping/ ← recon → lightest-tool extraction → JSONL output
  29. ├── productivity/ ← personal / business-ops skills
  30. │ ├── fill-template/ ← bulk-fill Word/Excel templates from a data table (mail-merge)
  31. │ ├── travel-itinerary/ ← business-trip itineraries: parse → structure → export
  32. │ ├── decision-log/ ← ADR-style decision journal + superseding chains + cron reviews
  33. │ ├── scheduled-summary/ ← cron-driven cross-session digest for messaging platforms
  34. │ ├── file-organizer/ ← LLM-powered directory organizer: scan → propose → confirm → move
  35. │ ├── receipt-compiler/ ← phone-camera receipt photos → straightened B&W A4 expense-claim PDF
  36. │ ├── task-brief/ ← goal/done-when/constraints brief before substantial tasks; reusable prompts
  37. │ ├── marp-deck/ ← Marp Markdown decks → PPTX/PDF/HTML render
  38. │ └── pdf2epub/ ← text-layer PDF book → structured EPUB (cover, TOC nav, illustrations, endnotes; classifier calibration rules absorbed)
  39. ├── agent-ops/ ← agent infrastructure and maintenance skills
  40. │ ├── claude-plugin-converter/ ← convert Claude Code plugins → self-contained Hermes plugins
  41. │ ├── log-analyzer/ ← log pattern detection: error clusters, rate limits, timeouts
  42. │ ├── input-token-overheads/ ← audit input token cost, two scopes: per-turn prompt overhead + aggregate spend (cost accounting)
  43. │ ├── operator-brain/ ← 10-module behavioral stack (Fable 5 + 5.1): act, lead with outcome, ground claims, narrate long work
  44. │ └── hermes-onboarding/ ← 21-step customer onboarding: gateway, dashboard, memory, crons
  45. ├── software-development/ ← skill development, review, and methodology skills
  46. │ └── skill-quality-review/ ← batch skill audit: 9 checks, writing-for-agents levers, efficacy testing
  47. ├── devops/ ← infrastructure and system maintenance skills
  48. │ └── disk-triage/ ← triage survey → safe/ask buckets → execute → verify delta (renamed from disk-cleanup — bundled Hermes plugin now owns that name)
  49. └── plugins/ ← installable Hermes Agent plugins
  50. ├── skill-retrieval/ ← BM25 retrieval that injects the top-K relevant skills per turn
  51. ├── dev-pipeline/ ← five-stage development pipeline (grill/spec/test-evals/build/review-commit) with a pre_tool_call create-gate hook
  52. ├── skill-governance/ ← skill provenance + drift acks + advisory contrastive probes behind one composed hook surface (successor to the retired skill-manifest + contrastive-advisor plugins)
  53. └── lumen/ ← LLM wiki plugin: methodology + memory-fed curator
  54. ```
  55. New skills are added as folders under the relevant domain directory.
  56. ## Skills
  57. | Skill | Domain | What it does | Dependencies |
  58. |-------|--------|-------------|-------------|
  59. | [image-studio](creative/image-studio/) | creative | Staged fal.ai image gen/edit/upscale/cleanup with cost logging + `--dry-run` | pexels-stock-photos |
  60. | [clips-studio](creative/clips-studio/) | creative | Staged fal.ai short-video: text-to-video, animate still, camera moves | image-studio |
  61. | [pexels-stock-photos](creative/pexels-stock-photos/) | creative | Free real-world stock photos (Pexels API, 20k/month) with attribution handling | image-studio |
  62. | [deep-research](research/deep-research/) | research | Iterative research engine: structured evidence, source quality ranking (primary/secondary/tertiary), refute polarity, overview-first reports, four-label evidence-basis discipline ([VERIFIED]/[SOURCED]/[REASONED]/[ESTIMATED]), deterministic validation gates (claim-support, citations, structure), verbatim quote anchoring, per-round search budgets, provider-neutral search and page-reader fallbacks, referent disambiguation probe, firmware support-status triangulation recipe, provider head-to-head benchmarking, source families / shelf lives / money-figure bases, items × fields comparison mode and research recipes, checkable done-when tests, follow-up report revision, persistent citation DB scripts (absorbed source-tracker) | — |
  63. | [entity-research](research/entity-research/) | research | Cited company/person dossiers: ownership, adverse media, sanctions, litigation; optional cited organisation-evidence run (Exa Agent API) | deep-research |
  64. | [people-enrichment](research/people-enrichment/) | research | PDL person/company lookup → styled `.xlsx`; email-list enrichment (free triage, one lookup per domain); shared mailboxes never kept as a person's email | entity-research |
  65. | [library-rag](research/library-rag/) | research | Semantic search over personal library (Nemotron-3-Embed-1B + sqlite-vec), incremental + prune-missing | notebooklm-mode |
  66. | [notebooklm-mode](research/notebooklm-mode/) | research | Source-grounded Q&A from a source vault, strict or augmented grounding | library-rag, deep-research |
  67. | [news-monitoring](research/news-monitoring/) | research | Recurring news digests with cron delivery + multi-language + dedup | — |
  68. | [endpoint-probe](research/endpoint-probe/) | research | Discover API/MCP surfaces (REST, GraphQL, SOAP, JSON-RPC) — probe script + interpretation guide | website-scraping |
  69. | [model-compare](mlops/model-compare/) | mlops | Blind multi-model A/B comparison: simple, tools, coding, review modes + embedding benchmark; dated battery findings library | paired-agent-eval |
  70. | [paired-agent-eval](mlops/paired-agent-eval/) | mlops | Does tiered pipeline processing justify its cost: matched single-agent vs pipeline pairs, acceptance suites, blinded severity-weighted defect scoring; behavioral skill-text variant A/B batteries (operating methodology for the operator-brain text-variant evals) | model-compare |
  71. | [website-scraping](web-scraping/website-scraping/) | web-scraping | Recon → lightest extraction tool → JSONL + run manifest | — |
  72. | [fill-template](productivity/fill-template/) | productivity | Bulk-fill Word/Excel templates from a data table (mail-merge) | — |
  73. | [travel-itinerary](productivity/travel-itinerary/) | productivity | Business-trip itineraries from emails/PDFs → Markdown + `.ics` + chat variants | — |
  74. | [decision-log](productivity/decision-log/) | productivity | ADR-style decision journal with superseding chains + cron review reminders | — |
  75. | [scheduled-summary](productivity/scheduled-summary/) | productivity | Cron-driven cross-session digest — surfaces activity invisible on chat platforms | decision-log, news-monitoring |
  76. | [file-organizer](productivity/file-organizer/) | productivity | LLM-powered directory organizer: scan → propose structure → confirm → chunked moves | — |
  77. | [receipt-compiler](productivity/receipt-compiler/) | productivity | Phone-camera receipt photos → straightened B&W scans → A4 expense-claim PDF with confirmation gate | pdf |
  78. | [task-brief](productivity/task-brief/) | productivity | Goal/done-when/context/constraints/tooling brief compiled and confirmed before substantial work starts; reusable-prompt mode for recurring work | — |
  79. | [pdf2epub](productivity/pdf2epub/) | productivity | Text-layer PDF book → structured EPUB: cover, printed-TOC nav, inline illustrations, linked endnotes; classifier calibration rules absorbed into `references/calibration.md` | document-toolkit, opendataloader-pdf |
  80. | [marp-deck](productivity/marp-deck/) | productivity | Marp presentations: Markdown source of truth → PDF/PPTX/HTML, with themes, SVG components, PPTX import, and render tests | — |
  81. | [claude-plugin-converter](agent-ops/claude-plugin-converter/) | agent-ops | Two-phase converter: analyze Claude Code plugins → generate installable Hermes plugins | — |
  82. | [skill-quality-review](software-development/skill-quality-review/) | software-development | Batch skill audit: 9 automated checks, writing-for-agents levers, per-skill grep methodology, efficacy A/B testing, frontmatter/description fixes | — |
  83. | [log-analyzer](agent-ops/log-analyzer/) | agent-ops | Log pattern detection: error clusters, rate limits, timeout clusters, tool failures | scheduled-summary |
  84. | [input-token-overheads](agent-ops/input-token-overheads/) | agent-ops | Audit input token cost at two scopes: per-turn prompt overhead (tool schemas, skills index, system text, profile, memory — measured live, ranked, reduced) and aggregate spend/cost accounting across sessions, cron fires, and tool traffic (cache-aware interpretation, pre-checked config levers, scheduled delta checks) | — |
  85. | [operator-brain](agent-ops/operator-brain/) | agent-ops | 10-module behavioral stack from Anthropic's Fable 5 and Fable 5.1 guides: act, lead with outcome, ground every claim, narrate long work, stay surgical | — |
  86. | [hermes-onboarding](agent-ops/hermes-onboarding/) | agent-ops | 21-step customer onboarding: gateway, dashboard, memory, search, guardrails, maintenance crons | disk-triage, log-analyzer |
  87. | [disk-triage](devops/disk-triage/) | devops | Triage disk space: survey all mounts → safe/ask buckets → execute approved set → verify delta (renamed from disk-cleanup; the bundled Hermes `disk-cleanup` plugin owns that name) | — |
  88. | [dev-pipeline](plugins/dev-pipeline/) | plugins | Five-stage development pipeline: grill → spec → test-evals → build → review-commit, planned by S0-S3 complexity and reviewed by R0-R3 risk (T0-T3 review-tier aliases), with a review-lessons library and a pre_tool_call create-gate that blocks new software-development skills unless a single-use allow flag is consumed | skill-quality-review |
  89. | [skill-governance](plugins/skill-governance/) | plugins | Consolidated skill provenance and governance: manifest fingerprints + drift acks and advisory-only contrastive probes behind one composed hook surface, conservative `governance.records` join, non-destructive legacy state import, and one clearance Automation Blueprint (`/blueprint`-adopted, no self-installed cron; sole successor to the retired skill-manifest + contrastive-advisor plugins) | — |
  90. > **Related work:** [Odysseus](https://github.com/pewdiepie-archdaemon/odysseus) (PewDiePie's self-hosted AI workspace) ships similar features as a standalone web app — "Deep Research" and "Compare" — while `deep-research` and `model-compare` cover the same ground as pure-prompt workflows + stdlib scripts inside any agent's tool loop.
  91. ## Plugins
  92. Beyond skills, the repo ships installable [Hermes Agent](https://hermes-agent.nousresearch.com) plugins under `plugins/`.
  93. ### skill-retrieval
  94. A Hermes plugin that scales skill usage to large libraries. As a skill catalog grows past a few dozen entries, the per-turn `<available_skills>` block costs input tokens and buries the right skill in noise. This plugin replaces the full block with BM25 retrieval: each user turn is scored against a stdlib inverted index built from skill names and descriptions, and only the top-K most relevant skills are injected into the prompt (default K=6, configurable via `plugin.yaml`).
  95. - **Stdlib only** — no numpy/scipy; the index builds in milliseconds and retrieval is sub-millisecond for 128+ skills.
  96. - **Profile-aware discovery** — paths resolve through Hermes' own helpers (`get_hermes_home`, `get_skills_dir`), so named profiles, `skills.external_dirs`, trusted project-local skills, disabled lists, and platform/condition gates all match what the agent itself sees. The index cache is keyed per Hermes home, so multiplexed profiles never share an index.
  97. - **Windows-safe** — skill ids normalize to forward slashes; `$HERMES_HOME`-aware path resolution.
  98. - **Optional Jev rerank** — reranks the BM25 top-K with the Jev system-one judgment model (`api.typesafe.ai`) when `SKILL_RETRIEVAL_RERANK` is enabled and `TYPESAFE_API_KEY` is present (the legacy `TYPESAFE_KEY` name is accepted, from `os.environ`). Fail-soft: on timeout or error it logs and falls back to pure BM25. An A/B log (`rerank_ab_report.py`) records per-query decisions for trial review; it rotates past 5 MB; runs on a cron, no runtime dependency.
  99. - **Graceful degradation** — if Hermes core modules are unavailable, it falls back to a standalone loader; malformed configs never abort the index build. A/B logging and rerank never abort retrieval.
  100. Or install from the Hermes plugin catalog (pinned, version-tracked):
  101. ```bash
  102. hermes plugins install skill-retrieval
  103. ```
  104. Install by copying or symlinking `plugins/skill-retrieval/` into `~/.hermes/plugins/` (or your profile's `plugins/`), then restart the gateway. Tests: `python3 -m pytest plugins/skill-retrieval/tests/`.
  105. ### lumen
  106. A Hermes plugin that turns an agent's conversation history and memory into a maintained markdown wiki (Karpathy-style LLM wiki). Two skills: `lumen:wiki` (the methodology: OKF frontmatter, three-layer page layout, ingest/query/lint workflows) and `lumen:curator` (the `wiki_curator.py` script plus a read-only memory-source adapter layer — the Hermes conversation history via read-only SQLite, Mnemosyne via the `hermes` CLI export, plain JSON files, or none).
  107. - **Sessions-first by default** — the default memory source is the agent's own conversation history (read-only SQLite over `state.db`); `auto` prefers sessions, then Mnemosyne, then JSON files. The conversation record is treated as ground truth; memory stores hold derived notes.
  108. - **Cap-bounded curation** — batch ingest, update, and validate runs are capped per run, with per-page backups and atomic replace.
  109. - **Source attribution contract** — every generated line is `[source: id]` attributed; operator-authored text outside generated sections is preserved on update (verified through 7 review rounds with independent confirm reviewers).
  110. - **Stdlib + PyYAML only** — no network calls except the `hermes` CLI for memory export; adapters read exports, never provider internals.
  111. Install by copying or symlinking `plugins/lumen/` into `~/.hermes/plugins/` (or your profile's `plugins/`), enable it with `hermes plugins enable lumen` (user plugins are opt-in), then restart the gateway. Tests: `python3 -m pytest plugins/lumen/tests/`.
  112. ### dev-pipeline
  113. A Hermes plugin that guards skill creation and carries the development pipeline as five bundled stage skills (`dev-pipeline:orchestrator` → `dev-pipeline:grill` → `dev-pipeline:spec` → `dev-pipeline:test-evals` → `dev-pipeline:build` → `dev-pipeline:review-commit`), plus a `review-lessons` library split out of the review stage. A `pre_tool_call` gate blocks bare-name creation of new software-development skills unless a single-use `.allow-create` flag is consumed — the loop concepts that used to live in a standalone build-review-loop skill now ship as these bundled skills.
  114. Install by copying or symlinking `plugins/dev-pipeline/` into `~/.hermes/plugins/` (or your profile's `plugins/`), then restart the gateway. Tests: `python3 -m pytest plugins/dev-pipeline/tests/`.
  115. ### skill-governance
  116. A Hermes plugin that consolidates the provenance engine and the advisory edit-observation engine behind one composed hook surface (`on_skill_lifecycle`, `on_session_start`, `pre_tool_call`, `pre_llm_call`). It bundles the `contrastive-refinement` skill (`plugins/skill-governance/skills/contrastive-refinement/`, registered as `skill-governance:contrastive-refinement`): behavioral skill edits get one advisory reminder to run the probe cycle (fire ledger at `~/.hermes/skill-probes/fire-ledger.jsonl`). The manifest engine enforces `UPSTREAM_MANIFEST.md`: arrivals must have a manifest row, content changes in manifested skills must be re-acknowledged against a content fingerprint (`/skill-manifest-ack <name> <sha>`). `manifest.v1`/`advisor.v1` import legacy state by copy (destination-wins, sources never modified). v0.3.0 ships the clearance procedure as an adopted Automation Blueprint (`skill-governance:clearance`, daily `0 9 * * *`, delivery `origin`) registered through the public host surface — the plugin imports no private cron modules and writes no cron state; it replaces both legacy schedulers and preserves both clearance procedures verbatim. `governance.records` joins the two views conservatively — an acknowledged fingerprint never implies validated evidence.
  117. Install from the Hermes plugin catalog:
  118. ```bash
  119. hermes plugins install skill-governance
  120. ```
  121. Or copy/symlink `plugins/skill-governance/` into `~/.hermes/plugins/` (or your profile's `plugins/`), then restart the gateway. Migrate from the retired `skill-manifest`/`contrastive-advisor` plugins per the checklist in `plugins/skill-governance/README.md`. Tests: `python3 -m pytest plugins/skill-governance/tests/`.
  122. ## Conventions
  123. > Conventions: the *Dependencies* column on the Skills table lists pip/runtime requirements beyond Python stdlib; skills marked *evals* ship routing/output-contract fixtures under `evals/` (sample request → expected routing, required output fields, forbidden patterns), validated by `tests/test_routing_fixtures.py` — no live-model execution in CI. Plugins are tested separately (`plugins/<name>/tests/`) and tracked under Plugins above.
  124. ## Install
  125. ### One-command: install the whole catalog (`npx`)
  126. ```bash
  127. npx skills add moonlight-lupin/agent-skills
  128. ```
  129. Installs every skill into `.agents/skills/` (works for Cursor, Codex, Gemini CLI, Copilot, OpenCode, and more; Claude Code gets a symlinked copy) plus `.claude/skills/`, with a hash-pinned `skills-lock.json` so `npx skills update` can refresh later. Install one skill with `--skill <name>` — or omit it for an interactive pick-list.
  130. ### Pick a skill from GitHub (`gh`)
  131. ```bash
  132. # Install one skill by exact path (fastest, no tree scan)
  133. gh skill install moonlight-lupin/agent-skills creative/image-studio/SKILL.md
  134. # ...or by name into a specific agent's directory
  135. gh skill install moonlight-lupin/agent-skills creative/image-studio/SKILL.md --agent claude-code --scope user
  136. ```
  137. ### Manual
  138. ```bash
  139. git clone https://github.com/moonlight-lupin/agent-skills.git
  140. cd agent-skills
  141. ```
  142. Each skill folder has a `SKILL.md` with setup and usage instructions — copy the ones you want into your agent's skills directory (e.g. `~/.claude/skills/`, `~/.cursor/skills/`, `~/.agents/skills/`).
  143. > **Never commit credentials.** API keys, config files with secrets, and generated artifacts are all gitignored.
  144. > **Spec compliance:** all skills validate against the [Agent Skills spec](https://agentskills.io/specification) (`npx skills-ref validate`). Author, version, and platform metadata live under `metadata:`.
  145. ## License
  146. [MIT](LICENSE) — all skills in this repository are original works by moonlight-lupin and are covered by the MIT License.
productivity/marp-deck/scripts/md2pptx-officecli.py · Bundled script · 316 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. """md2pptx-officecli.py — build an editable PPTX from a Marp Markdown deck.
  3. Fallback path for machines without a full LibreOffice install (LibreOffice 24.2+
  4. removed the Impress HTML import filter, which breaks `marp --pptx-editable`).
  5. Parses the deck's Markdown structurally — headings, bullets, numbered lists,
  6. tables, blockquotes — and emits native PowerPoint text boxes, tables and shapes
  7. via the `officecli` CLI. Styling: reads the deck's own theme colours when the
  8. frontmatter defines `--dark`, `--light` and `--accent` CSS variables in a
  9. `:root` block; otherwise uses PowerPoint defaults.
  10. This is a fidelity-lost conversion by design: complex HTML components, SVG
  11. charts and background images are skipped (a placeholder line names them). The
  12. pixel-faithful render stays with `marp deck.md --pdf`. Keep both.
  13. Usage:
  14. python3 md2pptx-officecli.py deck.md output.pptx
  15. Requires:
  16. officecli on PATH — https://github.com/iOfficeAI/OfficeCLI
  17. curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 20 on GitHub
  18. """
  19. import json
  20. import re
  21. import subprocess
  22. import sys
  23. CANVAS_W, CANVAS_H = 33.87, 19.05 # cm — officecli default 960x540pt
  24. MX = 1.4
  25. CW = CANVAS_W - 2 * MX
  26. # Fallback palette (near-neutral, readable on white)
  27. C_BG, C_INK, C_SOFT, C_FAINT = "FFFFFF", "1A1A1A", "444444", "8A8A8A"
  28. C_ACCENT, C_LINE, C_ONACC = "1F4E79", "D9D9D9", "FFFFFF"
  29. ops = []
  30. slide_n = 0
  31. def add(parent, type_, **props):
  32. parent = parent.replace("/slide[1]", f"/slide[{slide_n}]")
  33. ops.append({"command": "add", "parent": parent, "type": type_,
  34. "props": {k: str(v) for k, v in props.items()}})
  35. def st(path, **props):
  36. path = path.replace("/slide[1]", f"/slide[{slide_n}]")
  37. ops.append({"command": "set", "path": path,
  38. "props": {k: str(v) for k, v in props.items()}})
  39. def strip_md(text):
  40. text = re.sub(r"<[^>]+>", "", text) # inline HTML/strong tags
  41. text = re.sub(r"\*\*(.+?)\*\*", r"\1", text) # bold
  42. text = re.sub(r"\*(.+?)\*", r"\1", text) # italic
  43. text = re.sub(r"`(.+?)`", r"\1", text) # code
  44. text = re.sub(r"!\[.*?\]\(.*?\)", "[image]", text)
  45. text = re.sub(r"\[(.+?)\]\(.*?\)", r"\1", text) # links
  46. return text.strip()
  47. def parse_theme(md_text):
  48. """Pull --dark/--light/--accent from a :root block in the frontmatter style."""
  49. global C_BG, C_INK, C_SOFT, C_FAINT, C_ACCENT, C_LINE, C_ONACC
  50. root = re.search(r":root\s*\{(.*?)\}", md_text, re.S)
  51. if not root:
  52. return
  53. block = root.group(1)
  54. def var(name, default):
  55. m = re.search(rf"--{name}\s*:\s*#([0-9a-fA-F]{{6}})", block)
  56. return m.group(1).upper() if m else default
  57. dark = var("dark", "") # dark = background colour in Marp themes
  58. light = var("light", "")
  59. accent = var("accent", "")
  60. if light and dark:
  61. # Convention: --light is body/foreground, --dark is background
  62. C_BG = dark
  63. C_INK = light
  64. C_ONACC = dark if _luma(dark) > 0.5 else "FFFFFF"
  65. C_ONACC = "FFFFFF" if _luma(dark) < 0.5 else dark
  66. if accent:
  67. C_ACCENT = accent
  68. C_ONACC = "FFFFFF" if _luma(accent) < 0.5 else dark or "1A1A1A"
  69. m = re.search(r"--body\s*:\s*#([0-9a-fA-F]{6})", block)
  70. if m:
  71. C_SOFT = m.group(1).upper()
  72. def _luma(hex6):
  73. r, g, b = (int(hex6[i:i + 2], 16) for i in (0, 2, 4))
  74. return (0.299 * r + 0.587 * g + 0.114 * b) / 255
  75. def parse_deck(path):
  76. """Return list of slides; each = dict(kind, title, blocks[]).
  77. block = (btype, payload) with btype in h1/h2/h3/bullets/table/quote/par/peg/html."""
  78. md = open(path, encoding="utf-8").read()
  79. parse_theme(md)
  80. # Drop frontmatter (allow leading blank lines)
  81. md = re.sub(r"\A\s*---\n.*?\n---\n", "", md, count=1, flags=re.S)
  82. # Drop Marp directives
  83. md = re.sub(r"<!--_class:.*?-->", "", md)
  84. md = re.sub(r"<!--\s*_?class:.*?-->", "", md)
  85. md = re.sub(r"<!--.*?-->", "", md)
  86. slides = []
  87. for chunk in re.split(r"\n---+\n", md):
  88. lines = chunk.strip().splitlines()
  89. if not lines or all(not ln.strip() for ln in lines):
  90. continue
  91. slide = {"title": None, "subtitle": None, "blocks": []}
  92. i, buf = 0, lines
  93. while i < len(buf):
  94. ln = buf[i].rstrip()
  95. if not ln.strip():
  96. i += 1
  97. continue
  98. if ln.startswith("# ") and slide["title"] is None:
  99. slide["title"] = strip_md(ln[2:])
  100. elif ln.startswith("## "):
  101. t = strip_md(ln[3:])
  102. if slide["title"] is None:
  103. slide["title"] = t
  104. else:
  105. slide["blocks"].append(("h3", t))
  106. elif ln.startswith("### "):
  107. slide["blocks"].append(("h3", strip_md(ln[4:])))
  108. elif re.match(r"^- |\* ", ln):
  109. items = []
  110. while i < len(buf) and re.match(r"^\s*[-*] ", buf[i]):
  111. indent = len(buf[i]) - len(buf[i].lstrip())
  112. items.append((" " * (indent // 2)) + strip_md(re.sub(r"^\s*[-*] ", "", buf[i])))
  113. i += 1
  114. slide["blocks"].append(("bullets", items))
  115. continue
  116. elif re.match(r"^\d+\. ", ln):
  117. items = []
  118. while i < len(buf) and re.match(r"^\s*\d+\. ", buf[i]):
  119. items.append(strip_md(re.sub(r"^\s*\d+\. ", "", buf[i])))
  120. i += 1
  121. slide["blocks"].append(("numbers", items))
  122. continue
  123. elif ln.startswith("|"):
  124. rows = []
  125. while i < len(buf) and buf[i].strip().startswith("|"):
  126. cells = [strip_md(c.strip()) for c in buf[i].strip().strip("|").split("|")]
  127. if not re.match(r"^\s*\|[\s:|-]+\|?\s*$", buf[i]):
  128. rows.append(cells)
  129. i += 1
  130. if rows:
  131. slide["blocks"].append(("table", rows))
  132. continue
  133. elif ln.startswith(">"):
  134. quote = strip_md(ln.lstrip("> "))
  135. slide["blocks"].append(("quote", quote))
  136. elif ln.startswith("<"): # HTML block (peg-row, cols, rule divs…)
  137. html = []
  138. while i < len(buf) and buf[i].strip().startswith("<"):
  139. html.append(buf[i].strip())
  140. i += 1
  141. joined = " ".join(html)
  142. peg = re.search(r'class="peg"[^>]*>(\d+)<', joined) # header-tag rows (any theme)
  143. label = re.search(r'class="peg-label"[^>]*>([^<]+)<', joined)
  144. if peg and label:
  145. slide["blocks"].append(("peg", (peg.group(1), label.group(1))))
  146. elif "<strong>" in joined or "<div" in joined:
  147. txt = strip_md(re.sub(r"<br\s*/?>", "\n", joined))
  148. if txt:
  149. slide["blocks"].append(("box", txt))
  150. continue
  151. else:
  152. txt = strip_md(ln)
  153. if txt and not slide["subtitle"] and slide["title"] and not slide["blocks"]:
  154. slide["subtitle"] = txt
  155. elif txt:
  156. slide["blocks"].append(("par", txt))
  157. i += 1
  158. slides.append(slide)
  159. return slides
  160. def emit(slides):
  161. for s in slides:
  162. globals()["slide_n"] += 1
  163. y = 1.2
  164. # Background: light theme only (officecli renders text themes simply)
  165. add(f"/slide[{slide_n}]", "shape", x="0cm", y="0cm",
  166. width=f"{CANVAS_W}cm", height=f"{CANVAS_H}cm", fill=C_BG,
  167. line="none")
  168. title_y = 1.6
  169. if s["title"]:
  170. add(f"/slide[{slide_n}]", "shape", text=s["title"],
  171. x=f"{MX}cm", y=f"{title_y}cm", width=f"{CW}cm", height="1.5cm",
  172. font="Arial", size=28, bold="true", color=C_INK)
  173. y = title_y + 2.0
  174. if s["subtitle"]:
  175. add(f"/slide[{slide_n}]", "shape", text=s["subtitle"],
  176. x=f"{MX}cm", y=f"{y}cm", width=f"{CW}cm", height="1.0cm",
  177. font="Arial", size=15, color=C_SOFT)
  178. y += 1.5
  179. for btype, payload in s["blocks"]:
  180. if btype == "peg":
  181. num, label = payload
  182. add(f"/slide[{slide_n}]", "shape", text=num,
  183. x=f"{MX}cm", y=f"{y}cm", width="1.2cm", height="1.2cm",
  184. fill=C_BG, font="Consolas", size=13, bold="true",
  185. color=C_ACCENT, geometry="roundRect", line=C_LINE)
  186. add(f"/slide[{slide_n}]", "shape", text=label.upper(),
  187. x=f"{MX + 1.8}cm", y=f"{y + 0.25}cm", width="12cm",
  188. height="0.8cm", font="Consolas", size=10, bold="true",
  189. color=C_ACCENT)
  190. y += 1.8
  191. elif btype == "h3":
  192. add(f"/slide[{slide_n}]", "shape", text=payload.upper(),
  193. x=f"{MX}cm", y=f"{y}cm", width=f"{CW}cm", height="0.8cm",
  194. font="Consolas", size=11, bold="true", color=C_ACCENT)
  195. y += 1.2
  196. elif btype == "bullets":
  197. txt = "\n".join("· " + item for item in payload)
  198. h = max(1.2, 0.75 * len(payload) + 0.6)
  199. add(f"/slide[{slide_n}]", "shape", text=txt,
  200. x=f"{MX}cm", y=f"{y}cm", width=f"{CW}cm", height=f"{h}cm",
  201. font="Arial", size=14, color=C_SOFT, valign="top")
  202. y += h + 0.4
  203. elif btype == "numbers":
  204. txt = "\n".join(f"{i}. {item}" for i, item in enumerate(payload, 1))
  205. h = max(1.2, 0.75 * len(payload) + 0.6)
  206. add(f"/slide[{slide_n}]", "shape", text=txt,
  207. x=f"{MX}cm", y=f"{y}cm", width=f"{CW}cm", height=f"{h}cm",
  208. font="Arial", size=14, color=C_SOFT, valign="top")
  209. y += h + 0.4
  210. elif btype == "table":
  211. rows = payload
  212. n, c = len(rows), len(rows[0])
  213. colw = (CW - 0.4 * (c - 1)) / c
  214. add(f"/slide[{slide_n}]", "table", rows=n, cols=c,
  215. x=f"{MX}cm", y=f"{y}cm",
  216. colWidths=",".join(f"{colw:.2f}cm" for _ in range(c)),
  217. bandedRows="false")
  218. t = f"/slide[{slide_n}]/table[1]"
  219. for r, row in enumerate(rows, 1):
  220. st(f"{t}/tr[{r}]", height="0.85cm" if r == 1 else "1.1cm")
  221. for cix, val in enumerate(row, 1):
  222. if r == 1:
  223. st(f"{t}/tr[1]/tc[{cix}]", text=val, fill=C_BG,
  224. color=C_ACCENT, bold="true", font="Consolas",
  225. size=10)
  226. else:
  227. st(f"{t}/tr[{r}]/tc[{cix}]", text=val,
  228. fill="FFFFFF", color=C_SOFT, font="Arial",
  229. size=11, valign="middle")
  230. y += (0.85 if n else 0) + 1.1 * (n - 1) + 0.6
  231. elif btype == "quote":
  232. add(f"/slide[{slide_n}]", "shape", text=payload,
  233. x=f"{MX}cm", y=f"{y}cm", width=f"{CW}cm", height="1.6cm",
  234. font="Arial", size=12.5, color=C_INK, fill=C_BG,
  235. geometry="rect")
  236. add(f"/slide[{slide_n}]", "shape", x=f"{MX}cm", y=f"{y}cm",
  237. width="0.13cm", height="1.6cm", fill=C_ACCENT, line="none")
  238. y += 2.0
  239. elif btype == "par":
  240. h = 1.2 + 0.5 * (len(payload) // 110)
  241. add(f"/slide[{slide_n}]", "shape", text=payload,
  242. x=f"{MX}cm", y=f"{y}cm", width=f"{CW}cm", height=f"{h}cm",
  243. font="Arial", size=13, color=C_SOFT, valign="top")
  244. y += h + 0.3
  245. elif btype == "box":
  246. add(f"/slide[{slide_n}]", "shape", text=payload,
  247. x=f"{MX}cm", y=f"{y}cm", width=f"{CW}cm", height="2.0cm",
  248. font="Arial", size=12.5, color=C_SOFT, fill=C_BG,
  249. geometry="rect", line=C_LINE, margin="12pt,10pt,12pt,10pt")
  250. y += 2.4
  251. if y > 17.2:
  252. break # keep content on-canvas; overflow goes to next slide in a full rebuild
  253. def flush(out_path):
  254. payload = json.dumps(ops)
  255. r = subprocess.run(["officecli", "batch", out_path, "--commands", payload,
  256. "--json"], capture_output=True, text=True)
  257. try:
  258. data = json.loads(r.stdout)
  259. fails = [x for x in data.get("data", {}).get("results", [])
  260. if not x.get("success")]
  261. except Exception:
  262. fails = ["(unparseable output)"]
  263. if r.returncode != 0 or fails:
  264. print(f"officecli batch failed: {len(fails)} item(s)", file=sys.stderr)
  265. for f in fails[:4]:
  266. print(f, file=sys.stderr)
  267. sys.exit(1)
  268. print(f"officecli batch ok: {data.get('data', {}).get('summary', '')}")
  269. def main():
  270. if len(sys.argv) != 3:
  271. print(__doc__)
  272. sys.exit(2)
  273. src, out = sys.argv[1], sys.argv[2]
  274. subprocess.run(["officecli", "create", out], capture_output=True)
  275. # Pre-create slides one at a time (mixed slide-adds in one batch are unreliable)
  276. slides = parse_deck(src)
  277. for _ in slides:
  278. subprocess.run(["officecli", "add", out, "/", "--type", "slide"],
  279. capture_output=True)
  280. emit(slides)
  281. flush(out)
  282. subprocess.run(["officecli", "close", out], capture_output=True)
  283. print(f"Written {out} ({len(slides)} slides) — editable text boxes + tables.")
  284. if __name__ == "__main__":
  285. main()

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.