@unityclaw/skills 1.0.6 → 1.0.9

package/README.md

@@ -1,6 +1,6 @@
 # @unityclaw/skills
 
-UnityClaw Skills - Claude Code and OpenClaw skill definitions for AI-powered image/video generation, media analysis, and document processing.
+UnityClaw Skills for Claude Code and OpenClaw.
 
 ## Installation
 
@@ -14,20 +14,15 @@ npx @unityclaw/skills --help
 
 ## API Key Configuration
 
-All skills require an API key. You can configure it using the SDK CLI:
+All skills require an API key:
 
 ```bash
-# Install SDK globally
 npm install -g @unityclaw/sdk
-
-# Configure API key (stored in ~/.unityclaw/config.json)
 unityclaw-sdk config set apiKey your-api-key
-
-# Verify configuration
 unityclaw-sdk config
 ```
 
-Or set the environment variable:
+Or:
 
 ```bash
 export UNITYCLAW_API_KEY=your-api-key
@@ -35,102 +30,107 @@ export UNITYCLAW_API_KEY=your-api-key
 
 ## CLI Commands
 
-### Install Skills
-
-Install skills to Claude Code or OpenClaw:
-
 ```bash
 # Install all skills to Claude Code
 npx @unityclaw/skills install
 
 # Install specific skills
-npx @unityclaw/skills install unityclaw-image-generation unityclaw-video-generation-sora
+npx @unityclaw/skills install unityclaw-image-generation unityclaw-video-generation-kling
 
 # Install to OpenClaw
 npx @unityclaw/skills install --target openclaw
-```
 
-### List Available Skills
-
-```bash
+# List available skills
 npx @unityclaw/skills list
-```
 
-### Update Packages
+# Update sdk + skills
+npx @unityclaw/skills update
+```
 
-Update SDK and skills to the latest version:
+## Reorganized Skill List
 
-```bash
-# Update local packages
-npx @unityclaw/skills update
+This list is aligned with `~/moox/field-feishu` shortcuts and `server` `ParameterModel` definitions.
 
-# Update global packages
-npx @unityclaw/skills update --global
-```
+- Removed from skill list: `sora/*`, `veo/*`
+- No version-level split for same model family (for example, no separate `jimeng-image-v3` skill)
+- Document conversion is abstracted as one skill/API entry instead of many individual shortcut skills
 
-### Execute Skills Directly
+### Image
 
-Execute a skill via Claude Code CLI:
+- [unityclaw-image-generation](./unityclaw-image-generation/SKILL.md)
+: Covers `gemini/image/v2` + `jimeng/image` (unified)
+- [unityclaw-image-compress](./unityclaw-image-compress/SKILL.md)
+: Covers `image/compress`
 
-```bash
-# Generate an image
-npx @unityclaw/skills /unityclaw-image-generation 我要一张竖屏的桌面背景图
+### Video
 
-# Analyze a video
-npx @unityclaw/skills /unityclaw-media-analysis https://youtube.com/watch?v=...
-```
+- [unityclaw-video-generation-kling](./unityclaw-video-generation-kling/SKILL.md)
+: Covers `kling/video`
+- [unityclaw-video-generation-jimeng-doubao](./unityclaw-video-generation-jimeng-doubao/SKILL.md)
+: Covers `jimeng/video`, `doubao/video`
+- [unityclaw-video-generation-wan-minimax](./unityclaw-video-generation-wan-minimax/SKILL.md)
+: Covers `wan/video`, `minimax/video`
 
-## Available Skills
+### Document
 
-### Image Skills
+- [unityclaw-document-translation](./unityclaw-document-translation/SKILL.md)
+: Covers `doc/translate`
+- [unityclaw-document-convert](./unityclaw-document-convert/SKILL.md)
+: Covers generic `doc_convert/image` + `doc_convert/pdf`
 
-| Skill | Description | Emoji |
-|-------|-------------|-------|
-| [unityclaw-image-generation](./unityclaw-image-generation/SKILL.md) | Generate images using Gemini or JiMeng models | 🎨 |
-| [unityclaw-image-compress](./unityclaw-image-compress/SKILL.md) | Compress images with quality control | 🗜️ |
+### Media
 
