pdfmd

PDF to Markdown Conversion Skill (example)

When to use

Consider enabling this Skill when any of the following situations occurs:

• The user says "convert this PDF into Markdown / MD / text / document"
• The user uploads or references a PDF file and requests things like "extract the body text from it" or "translate it into Chinese Markdown"

If the user only wants to read / summarize the PDF in general and does not request exporting Markdown, you can directly read the PDF text or use other skills.

Working directory structure

In the current example project, the directory where this Skill is located is as follows:

workspace/
  skills/
    pdfmd/
      SKILL.md
      pdf_extract.py

Among them:

• SKILL.md is this documentation file
• pdf_extract.py is a Python script that is only responsible for extracting plain text from the PDF (it does not call any large model), and then the current Agent uses the existing large model configuration to complete the translation and Markdown conversion.

Note: This Skill assumes that Python and the dependencies are already installed in the execution environment:

• pypdf

Operating steps for Claude (using the SDK's built-in capabilities)

When you determine that this Skill should be used, please operate in the following order:

1. Confirm the PDF file path

   • If the user provided a path (for example docs/report.pdf), first confirm that the path is within the current workspace.
   • If the user uploaded a PDF file, save it to the local working directory (such as ./docs/), and remember the actual path.

2. Choose the output path

   • If the user wants to generate a Markdown file, you can choose an output path, for example:
     • Input:docs/report.pdf
     • Output:docs/report.md

3. Use Bash to call the Python script to extract the PDF text

   Use the Bash tool to execute the Python script to read the PDF content, for example (note: the command is executed in the sandbox working directory workspace/ , so the path starts from skills/ ):

   python skills/pdfmd/pdf_extract.py \
     --input "<PDF 文件路径>" \
     --pages "<页码范围，可选，如 1-3,5>"
   

   Description:

   • --input: the path of the PDF file to read (required)
   • --pages: optional page range, for example "1-3,5"
   • The script does not call any large model; it only prints the extracted plain text to stdout.

   Bash In the return of the tool:

   • ok: whether the command executed successfully (exit code is 0)
   • output: contains the script's standard output (that is, the extracted PDF text)

4. Use the large model in the current conversation to perform the conversion

   After obtaining the output of Bash , there is no need to directly call any external large model API in the Skill or script. Instead:

   • Treat the content in the output field as the original PDF text;
   • In the current Agent's conversation, combined with the instructions of this Skill, send a request to the large model:
     • Translate the text into Chinese;
     • Adjust the structure into reasonable headings, paragraphs, lists, etc.;
     • Output in standard Markdown format.

   All large model calls are handled uniformly by the SDK's provider/router, automatically using the model and routing strategy configured for the current Agent. The Skill is not responsible for managing API Keys or model selection.

5. Use Write Save the Markdown to a file (if the user has this need)

   If the user explicitly requests to generate a Markdown file, after obtaining the final Markdown text, you can call the Write tool to write to the file:

   {
     "path": "<输出 Markdown 文件路径>",
     "content": "<模型生成的中文 Markdown 文本>"
   }
   

   Then the file can be used through normal file system operations (such as downloading or subsequent processing).

6. Perform secondary processing according to user needs (optional)

   • If the user has additional requirements (for example, "keep only certain chapters" or "simplify into a summary"), after obtaining the Markdown, use the model again for secondary processing.
   • For particularly long Markdown, it can be split by chapter or paragraph for processing to avoid exceeding the context limit.

Error Handling and Limitations

• If the Python script fails to execute (Bash returns ok == false or the exit code is non-zero):

  • Check whether the PDF path is correct;
  • Confirm that the file exists and is a valid PDF;
  • Check whether pypdf dependencies are installed.

• If the generated Markdown clearly lacks content or contains a large amount of garbled text:

  • Explain to the user that this is a limitation caused by the PDF's original layout / embedded fonts.
  • As appropriate, suggest trying to convert only part of the pages, or using another method to obtain the content.

Security Considerations

• This Skill only reads PDF text through a Python script and does not execute any code within it, but it is still recommended to use this Skill only with PDFs from trusted sources.
• Large model calls are uniformly managed internally by the SDK, and the Skill does not directly handle any API Key.