docs(skills): prefer host-managed environment variables (#17792)

* docs(skills): prefer host-managed environment variables

* docs(skills): add readme prerequisites

* docs(skills): clarify smoke test env setup

* docs(skills): simplify smoke test wording

* docs(skills): merge readme guidance into env-first pr

* Apply suggestion from @Bobholamovic

* Update skills/paddleocr-text-recognition/scripts/smoke_test.py

Co-authored-by: Lin Manhui <mhlin425@whu.edu.cn>

* docs(skills): refine review wording in guides

* docs(skills): complete readme setup steps

* docs(skills): clarify install and usage flow

* Update docs and fix bugs

---------

Co-authored-by: Lin Manhui <mhlin425@whu.edu.cn>
Co-authored-by: Bobholamovic <bob1998425@hotmail.com>

Author: Aidenwu0209

skills/.env.example

@@ -32,7 +32,7 @@ PADDLEOCR_DOC_PARSING_API_URL=
 # ============================================
 
 # Request timeout (milliseconds, default 25000)
-# PADDLEOCR_TIMEOUT_MS=25000
+# PADDLEOCR_OCR_TIMEOUT=25000
 
 # Log level (DEBUG/INFO/WARNING/ERROR, default INFO)
 # PADDLEOCR_LOG_LEVEL=INFO

skills/README.ch.md

@@ -1,36 +1,177 @@
 # PaddleOCR Skills
 
-This directory contains AI agent skills for PaddleOCR official APIs.
+This directory contains official PaddleOCR Agent Skills. They integrate with AI apps such as Claude Code for OCR text extraction from images/PDFs and layout-aware document parsing.
 
 ## Included Skills
 
-- `paddleocr-text-recognition`: OCR text extraction for images/PDFs.
-- `paddleocr-doc-parsing`: document parsing for layout-aware extraction.
+- `paddleocr-text-recognition`: extract text from images/PDFs.
+- `paddleocr-doc-parsing`: document parsing that converts images/PDFs to Markdown.
 
-## Quick Start
+## Prerequisites
 
-1. Install dependencies for the skill you use.
-2. Configure API credentials interactively:
-   ```bash
-   python skills/paddleocr-text-recognition/scripts/configure.py
-   ```
-   Or manually copy `.env.example` to `.env` and fill in your credentials: `cp skills/.env.example skills/.env`
-3. Run smoke tests:
+1. Python 3.8 or later must be installed on the device that runs the skill.
+2. These skills depend on PaddleOCR official APIs and require API credentials. Visit the [PaddleOCR website](https://www.paddleocr.com), click **API**, select the model you need, then copy the `API_URL` and `Token`. They correspond to the API URL and access token used for authentication. Supported models per skill:
+   - `paddleocr-text-recognition`: `PP-OCRv5`
+   - `paddleocr-doc-parsing`: `PP-StructureV3`, `PaddleOCR-VL`, `PaddleOCR-VL-1.5`
+
+## Using in AI Apps
+
+### Install to AI Apps
+
+#### Option 1: Install via `skills` CLI
+
+The `skills` CLI installs skills globally on the device so all AI apps can use them. [Node.js](https://nodejs.org/en/download) is required.
+
+```shell
+npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-text-recognition -y
+npx skills add PaddlePaddle/PaddleOCR -g --skill paddleocr-doc-parsing -y
+```
+
+> This repository is relatively large. On slower networks, `npx skills add` may time out. If that happens, clone the repository locally first, then install from the local path:
+>
+> ```shell
+> git clone https://github.com/PaddlePaddle/PaddleOCR.git
+> npx skills add ./PaddleOCR/skills/paddleocr-text-recognition
+> ```
+
+#### Option 2: Install via `clawhub` (OpenClaw)
+
+```shell
+clawhub install paddleocr-text-recognition
+clawhub install paddleocr-doc-parsing
+```
+
+See the [OpenClaw Skills documentation](https://docs.openclaw.ai/tools/skills) for details.
+
+#### Option 3: Manual installation
 
-```bash
-python skills/paddleocr-text-recognition/scripts/smoke_test.py
-python skills/paddleocr-doc-parsing/scripts/smoke_test.py
+If the above options are not available, you can clone the repository and manually copy the skill directories to the location required by your AI app ([Git](https://git-scm.com/downloads) required):
+
+```shell
+git clone https://github.com/PaddlePaddle/PaddleOCR.git
 ```
 
-## Documentation
+After cloning, skill source code is located under `PaddleOCR/skills`. Refer to the documentation for your AI app to complete installation:
+
+- Claude Code: <https://code.claude.com/docs/en/skills>
+- claude.ai: <https://support.claude.com/en/articles/12512180-use-skills-in-claude>
+- OpenClaw: <https://docs.openclaw.ai/tools/skills>
+
+### Configure Environment Variables
+
+After installation, configure the required environment variables so the skills can work properly. Each skill requires the following:
+
+| Skill | Required | Optional |
+| --- | --- | --- |
+| `paddleocr-text-recognition` | `PADDLEOCR_OCR_API_URL` (API URL), `PADDLEOCR_ACCESS_TOKEN` (access token) | `PADDLEOCR_OCR_TIMEOUT` (timeout) |
+| `paddleocr-doc-parsing` | `PADDLEOCR_DOC_PARSING_API_URL` (API URL), `PADDLEOCR_ACCESS_TOKEN` (access token) | `PADDLEOCR_DOC_PARSING_TIMEOUT` (timeout) |
+
+You can ask the AI in natural language (e.g., "I need to configure paddleocr-text-recognition skill"), or configure manually. Below are manual configuration methods for some AI apps:
+
+- **Claude Code**: add an `env` field to `.claude/settings.local.json` in your project:
 
-- Text recognition: `skills/paddleocr-text-recognition/SKILL.md`
-- Doc parsing: `skills/paddleocr-doc-parsing/SKILL.md`
+  ```json
+  {
+    "env": {
+      "PADDLEOCR_ACCESS_TOKEN": "<ACCESS_TOKEN>",
+      "PADDLEOCR_OCR_API_URL": "<OCR_API_URL>",
+      "PADDLEOCR_DOC_PARSING_API_URL": "<DOC_PARSING_API_URL>"
+    }
+  }
+  ```
 
-## API Access
+- **OpenClaw**: add skill configuration to `~/.openclaw/openclaw.json`:
 
-Get API credentials from the PaddleOCR official website: <https://www.paddleocr.com>
+  ```json
+  {
+    "skills": {
+      "entries": {
+        "paddleocr-text-recognition": {
+          "enabled": true,
+          "apiKey": "<ACCESS_TOKEN>",
+          "env": {
+            "PADDLEOCR_OCR_API_URL": "<OCR_API_URL>"
+          }
+        },
+        "paddleocr-doc-parsing": {
+          "enabled": true,
+          "apiKey": "<ACCESS_TOKEN>",
+          "env": {
+            "PADDLEOCR_DOC_PARSING_API_URL": "<DOC_PARSING_API_URL>"
+          }
+        }
+      }
+    }
+  }
+  ```
+
+### Usage Examples
+
+After configuration, describe the OCR or document parsing task in natural language and provide a file URL or local path so the AI app can invoke the corresponding skill.
+
+**paddleocr-text-recognition**
+
+URL example:
+
+```text
+Extract all text from this file: https://example.com/invoice.jpg
+```
 
-## License
+Local file example:
 
-[Apache License 2.0](../LICENSE)
+```text
+Extract all text from local file C:\docs\invoice.pdf
+```
+
+**paddleocr-doc-parsing**
+
+URL example:
+
+```text
+Parse this PDF and return the main body plus all tables: https://example.com/report.pdf
+```
+
+Local file example:
+
+```text
+Parse local file C:\docs\report.pdf and return complete structured output.
+```
+
+## Local Testing
+
+This section describes how to run smoke tests locally to verify that the skills work correctly.
+
+> The examples below cover both skills. Run only the commands for the skill you need.
+
+Make sure your working directory is the directory containing this file.
+
+1. Install dependencies.
+
+   ```shell
+   python -m pip install -r paddleocr-text-recognition/scripts/requirements.txt
+   python -m pip install -r paddleocr-doc-parsing/scripts/requirements.txt
+   # Optional: required only when using document file optimization
+   python -m pip install -r paddleocr-doc-parsing/scripts/requirements-optimize.txt
+   ```
+
+2. Configure environment variables (see [Configure Environment Variables](#configure-environment-variables) for the list of variables). Choose one of the following methods:
+
+   **Option A**: run the interactive configuration script.
+
+   ```shell
+   python paddleocr-text-recognition/scripts/configure.py
+   python paddleocr-doc-parsing/scripts/configure.py
+   ```
+
+   **Option B**: create a local `.env` file from the `.env.example` template and fill in the required variables.
+
+   ```shell
+   cp .env.example .env
+   ```
+
+3. Run the smoke test scripts.
+
+   ```shell
+   python paddleocr-text-recognition/scripts/smoke_test.py
+   python paddleocr-doc-parsing/scripts/smoke_test.py
+   ```