-### Video Skills
-| Skill | Description | Emoji |
-|-------|-------------|-------|
-| [unityclaw-video-generation-kling](./unityclaw-video-generation-kling/SKILL.md) | Generate videos using Kling AI | 📹 |
-| [unityclaw-video-generation-other](./unityclaw-video-generation-other/SKILL.md) | Generate videos using Doubao, Wan, MiniMax, JiMeng | 🎞️ |
+- [unityclaw-media-analysis](./unityclaw-media-analysis/SKILL.md)
+: Covers `media_analysis`
+- [unityclaw-media-stats](./unityclaw-media-stats/SKILL.md)
+: Covers `media_stats`
+- [unityclaw-media-user-info](./unityclaw-media-user-info/SKILL.md)
+: Covers `media_user_info`
+- [unityclaw-media-download-xhs](./unityclaw-media-download-xhs/SKILL.md)
+: Covers `xiaohongshu/download`
+- [unityclaw-video-frame-extract](./unityclaw-video-frame-extract/SKILL.md)
+: Covers `video/frame`
 
-### Document Skills
+### IDP
 
-| Skill | Description | Emoji |
-|-------|-------------|-------|
-| [unityclaw-document-translation](./unityclaw-document-translation/SKILL.md) | Translate documents between languages | 🌐 |
-| [unityclaw-document-convert](./unityclaw-document-convert/SKILL.md) | Convert document formats (PDF/Word/PPT/Excel/Image) | 📄 |
+- [unityclaw-idp-personal-documents](./unityclaw-idp-personal-documents/SKILL.md)
+: Covers `idp/id_card`, `idp/vehicle_license`, `idp/bank_card`
+- [unityclaw-idp-invoice-extraction](./unityclaw-idp-invoice-extraction/SKILL.md)
+: Covers `idp/vat_invoice`, `idp/train_invoice`, `idp/taxi_invoice`
+- [unityclaw-idp-business-extraction](./unityclaw-idp-business-extraction/SKILL.md)
+: Covers `idp/business_license`, `idp/business_card`
+- [unityclaw-idp-contract-extraction](./unityclaw-idp-contract-extraction/SKILL.md)
+: Covers `idp/contract`
 
-### Media Skills
+IDP is intentionally split by scenario (personal/invoice/business/contract), instead of one generic skill, to improve skill routing accuracy and parameter selection success.
 
-| Skill | Description | Emoji |
-|-------|-------------|-------|
-| [unityclaw-media-analysis](./unityclaw-media-analysis/SKILL.md) | Analyze video/audio content and extract insights | 📊 |
+## Local File Input Support
 
-## Programmatic Usage
+With latest SDK, skill examples can use local file paths directly:
 
-```typescript
-import { listSkills, installSkills, executeSkill } from '@unityclaw/skills';
+```ts
+attachment: [{ path: './files/input.pdf' }]
+```
 
-// List available skills
-const skills = await listSkills();
-console.log(skills);
+SDK will auto-upload the local file through `/api/upload` and replace it with a valid `tmp_url`.
 
-// Install skills to Claude Code
-await installSkills('claude', ['unityclaw-image-generation']);
+## Parameter Normalization Notes
 
-// Install all skills to OpenClaw
-await installSkills('openclaw');
+Only endpoints that **require** field-feishu structures are normalized.
 
-// Execute a skill
-await executeSkill('/unityclaw-image-generation A beautiful sunset');
-```
+- Text array conversion (`string` -> `[{ type: 'text', text: '...' }]`) is applied only for:
+  `jimeng/image`, `jimeng/image/v3`, `sora/video`, `sora/video/stable`, `veo/video`, `jimeng/video`, `doubao/video`.
+- Label conversion (`'16:9'` -> `{ value: '16:9', label: '16:9' }`) is applied only for endpoints whose `ParameterModel` expects `LabelFieldItem`.
+- For `doubao/video`, duration should use numeric value in `LabelFieldItem.value` when provided (for example `{ value: 5, label: '5' }`).
+- Endpoints that already support plain strings are kept as-is (no forced conversion).
+- If you pass full field-feishu structures, SDK keeps them unchanged.
 
-## SDK Documentation
+## Skill Version Rule
 
