claude-md-to-pdf/docs/superpowers/specs/2026-05-04-md-to-pdf-skill-design.md

md-to-pdf Skill — Design Spec

Date: 2026-05-04 Author: Jean-Luc Makiola Status: Approved (pending implementation)

Goal

Provide a globally available Claude Code skill that converts the user's working Markdown file to a PDF on demand, triggered by natural language ("exportier mal", "mach das als PDF", "regenerate the PDF") rather than a slash command. The skill is distributed as a Claude Code plugin via a self-hosted Gitea marketplace, so installing it once on each device makes it permanently available with auto-updates.

Non-Goals

• Other output formats (DOCX, HTML, EPUB) — out of scope, kept open for later.
• Watch mode or batch (--all) conversions — not part of the current workflow.
• Multiple named style presets — a single sensible default plus per-project override is enough.
• Slash command UX — explicitly excluded; the trigger is the skill description.

Distribution

The repository is published to Gitea (gitea.<user-domain>/jlmak/claude-md-to-pdf) using Claude Code's plugin marketplace format. On each device, the user runs once:

/plugin marketplace add https://gitea.<user-domain>/jlmak/claude-md-to-pdf
/plugin install md-to-pdf@claude-md-to-pdf

After that, Claude Code's plugin update mechanism handles new versions.

Repository Layout

claude-md-to-pdf/
├── .claude-plugin/
│   └── marketplace.json            # marketplace manifest, lists the md-to-pdf plugin
├── plugins/
│   └── md-to-pdf/
│       ├── .claude-plugin/
│       │   └── plugin.json         # plugin manifest (name, version, description)
│       └── skills/
│           └── md-to-pdf/
│               ├── SKILL.md        # trigger description + instructions
│               └── default.config.js  # bundled md-to-pdf style config
├── docs/
│   └── superpowers/specs/
│       └── 2026-05-04-md-to-pdf-skill-design.md   (this file)
├── README.md
└── LICENSE

The default.config.js is a verbatim copy of the user's proven A4 / small-table CSS currently used in the Databases project.

Skill Trigger

The SKILL.md description is written so Claude's skill-matcher activates on natural-language requests in either German or English. Examples that must trigger:

• "exportier mal das PDF"
• "mach mir daraus ein PDF"
• "regenerate the PDF"
• "PDF neu generieren"
• "convert this markdown to pdf"

The description is explicit enough to not trigger on unrelated PDF requests (e.g. "open this PDF", "show me the lecture PDF").

Skill Behavior

When invoked, the skill follows this flow:

1. Identify the source .md

Order of resolution:

1. A .md path explicitly mentioned in the user's most recent message.
2. The .md file most recently read or written in the current session, if unambiguous.
3. The single most-recently-modified .md file in the current working directory.
4. If none of the above resolves to a single file, the skill asks the user which file to convert.

2. Resolve the config

1. Walk upward from the source .md looking for .md-to-pdf.config.js. Use the first one found.
2. Otherwise, fall back to the bundled default.config.js shipped with the skill (${CLAUDE_PLUGIN_ROOT}/skills/md-to-pdf/default.config.js).

3. Run the converter

npx --yes md-to-pdf <source.md> --config-file <resolved-config>

The output PDF is written next to the source (Loesung.md → Loesung.pdf), overwriting an existing file.

4. Confirm

Report back: PDF path, byte size, and which config was used (project vs. bundled default), so the user can tell at a glance which style applied.

Default Config

The bundled default.config.js mirrors the user's current setup — A4, 15mm/12mm margins, 5pt fixed-layout tables with no wrap, system sans-serif at 11pt. Optimized for German university homework with wide tables.

Project-local .md-to-pdf.config.js files always win, so the default is just a sensible fallback.

Error Handling

Boundaries where validation is needed:

• npx / Node not available → surface a clear error pointing the user to install Node.
• md-to-pdf package fetch fails → relay the npx error directly; don't retry silently.
• Source .md ambiguous → ask the user to disambiguate (do not guess).
• Config file syntactically broken → relay the error from md-to-pdf; don't try to "fix" the user's config.

Internal calls between skill steps trust each other; no defensive validation between them.

Testing Strategy

Manual smoke tests on first commit:

1. Run skill in the existing Databases project — must regenerate Uebungen/03/Loesung.pdf and visually match the current output (same layout, fonts, table rendering).
2. Run skill in a fresh directory with no .md-to-pdf.config.js — must produce a PDF using the bundled default.
3. Run skill where the source .md is ambiguous — must ask, not guess.

No automated test suite for v1; the toolchain is a thin wrapper over npx md-to-pdf.

Open Questions

None blocking. Future considerations (not part of v1):

• Should the bundled default eventually grow into multiple presets (homework / article / slides)?
• Should the skill help bootstrap a project-local .md-to-pdf.config.js on request?