Agent Skills

Teach IBM Bob, or any skill-aware AI assistant, to convert and navigate documents with Docling for IBM watsonx

A skill is a folder with a SKILL.md file: plain Markdown that tells an AI assistant what a tool does and when to use it. A Docling skill teaches the assistant to run the docling convert-remote command against Docling for IBM watsonx and then to read the result.

There is no server to keep running and no protocol to configure. The assistant reads the Markdown, runs a command in its terminal, and opens the files it produced. Because the skill is just text, the same folder works in IBM Bob and in other assistants that read skills, such as Claude Code or Cursor.

Your prompt
AI assistant reads SKILL.md
Learns when and how to call Docling
Converts on the service
docling convert-remote
mddclx
Navigates the result
dclq outline and show
Answer
Grounded in the sections it read

Prerequisites

A Service URL and API key for Docling for IBM watsonx
Python 3.10 or later
An assistant that supports skills, for example IBM Bob

1. Install the tools

pip install docling-client dclq

docling-client provides the docling convert-remote command (docling-slim or the full docling package work too, see Command Line). dclq lets the assistant navigate the DocLang output section by section instead of reading a whole document.

2. Store the credentials

Create a .env file in the root of your workspace. docling convert-remote loads it automatically from the folder it runs in.

.env

DOCLING_SERVICE_URL=https://your-service-url
DOCLING_SERVICE_API_KEY=your-api-key

Add .env to .gitignore. The assistant never needs to see the key: the skill tells it to rely on the .env file rather than to export or print credentials.

3. Create the skill

Create docling-service/SKILL.md in your assistant's skills folder:

Assistant	Skills folder
IBM Bob	`.bob/skills/` in the workspace
Other assistants	the folder your assistant scans for skills, for example `.claude/skills/` for Claude Code

docling-service/SKILL.md

---
name: docling-service
description: >
  Use when the user wants to convert, read or query a document (PDF, DOCX, PPTX,
  XLSX, HTML, EPUB, images, URLs) with the Docling for IBM watsonx service.
  Trigger phrases: "convert", "read this PDF", "what does this document say",
  "find the table", "extract fields from".
---

# Docling for IBM watsonx

Convert documents on the managed service with `docling convert-remote`, then
navigate the DocLang output with `dclq`. No local models are needed.

Credentials come from the `.env` file in the workspace root
(`DOCLING_SERVICE_URL`, `DOCLING_SERVICE_API_KEY`). Never print or export them.
Run commands from the workspace root.

## Convert

Always request Markdown and DocLang together:

    docling convert-remote --to md --to dclx --output ./converted <file-or-url-or-folder>

- Several sources: list them, or pass a folder.
- Only some formats from a folder: `--from pdf --from docx`.
- Born-digital PDF: add `--no-ocr`. Scanned PDF with bad text: `--force-ocr`.
- Classify pictures (chart, diagram, photo, ...): `--enrich-picture-classes`.
- Page subset: `--page-range 1-3`.

Output: `./converted/<name>.md` and `./converted/<name>.dclx`.
Exit code 1 means a connection or conversion failure, 2 means missing credentials.

## Navigate before answering

Do not read a whole document if you only need part of it. Use `dclq` on the
`.dclx` file:

    dclq inspect ./converted/<name>.dclx                          # inventory
    dclq outline ./converted/<name>.dclx                          # headings + XPaths
    dclq grep -i 'pattern' ./converted/<name>.dclx                # find units
    dclq show ./converted/<name>.dclx '/heading[N]' --section     # one section
    dclq list ./converted/<name>.dclx --type table_cell --page 1   # table cells

When you answer, cite the section heading or XPath you used.
Read the Markdown file when the user wants the whole document.

The skill is deliberately short. Add your own conventions, such as an output folder, a naming scheme or a list of documents the assistant should never upload.

4. Use it

In IBM Bob

Bob scans .bob/skills/ when it opens a workspace, so reopen the workspace after you add the skill. The first time Bob uses it, it asks for approval:

Bob's "Tools awaiting approval" prompt for the skill, with the options Approve once, Reject and Approve skill tools for task

Choose Approve skill tools for task so that Bob does not ask again during the conversation. Then just ask:

Convert docs/annual_report.pdf and show me its outline.

Which section of the report covers liquidity risk? Quote the key figures from it.

In other assistants

Put the same folder in your assistant's skills directory. Assistants that do not read skills can still use it: paste the body of SKILL.md into the project instructions file (for example AGENTS.md), since it is only instructions plus two commands.

The upstream Docling skill

The open-source docling package also ships a general usage skill that covers the Python SDK. You can install it with library-skills and link it into Bob's skills folder:

uvx library-skills install --skill docling --all -y
mkdir -p .bob/skills
ln -sf ../../.agents/skills/docling .bob/skills/docling

That skill is aimed at writing Python code with Docling. For converting and reading documents in a conversation, the CLI skill above is shorter and needs no code. See the Docling agent skills documentation for details.

Skill or MCP?

Docling MCP offers the same service to assistants through the Model Context Protocol. Both work. Choose by how you work:

	Agent skill	MCP server
What you install	A Markdown file, plus the `docling` and `dclq` commands	The `docling-mcp` server, plus its configuration in the client
Runs as	Commands in the assistant's terminal	A separate process the client connects to (stdio or HTTP)
Assistant needs	Skill support, or just terminal access	MCP support
Output	Files in your workspace (`.md`, `.dclx`) that you can open, diff and commit	Tool results inside the conversation, plus the server's own cache
Customizing	Edit the Markdown	Change server settings or code
Works without an assistant	Yes, the same commands run in any script	No
Best for	Coding assistants with a workspace, such as IBM Bob, Claude Code and Cursor; reproducible results	Chat clients without a terminal, such as Claude Desktop; teams that share one server

You can also use both: MCP for chat clients, the skill in the IDE.