-- [npm: @unityclaw/sdk](https://www.npmjs.com/package/@unityclaw/sdk)
-- [UnityClaw Homepage](https://unityclaw.com)
+- Every `unityclaw-*/SKILL.md` frontmatter `version` is auto-synced to `skills/package.json` version during `npm run build`.
+- Every `SKILL.md` also contains an `SDK Version Check Rule` block:
+  - If local `@unityclaw/sdk` version is lower than the skill version, agent should stop and prompt SDK upgrade first.
+  - Suggested command: `npm i @unityclaw/sdk@latest`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unityclaw/skills",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "description": "UnityClaw Skills - Claude Code and OpenClaw skill definitions for AI-powered image/video generation, media analysis, and more",
   "type": "module",
   "bin": {
@@ -19,7 +19,8 @@
     "unityclaw-*/SKILL.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean",
+    "sync:skill-metadata": "node scripts/sync-skill-metadata.mjs",
+    "build": "npm run sync:skill-metadata && tsup src/index.ts src/cli.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --watch",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build"

package/unityclaw-document-convert/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unityclaw-document-convert
 description: Convert documents between formats (PDF, Word, PPT, Excel, Image)
-version: 1.0.1
+version: 1.0.9
 metadata:
   openclaw:
     requires:
@@ -22,6 +22,7 @@ metadata:
 # UnityClaw Document Convert
 
 Convert documents between various formats including PDF, Word, PowerPoint, Excel, and images.
+Recommended API is unified `client.document.convertDocument(...)`.
 
 ## Installation
 
@@ -71,11 +72,13 @@ import { UnityClawClient } from '@unityclaw/sdk';
 
 const client = new UnityClawClient();
 
-// Convert PDF to Word
-const result = await client.document.pdf2Word({
+// Convert PDF to Word (unified API)
+const result = await client.document.convertDocument({
   attachment: [
-    { tmp_url: 'https://example.com/document.pdf', name: 'document.pdf' }
-  ]
+    { path: './files/document.pdf' }
+  ],
+  input_format: 'pdf',
+  output_format: 'docx'
 });
 
 // ✅ Correct: Check result.success, access data via result.response.data
@@ -108,6 +111,7 @@ if (result.success && result.response?.data) {
 
 | Method | Description |
 |--------|-------------|
+| `convertDocument()` | Recommended unified conversion API |
 | `convert()` | Generic conversion with format specification |
 
 ## API Reference
@@ -409,3 +413,12 @@ console.log('Downloaded Files:', result.attachments);
 
 - [unityclaw-document-translation](../unityclaw-document-translation/SKILL.md) - Translate documents
 - [unityclaw-image-compress](../unityclaw-image-compress/SKILL.md) - Compress images before conversion
+
+<!-- SDK_VERSION_RULE_START -->
+## SDK Version Check Rule
+
+- Before invoking this skill, check local `@unityclaw/sdk` version.
+- Required minimum SDK version: `1.0.9`
+- If local SDK version is lower than this skill version, stop and prompt user to upgrade SDK first.
+- Suggested command: `npm i @unityclaw/sdk@latest`
+<!-- SDK_VERSION_RULE_END -->

package/unityclaw-document-translation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unityclaw-document-translation
 description: Translate documents between multiple languages while preserving formatting
-version: 1.0.1
+version: 1.0.9
 metadata:
   openclaw:
     requires:
@@ -73,7 +73,7 @@ const client = new UnityClawClient();
 
 const result = await client.document.translate({
   attachment: [
-    { tmp_url: 'https://example.com/document.pdf', name: 'document.pdf' }
+    { path: './files/document.pdf' }
   ],
   source_language: { value: 'en', label: 'English' },
   target_language: { value: 'zh', label: 'Chinese' }
@@ -307,3 +307,12 @@ console.log('Downloaded Files:', result.attachments);
 
 - [unityclaw-document-convert](../unityclaw-document-convert/SKILL.md) - Convert document formats
 - [unityclaw-media-analysis](../unityclaw-media-analysis/SKILL.md) - Analyze video/audio content
+
+<!-- SDK_VERSION_RULE_START -->
+## SDK Version Check Rule
+
+- Before invoking this skill, check local `@unityclaw/sdk` version.
+- Required minimum SDK version: `1.0.9`
+- If local SDK version is lower than this skill version, stop and prompt user to upgrade SDK first.
+- Suggested command: `npm i @unityclaw/sdk@latest`
+<!-- SDK_VERSION_RULE_END -->

package/unityclaw-idp-business-extraction/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: unityclaw-idp-business-extraction
+description: Extract fields from business documents (business license, business card)
+version: 1.0.9
+metadata:
+  openclaw:
+    requires:
+      env:
+        - UNITYCLAW_API_KEY
+      bins:
+        - node
+        - npm
+    primaryEnv: UNITYCLAW_API_KEY
+    emoji: "🏢"
+    homepage: https://unityclaw.com
+    install:
+      - kind: node
+        package: "@unityclaw/sdk"
+        bins: []
+---
+
+# UnityClaw IDP - Business Extraction
+
+Use this skill for business document extraction:
+- `business_license`
+- `business_card`
+
+## SDK APIs
+
+```typescript
+await client.idp.businessLicense({ attachments: [{ path: './files/business-license.jpg' }] });
+await client.idp.businessCard({ attachments: [{ path: './files/business-card.jpg' }] });
+```
+
+Or generic API:
+
+```typescript
+await client.idp.extract('business_license', {
+  attachments: [{ path: './files/business-license.jpg' }]
+});
+```
+
+## Input
+
+```typescript
+{
+  attachments: AttachmentInput[]
+}
+```
+
+## Notes
+
+- This skill groups enterprise scenarios to avoid over-generic routing.
+- Output fields vary between license and card extraction.
+
+<!-- SDK_VERSION_RULE_START -->
+## SDK Version Check Rule
+
+- Before invoking this skill, check local `@unityclaw/sdk` version.
+- Required minimum SDK version: `1.0.9`
+- If local SDK version is lower than this skill version, stop and prompt user to upgrade SDK first.
+- Suggested command: `npm i @unityclaw/sdk@latest`
+<!-- SDK_VERSION_RULE_END -->

package/unityclaw-idp-contract-extraction/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: unityclaw-idp-contract-extraction
+description: Extract structured fields from contract files
+version: 1.0.9
+metadata:
+  openclaw:
+    requires:
+      env:
+        - UNITYCLAW_API_KEY
+      bins:
+        - node
+        - npm
+    primaryEnv: UNITYCLAW_API_KEY
+    emoji: "📑"
+    homepage: https://unityclaw.com
+    install:
+      - kind: node
+        package: "@unityclaw/sdk"
+        bins: []
+---
+
+# UnityClaw IDP - Contract Extraction
+
+Use this skill for contract parsing:
+- `contract`
+
+## SDK APIs
+
+```typescript
+await client.idp.contract({
+  attachments: [{ path: './files/contract.pdf' }]
+});
+```
+
+Or generic API:
+
+```typescript
+await client.idp.extract('contract', {
+  attachments: [{ path: './files/contract.pdf' }]
+});
+```
+
+## Input
+
+```typescript
+{
+  attachments: AttachmentInput[]
+}
+```
+
+## Notes
+
+- Preferred for long contract OCR + key field extraction scenarios.
+- Read extracted data from `result.response.data`.
+
+<!-- SDK_VERSION_RULE_START -->
+## SDK Version Check Rule
+
+- Before invoking this skill, check local `@unityclaw/sdk` version.
+- Required minimum SDK version: `1.0.9`
+- If local SDK version is lower than this skill version, stop and prompt user to upgrade SDK first.
+- Suggested command: `npm i @unityclaw/sdk@latest`
+<!-- SDK_VERSION_RULE_END -->

package/unityclaw-idp-invoice-extraction/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: unityclaw-idp-invoice-extraction
+description: Extract fields from invoice and ticket documents (VAT, train, taxi)
+version: 1.0.9
+metadata:
+  openclaw:
+    requires:
+      env:
+        - UNITYCLAW_API_KEY
+      bins:
+        - node
+        - npm
+    primaryEnv: UNITYCLAW_API_KEY
+    emoji: "🧾"
+    homepage: https://unityclaw.com
+    install:
+      - kind: node
+        package: "@unityclaw/sdk"
+        bins: []
+---
+
+# UnityClaw IDP - Invoice Extraction
+
+Use this skill for invoice/ticket extraction:
+- `vat_invoice`
+- `train_invoice`
+- `taxi_invoice`
+
+## SDK APIs
+
+```typescript
+await client.idp.vatInvoice({ attachments: [{ path: './files/vat-invoice.pdf' }] });
+await client.idp.trainInvoice({ attachments: [{ path: './files/train-ticket.jpg' }] });
+await client.idp.taxiInvoice({ attachments: [{ path: './files/taxi-invoice.jpg' }] });
+```
+
+Or generic API:
+
+```typescript
+await client.idp.extract('vat_invoice', {
+  attachments: [{ path: './files/vat-invoice.pdf' }]
+});
+```
+
+## Input
+
+```typescript
+{
+  attachments: AttachmentInput[]
+}
+```
+
+## Notes
+
+- Files can be image/PDF according to each underlying IDP type.
+- Output schema differs by type; parse from `result.response.data`.
+
+<!-- SDK_VERSION_RULE_START -->
+## SDK Version Check Rule
+
+- Before invoking this skill, check local `@unityclaw/sdk` version.
+- Required minimum SDK version: `1.0.9`
+- If local SDK version is lower than this skill version, stop and prompt user to upgrade SDK first.
+- Suggested command: `npm i @unityclaw/sdk@latest`
+<!-- SDK_VERSION_RULE_END -->

package/unityclaw-idp-personal-documents/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: unityclaw-idp-personal-documents
+description: Extract structured fields from personal identity documents (ID card, vehicle license, bank card)
+version: 1.0.9
+metadata:
+  openclaw:
+    requires:
+      env:
+        - UNITYCLAW_API_KEY
+      bins:
+        - node
+        - npm
+    primaryEnv: UNITYCLAW_API_KEY
+    emoji: "🪪"
+    homepage: https://unityclaw.com
+    install:
+      - kind: node
+        package: "@unityclaw/sdk"
+        bins: []
+---
+
+# UnityClaw IDP - Personal Documents
+
+Use this skill for personal document extraction:
+- `id_card`
+- `vehicle_license`
+- `bank_card`
+
+## SDK APIs
+
+```typescript
+await client.idp.idCard({ attachments: [{ path: './files/id-card.jpg' }] });
+await client.idp.vehicleLicense({ attachments: [{ path: './files/vehicle-license.jpg' }] });
+await client.idp.bankCard({ attachments: [{ path: './files/bank-card.jpg' }] });
+```
+
+Or generic API:
+
+```typescript
+await client.idp.extract('id_card', {
+  attachments: [{ path: './files/id-card.jpg' }]
+});
+```
+
+## Input
+
+```typescript
+{
+  attachments: AttachmentInput[]
+}
+```
+
+`AttachmentInput` supports:
+- `tmp_url`
+- local path (`path` / `localPath` / `filePath`), SDK auto-uploads to `/api/upload`
+
+## Notes
+
+- This category is split from invoice/business/contract to improve skill routing success.
+- Output fields vary by type; read from `result.response.data`.
+
+<!-- SDK_VERSION_RULE_START -->
+## SDK Version Check Rule
+
+- Before invoking this skill, check local `@unityclaw/sdk` version.
+- Required minimum SDK version: `1.0.9`
+- If local SDK version is lower than this skill version, stop and prompt user to upgrade SDK first.
+- Suggested command: `npm i @unityclaw/sdk@latest`
+<!-- SDK_VERSION_RULE_END -->

package/unityclaw-image-compress/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unityclaw-image-compress
 description: Compress images with quality control to reduce file size
-version: 1.0.1
+version: 1.0.9
 metadata:
   openclaw:
     requires:
@@ -263,3 +263,12 @@ console.log('Local Attachments:', result.attachments);
 ## Related Skills
 
 - [unityclaw-image-generation](../unityclaw-image-generation/SKILL.md) - Generate images before compression
+
+<!-- SDK_VERSION_RULE_START -->
+## SDK Version Check Rule
+
+- Before invoking this skill, check local `@unityclaw/sdk` version.
+- Required minimum SDK version: `1.0.9`
+- If local SDK version is lower than this skill version, stop and prompt user to upgrade SDK first.
+- Suggested command: `npm i @unityclaw/sdk@latest`
+<!-- SDK_VERSION_RULE_END -->