---
name: pdf-to-md
description: >
  Convert PDF documents to Markdown bundles using the convert_pdf_to_md tool.
  Handles single or multiple PDFs (concurrent batch), Feishu attachments, and
  local workspace files. Produces high-quality Markdown with LaTeX formulas
  and extracted images.
---

# PDF to Markdown Conversion

## When to use

Use this skill when the user asks to convert a PDF (or several PDFs) to
Markdown, extract text from a PDF, or turn PDF documents into an editable
format.

## How it works

The `convert_pdf_to_md` tool (provided by the in-process `cph_hub` MCP server)
calls Alibaba Cloud Document Mind to parse each PDF. It:

- Extracts text in reading order (handles multi-column, scanned, and
  multi-language documents)
- Converts mathematical formulas to **LaTeX** (`$...$` inline, `$$...$$` block)
- Extracts tables as Markdown tables
- Downloads embedded images into the output directory
- Writes a single `document.md` file plus image files **per** `output_dir`

There is **no** workspace `.mcp.json` source file. MCP tools are injected by
Hub at run start. Do not look for MCP or skill source under workspace
`.claude/` — those paths are sandbox stubs (often character devices) and are
not readable constitution.

## Where this skill text lives

Prefer the Skill tool when the runtime offers it. If you need to re-read these
instructions with Read:

- Workspace copy (always under cwd): `.cph/runtime-skills/pdf-to-md/SKILL.md`
- Absolute path env: `$CPH_RUNTIME_SKILLS_DIR/pdf-to-md/SKILL.md`

## Workflow

### One PDF from a Feishu message

1. Use `feishu_read_context` to find the `file_key` of the PDF attachment.
2. Use `feishu_download_resource` to download it into the workspace.
3. Use `convert_pdf_to_md` with `input_path` + `output_dir`.

### PDF already in the workspace

1. Use `convert_pdf_to_md` with `input_path` and `output_dir`.

### Multiple PDFs (concurrent)

1. Download or locate every PDF in the workspace first.
2. Call **`convert_pdf_to_md` once** with:

```json
{
  "items": [
    { "input_path": "sources/a.pdf", "output_dir": "md/a" },
    { "input_path": "sources/b.pdf", "output_dir": "md/b" }
  ]
}
```

3. Hub submits Docmind jobs with bounded concurrency (default 3, max 8;
   optional `concurrency` argument). Prefer this over N sequential tool calls.
4. **Each item must use a distinct `output_dir`** — the tool always writes
   `document.md` inside that directory; shared dirs overwrite each other.
5. Partial failure returns per-file OK/FAIL lines; re-run only failed items.

## Important rules

- **Always** use `convert_pdf_to_md` for PDF→Markdown. Do NOT attempt to parse
  PDFs yourself with Read, Bash, Python, or any other method.
- If `convert_pdf_to_md` fails because no capability connection is configured,
  tell the user to ask their organization admin to configure the Aliyun
  docmind credential in the admin web UI (组织后台 → 能力).
- The output directory will be created if it does not exist.
- After conversion, use `send_file` to send generated markdown (or a zip you
  assemble) back to the user if they requested delivery.

## Output

Per `output_dir`:

- `document.md` — the main markdown file
- `*.jpg` / `*.png` — extracted images, referenced from the markdown

## Cost

Billed per page (0.04 CNY/page ≈ $0.0056/page for enhanced formula mode).
Each successful file records its own usage fact on the run ledger.