--- name: kolmopdf-setup description: Install and configure the official KolmoPDF skill for the current AI agent. Use for onboarding, not for processing documents. --- # Set up KolmoPDF KolmoPDF is a cloud service for PDF to Markdown/OCR, layout-preserving PDF translation, and Markdown export to Word, PDF, HTML, or LaTeX. This is the official setup guide at https://www.kolmopdf.com/agent-setup/SKILL.md. You do not need to search for an installer or know the product beforehand. ## 1. Choose the existing or simplest integration Identify the current agent and operating system. If the target is unclear, ask which agent to configure. Follow that agent's permissions and the user's installation scope. If a working KolmoPDF skill, plugin, or MCP integration already exists, reuse it. Do not overwrite working credentials, automatically upgrade it, or install duplicate integrations. For Claude Code, Codex, or Cursor in Agent mode, the default is the **standalone skill**: - Official repository: https://github.com/komoai2026/kolmopdf-skill - The skill calls Jobs API v1 directly; MCP is optional. - Install the complete package, including `references/` and `scripts/`. Do not save this setup guide as the processing skill or download only an isolated `SKILL.md`. A chat-only client that cannot run commands cannot install the skill. Give manual instructions instead of claiming installation succeeded. ## 2. Install for the target agent Use the existing Node/npm environment. The processing skill bundles a Node.js Jobs API helper and does not require `jq`, GNU `timeout`, Homebrew coreutils, or PowerShell-specific rewrites. Prefer that helper or the MCP tools over rebuilding the workflow as shell one-liners. Do not silently install a new runtime/version manager. Interactive installation: ```bash npx skills add komoai2026/kolmopdf-skill ``` Choose only the current agent. Default to user-level installation unless the user or project requires project scope. For a non-interactive installation, select **one** matching command: ```bash # Claude Code npx skills add komoai2026/kolmopdf-skill --skill kolmopdf --agent claude-code --global --yes # Codex npx skills add komoai2026/kolmopdf-skill --skill kolmopdf --agent codex --global --yes # Cursor npx skills add komoai2026/kolmopdf-skill --skill kolmopdf --agent cursor --global --yes ``` Omit `--global` for an explicitly requested project-local install. If a prerequisite is missing or a client cannot run the installer, explain the specific blocker and the minimum manual step. Do not configure every installed agent. ## 3. Configure the user's API key Reuse `KOLMOPDF_API_KEY` from the agent's actual command environment, or an existing authenticated KolmoPDF MCP configuration. Check presence without printing the secret. If no usable key is available, ask the user to sign in and create one at https://www.kolmopdf.com/api-keys. Free, PAYG, Go, and Plus accounts can create one key; Pro supports up to ten. A subscription is not required. Web, API, and MCP share the account's credits. Have the user configure the key privately in the environment or private settings used to launch their agent. Never ask them to paste the key into this conversation. Do not put it in project files, logs, URLs, or the setup prompt. The following are **placeholders for the user's terminal**, not commands to execute with a dummy key: ```bash export KOLMOPDF_API_KEY='YOUR_API_KEY' ``` ```powershell $env:KOLMOPDF_API_KEY = 'YOUR_API_KEY' ``` These affect that shell and processes launched from it. Setting a variable in a different terminal does not update an already-running agent or IDE. On macOS, Finder/Dock-launched apps do not automatically inherit a Terminal `export`; use the client's private MCP environment or launch the agent from the configured shell. Restart from the configured environment. Do not invent a key-file location that the skill does not read. This integration uses API keys; there is no KolmoPDF browser OAuth or automatic credential transfer in this setup flow. Do not create, replace, or revoke keys on the user's behalf as a side effect of installation. ## 4. Check readiness without processing a document Confirm that the target agent has the `kolmopdf` skill and its references. For example, list user-level Claude Code skills with: ```bash npx skills list --global --agent claude-code ``` Adjust the agent and scope to the installation. Some clients need a restart or skill refresh before the current session can discover a newly installed skill. Verify authentication with the existing `kolmopdf_check_balance` MCP tool, or one read-only request from the **same environment the agent will use**: ```text GET https://www.kolmopdf.com/api/v1/balance Authorization: Bearer ``` Keep the key out of visible output. Report authentication status and credits, not the full response or credential. Zero credits means authentication can still be valid. If credits are insufficient for a later task, direct the user to https://www.kolmopdf.com/credits or the API's returned purchase URL; do not purchase automatically. Report the actual state: - **Installed; key setup required** when authentication is missing. - **Configured; restart/refresh required** when the current session has not loaded the skill. - **Ready** only when the skill/tools are available and authentication has been checked. Do not upload a PDF, create a paid job, or spend processing credits to test installation. Setup is not permission to process arbitrary local files. ## 5. Start useful work Read the installed `kolmopdf` skill and follow its existing routing and cost rules. Continue the user's original task if one was provided. Otherwise, give a short invitation such as: > KolmoPDF is ready. Send a file or its path and tell me whether to parse it to Markdown, translate the PDF, or export Markdown to Word/PDF. For example: “Use KolmoPDF to convert this PDF to Markdown, keeping formulas and tables.” Estimate the cost and follow the skill's upload/approval rules before processing. Do not substitute a demo task for the user's goal. ## Other supported installation paths Use these only when requested or when the client needs an MCP integration instead of a standalone skill. ### Claude Code native plugin The plugin bundles the skill and MCP configuration. Adding the marketplace and installing the plugin are separate steps: ```text /plugin marketplace add komoai2026/claude-plugin /plugin install kolmopdf@kolmopdf ``` Configure `KOLMOPDF_API_KEY` and refresh/restart as required. Do not install the standalone skill again alongside the plugin. ### MCP clients The existing server is `@kolmopdf/mcp-server`, requires Node.js 20+, and runs locally over stdio using `npx -y @kolmopdf/mcp-server`. It reads `KOLMOPDF_API_KEY` from its environment and writes results under `~/kolmopdf-output` unless `KOLMOPDF_OUTPUT_DIR` is set. Configure it through the client's MCP settings; it is not a hosted HTTP/OAuth endpoint. For macOS GUI clients, run `command -v npx` in Terminal and use the returned absolute path as the MCP `command` if bare `npx` fails with `ENOENT`. Keep the API key in the client's private `env` block, then fully quit and reopen the app. The server accesses files on the machine where it runs. Do not assume a remote chat client can read a path on the user's computer. - Plugin and MCP documentation: https://github.com/komoai2026/claude-plugin - Client setup guide: https://github.com/komoai2026/claude-plugin/blob/main/doc/plan/TESTING_AND_USAGE.md - Website setup guide: https://www.kolmopdf.com/api-docs#ai-agent-setup - API reference: https://www.kolmopdf.com/api-docs - Standalone processing skill: https://github.com/komoai2026/kolmopdf-skill