dingtom336-gif

---
name: explore-thailand
description: "Plan your Thailand adventure — Bangkok temples and street food, Chiang Mai elephants and night bazaar, Phuket beaches, Koh Samui islands, and Thai massage. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: explore-thailand

## Overview

Plan your Thailand adventure — Bangkok temples and street food, Chiang Mai elephants and night bazaar, Phuket beaches, Koh Samui islands, and Thai massage.

## When to Activate

User query contains:
- English: "Thailand", "Bangkok", "Chiang Mai", "Phuket"
- Chinese: "泰国", "曼谷", "清迈", "普吉岛", "去泰国"

Do NOT activate for: Japan → `explore-japan`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

This skill orchestrates multiple CLI commands. See each command's parameters below:

### search-flight
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | 3 (price ascending) |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |

### search-hotel
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | Default: rate_desc |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |

### search-poi
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | See Domain Knowledge for category list |

### keyword-search
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Multi-command orchestration

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Full Thailand

**Trigger:** "Thailand trip"

```bash
visa info + flights to BKK/CNX + hotels + temples/beaches
```

**Output:** Complete Thailand itinerary.

### Playbook B: Bangkok

**Trigger:** "Bangkok trip"

```bash
Flight to BKK + Bangkok hotel + temple/market/food POIs
```

**Output:** Bangkok city experience.

### Playbook C: Islands

**Trigger:** "Thai islands"

```bash
Flight to Phuket/Samui + beach resort + island activities
```

**Output:** Thai island hopping.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Shanghai" --destination "Bangkok" --dep-date 2026-12-01 --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Thailand: visa-free for Chinese passport holders (as of recent policy). Airports: BKK (Suvarnabhumi, international), DMK (Don Mueang, budget airlines), CNX (Chiang Mai), HKT (Phuket). Best season: Nov-Feb (cool, dry). Monsoon: Jun-Oct. Temples: dress modestly, remove shoes. Thai massage: ฿300-800 for 1-2 hours.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# explore-thailand

Plan your Thailand adventure — Bangkok temples and street food, Chiang Mai elephants and night bazaar, Phuket beaches, Koh Samui islands, and Thai massage.

## Overview

Plan your Thailand adventure — Bangkok temples and street food, Chiang Mai elephants and night bazaar, Phuket beaches, Koh Samui islands, and Thai massage. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install explore-thailand
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/explore-thailand
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Plan your Thailand adventure — Bangkok temples and street food, Chiang Mai elephants and night bazaar, Phuket beaches, Koh Samui islands, and Thai massage.

**Command type:** Multi-command orchestration

## File Structure

```
explore-thailand/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# explore-thailand（中文说明）

规划泰国之旅——曼谷寺庙和街头美食、清迈大象和夜市、普吉海滩、苏梅岛和泰式按摩。

## 概述

规划泰国之旅——曼谷寺庙和街头美食、清迈大象和夜市、普吉海滩、苏梅岛和泰式按摩。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install explore-thailand
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — explore-thailand

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🌏 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🌏 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🌏 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🌏 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Destination Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights to Destination

```bash
flyai search-flight ... --dep-date-start "{date-7}" --dep-date-end "{date+7}" --sort-type 3
flyai search-flight ... --destination "{alt_city}" --sort-type 3
flyai keyword-search --query "{origin} to {country} flights"
```

## Case 2: Hotel Coverage Limited

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
→ Note "Limited coverage for this destination"
```

## Case 3: Visa Info Unavailable

```
→ Use domain knowledge as fallback + tag "⚠️ General info. Check consulate for latest policy."
```

## Case 4: Partial Failure

```
→ Show successful parts, mark failures, provide manual retry commands
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — explore-thailand

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Full Thailand

**Trigger:** "Thailand trip"

```bash
visa info + flights to BKK/CNX + hotels + temples/beaches
```

**Output emphasis:** Complete Thailand itinerary.

---

## Playbook B: Bangkok

**Trigger:** "Bangkok trip"

```bash
Flight to BKK + Bangkok hotel + temple/market/food POIs
```

**Output emphasis:** Bangkok city experience.

---

## Playbook C: Islands

**Trigger:** "Thai islands"

```bash
Flight to Phuket/Samui + beach resort + island activities
```

**Output emphasis:** Thai island hopping.

---

---
name: explore-singapore
description: "Plan your Singapore visit — Marina Bay Sands, Gardens by the Bay, Sentosa Island, hawker center food trails, and multicultural neighborhood walks. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: explore-singapore

## Overview

Plan your Singapore visit — Marina Bay Sands, Gardens by the Bay, Sentosa Island, hawker center food trails, and multicultural neighborhood walks.

## When to Activate

User query contains:
- English: "Singapore", "Marina Bay", "Sentosa", "Gardens by the Bay"
- Chinese: "新加坡", "滨海湾", "圣淘沙", "狮城"

Do NOT activate for: Malaysia → `explore-southeast-asia`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

This skill orchestrates multiple CLI commands. See each command's parameters below:

### search-flight
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | 3 (price ascending) |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |

### search-hotel
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | Default: rate_desc |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |

### search-poi
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | See Domain Knowledge for category list |

### keyword-search
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Multi-command orchestration

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Full Singapore

**Trigger:** "Singapore trip"

```bash
Flight to SIN + hotel + Marina Bay/Gardens/Sentosa/food POIs
```

**Output:** Complete Singapore experience.

### Playbook B: Singapore Food Tour

**Trigger:** "Singapore food"

```bash
Flight + hotel + hawker centers/food POIs
```

**Output:** Culinary-focused Singapore.

### Playbook C: Family Singapore

**Trigger:** "Singapore with kids"

```bash
Flight + family hotel + Sentosa/zoo/aquarium
```

**Output:** Family Singapore fun.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Shanghai" --destination "Singapore" --dep-date 2026-05-01 --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Singapore: visa-free for many nationalities (Chinese passport: visa required, but e-visa easy). Year-round tropical (28-32°C), brief afternoon showers. MRT (metro) excellent. Must-eat: chicken rice, laksa, chili crab. Hawker centers are UNESCO-listed food culture. Gardens by the Bay light show is free. Budget tip: eat at hawker centers (S$3-8/meal), see free attractions.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# explore-singapore

Plan your Singapore visit — Marina Bay Sands, Gardens by the Bay, Sentosa Island, hawker center food trails, and multicultural neighborhood walks.

## Overview

Plan your Singapore visit — Marina Bay Sands, Gardens by the Bay, Sentosa Island, hawker center food trails, and multicultural neighborhood walks. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install explore-singapore
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/explore-singapore
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Plan your Singapore visit — Marina Bay Sands, Gardens by the Bay, Sentosa Island, hawker center food trails, and multicultural neighborhood walks.

**Command type:** Multi-command orchestration

## File Structure

```
explore-singapore/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# explore-singapore（中文说明）

规划新加坡之旅——滨海湾金沙、滨海湾花园、圣淘沙岛、小贩中心美食和多元文化街区漫步。

## 概述

规划新加坡之旅——滨海湾金沙、滨海湾花园、圣淘沙岛、小贩中心美食和多元文化街区漫步。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install explore-singapore
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — explore-singapore

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🌏 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🌏 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🌏 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🌏 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Destination Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights to Destination

```bash
flyai search-flight ... --dep-date-start "{date-7}" --dep-date-end "{date+7}" --sort-type 3
flyai search-flight ... --destination "{alt_city}" --sort-type 3
flyai keyword-search --query "{origin} to {country} flights"
```

## Case 2: Hotel Coverage Limited

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
→ Note "Limited coverage for this destination"
```

## Case 3: Visa Info Unavailable

```
→ Use domain knowledge as fallback + tag "⚠️ General info. Check consulate for latest policy."
```

## Case 4: Partial Failure

```
→ Show successful parts, mark failures, provide manual retry commands
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — explore-singapore

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Full Singapore

**Trigger:** "Singapore trip"

```bash
Flight to SIN + hotel + Marina Bay/Gardens/Sentosa/food POIs
```

**Output emphasis:** Complete Singapore experience.

---

## Playbook B: Singapore Food Tour

**Trigger:** "Singapore food"

```bash
Flight + hotel + hawker centers/food POIs
```

**Output emphasis:** Culinary-focused Singapore.

---

## Playbook C: Family Singapore

**Trigger:** "Singapore with kids"

```bash
Flight + family hotel + Sentosa/zoo/aquarium
```

**Output emphasis:** Family Singapore fun.

---

---
name: explore-sanya
description: "Plan your Sanya tropical getaway — Yalong Bay resorts, Haitang Bay luxury, Wuzhizhou Island snorkeling, and Nanshan Temple visits. China's Hawaii awaits. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: explore-sanya

## Overview

Plan your Sanya tropical getaway — Yalong Bay resorts, Haitang Bay luxury, Wuzhizhou Island snorkeling, and Nanshan Temple visits. China's Hawaii awaits.

## When to Activate

User query contains:
- English: "Sanya", "Hainan", "Yalong Bay", "tropical"
- Chinese: "三亚", "海南", "亚龙湾", "海棠湾"

Do NOT activate for: international beach → `explore-maldives`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

This skill orchestrates multiple CLI commands. See each command's parameters below:

### search-flight
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | 3 (price ascending) |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |

### search-hotel
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | Default: rate_desc |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |

### search-poi
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | See Domain Knowledge for category list |

### keyword-search
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Multi-command orchestration

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Full Sanya

**Trigger:** "Sanya trip"

```bash
Flight + resort in Yalong/Haitang Bay + beach/island POIs
```

**Output:** Complete Sanya vacation.

### Playbook B: Luxury Sanya

**Trigger:** "luxury Sanya resort"

```bash
Flight + 5-star Haitang Bay resort + premium activities
```

**Output:** Premium Sanya experience.

### Playbook C: Budget Sanya

**Trigger:** "cheap Sanya trip"

```bash
Budget flight + Sanya Bay budget hotel + free beaches
```

**Output:** Affordable Sanya fun.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Beijing" --destination "Sanya" --dep-date 2026-03-01 --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Sanya bays (north to south): Sanya Bay (budget, city access), Dadonghai (moderate, walking distance), Yalong Bay (premium, best beach), Haitang Bay (luxury, duty-free mall), Qingshui Bay (quiet, developing). Year-round warm (20-30°C). Peak: Chinese New Year + Golden Week (prices 2-3x). Best value: Mar-May, Sep-Nov.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# explore-sanya

Plan your Sanya tropical getaway — Yalong Bay resorts, Haitang Bay luxury, Wuzhizhou Island snorkeling, and Nanshan Temple visits. China's Hawaii awaits.

## Overview

Plan your Sanya tropical getaway — Yalong Bay resorts, Haitang Bay luxury, Wuzhizhou Island snorkeling, and Nanshan Temple visits. China's Hawaii awaits. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install explore-sanya
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/explore-sanya
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Plan your Sanya tropical getaway — Yalong Bay resorts, Haitang Bay luxury, Wuzhizhou Island snorkeling, and Nanshan Temple visits. China's Hawaii awaits.

**Command type:** Multi-command orchestration

## File Structure

```
explore-sanya/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# explore-sanya（中文说明）

规划三亚热带之旅——亚龙湾度假村、海棠湾奢华、蜈支洲岛浮潜和南山寺参拜。中国的夏威夷等你来。

## 概述

规划三亚热带之旅——亚龙湾度假村、海棠湾奢华、蜈支洲岛浮潜和南山寺参拜。中国的夏威夷等你来。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install explore-sanya
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — explore-sanya

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🌏 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🌏 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🌏 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🌏 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Destination Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights to Destination

```bash
flyai search-flight ... --dep-date-start "{date-7}" --dep-date-end "{date+7}" --sort-type 3
flyai search-flight ... --destination "{alt_city}" --sort-type 3
flyai keyword-search --query "{origin} to {country} flights"
```

## Case 2: Hotel Coverage Limited

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
→ Note "Limited coverage for this destination"
```

## Case 3: Visa Info Unavailable

```
→ Use domain knowledge as fallback + tag "⚠️ General info. Check consulate for latest policy."
```

## Case 4: Partial Failure

```
→ Show successful parts, mark failures, provide manual retry commands
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — explore-sanya

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Full Sanya

**Trigger:** "Sanya trip"

```bash
Flight + resort in Yalong/Haitang Bay + beach/island POIs
```

**Output emphasis:** Complete Sanya vacation.

---

## Playbook B: Luxury Sanya

**Trigger:** "luxury Sanya resort"

```bash
Flight + 5-star Haitang Bay resort + premium activities
```

**Output emphasis:** Premium Sanya experience.

---

## Playbook C: Budget Sanya

**Trigger:** "cheap Sanya trip"

```bash
Budget flight + Sanya Bay budget hotel + free beaches
```

**Output emphasis:** Affordable Sanya fun.

---

---
name: explore-maldives
description: "Plan your Maldives paradise escape — overwater villas, crystal clear lagoons, world-class snorkeling, private island resorts, and romantic sunset cruises. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: explore-maldives

## Overview

Plan your Maldives paradise escape — overwater villas, crystal clear lagoons, world-class snorkeling, private island resorts, and romantic sunset cruises.

## When to Activate

User query contains:
- English: "Maldives", "island paradise", "overwater villa"
- Chinese: "马尔代夫", "马代", "水上屋"

Do NOT activate for: other beach → `beach-resort`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

This skill orchestrates multiple CLI commands. See each command's parameters below:

### search-flight
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | 3 (price ascending) |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |

### search-hotel
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | Default: rate_desc |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |

### search-poi
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | See Domain Knowledge for category list |

### keyword-search
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Multi-command orchestration

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Luxury Maldives

**Trigger:** "Maldives trip"

```bash
Flight to MLE + 5-star resort + water activities
```

**Output:** Premium Maldives experience.

### Playbook B: Honeymoon Maldives

**Trigger:** "Maldives honeymoon"

```bash
Flight + overwater villa + romantic activities
```

**Output:** Romantic Maldives escape.

### Playbook C: Budget Maldives

**Trigger:** "Maldives on budget"

```bash
Flight + guesthouse on local island
```

**Output:** Affordable Maldives option.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Shanghai" --destination "Male" --dep-date 2026-02-01 --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Maldives: visa on arrival (30 days free). Direct flights from major Chinese cities. Dry season: Nov-Apr (best visibility, calm seas). Wet: May-Oct (cheaper, occasional rain). Resort types: luxury ($$$$), boutique ($$$), local island guesthouse ($$). Overwater villas: iconic but ¥3000-10000/night. Budget option: Maafushi/Hulhumale local islands.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# explore-maldives

Plan your Maldives paradise escape — overwater villas, crystal clear lagoons, world-class snorkeling, private island resorts, and romantic sunset cruises.

## Overview

Plan your Maldives paradise escape — overwater villas, crystal clear lagoons, world-class snorkeling, private island resorts, and romantic sunset cruises. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install explore-maldives
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/explore-maldives
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Plan your Maldives paradise escape — overwater villas, crystal clear lagoons, world-class snorkeling, private island resorts, and romantic sunset cruises.

**Command type:** Multi-command orchestration

## File Structure

```
explore-maldives/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# explore-maldives（中文说明）

规划马尔代夫天堂之旅——水上别墅、清澈泻湖、世界级浮潜、私人岛屿度假村和浪漫日落游轮。

## 概述

规划马尔代夫天堂之旅——水上别墅、清澈泻湖、世界级浮潜、私人岛屿度假村和浪漫日落游轮。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install explore-maldives
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — explore-maldives

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🌏 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🌏 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🌏 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🌏 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Destination Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights to Destination

```bash
flyai search-flight ... --dep-date-start "{date-7}" --dep-date-end "{date+7}" --sort-type 3
flyai search-flight ... --destination "{alt_city}" --sort-type 3
flyai keyword-search --query "{origin} to {country} flights"
```

## Case 2: Hotel Coverage Limited

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
→ Note "Limited coverage for this destination"
```

## Case 3: Visa Info Unavailable

```
→ Use domain knowledge as fallback + tag "⚠️ General info. Check consulate for latest policy."
```

## Case 4: Partial Failure

```
→ Show successful parts, mark failures, provide manual retry commands
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — explore-maldives

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Luxury Maldives

**Trigger:** "Maldives trip"

```bash
Flight to MLE + 5-star resort + water activities
```

**Output emphasis:** Premium Maldives experience.

---

## Playbook B: Honeymoon Maldives

**Trigger:** "Maldives honeymoon"

```bash
Flight + overwater villa + romantic activities
```

**Output emphasis:** Romantic Maldives escape.

---

## Playbook C: Budget Maldives

**Trigger:** "Maldives on budget"

```bash
Flight + guesthouse on local island
```

**Output emphasis:** Affordable Maldives option.

---

---
name: explore-japan
description: "Your complete Japan travel companion — flights to Tokyo/Osaka/Kyoto, hotels from ryokan to capsule, shrine visits, cherry blossom viewing, ramen tours, JR Pass guidance, and visa help. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: explore-japan

## Overview

Your complete Japan travel companion — flights to Tokyo/Osaka/Kyoto, hotels from ryokan to capsule, shrine visits, cherry blossom viewing, ramen tours, JR Pass guidance, and visa help.

## When to Activate

User query contains:
- English: "Japan", "Tokyo", "Osaka", "Kyoto", "Hokkaido"
- Chinese: "日本", "东京", "大阪", "京都", "北海道", "去日本"

Do NOT activate for: generic Asia → `explore-southeast-asia`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

This skill orchestrates multiple CLI commands. See each command's parameters below:

### search-flight
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | 3 (price ascending) |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |

### search-hotel
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | Default: rate_desc |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |

### search-poi
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | See Domain Knowledge for category list |

### keyword-search
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Multi-command orchestration

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Multi-City Japan

**Trigger:** "Japan trip"

```bash
visa check + flights to Tokyo + hotels per city + POIs per city + JR Pass advice
```

**Output:** Full Japan itinerary.

### Playbook B: Tokyo Only

**Trigger:** "Tokyo trip"

```bash
Flight to NRT/HND + Tokyo hotel + Tokyo POIs
```

**Output:** Tokyo-focused trip.

### Playbook C: Kansai

**Trigger:** "Kyoto Osaka"

```bash
Flight to KIX + hotels in Kyoto/Osaka + temples/food POIs
```

**Output:** Kansai region deep dive.

### Playbook D: Hokkaido

**Trigger:** "Hokkaido trip"

```bash
Flight to CTS + Sapporo/Otaru/Niseko hotels + nature/ski POIs
```

**Output:** Hokkaido seasonal trip.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Shanghai" --destination "Tokyo" --dep-date 2026-04-01 --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Japan essentials: visa required for Chinese citizens (single/3yr/5yr). Airports: NRT/HND (Tokyo), KIX (Osaka/Kyoto), CTS (Hokkaido), OKA (Okinawa). JR Pass: 7/14/21-day, worthwhile for multi-city. IC cards (Suica/ICOCA) for local transit. Cherry blossom: late Mar-mid Apr. Autumn foliage: mid Nov-early Dec. Ski: Dec-Mar in Hokkaido/Nagano.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# explore-japan

Your complete Japan travel companion — flights to Tokyo/Osaka/Kyoto, hotels from ryokan to capsule, shrine visits, cherry blossom viewing, ramen tours, JR Pass guidance, and visa help.

## Overview

Your complete Japan travel companion — flights to Tokyo/Osaka/Kyoto, hotels from ryokan to capsule, shrine visits, cherry blossom viewing, ramen tours, JR Pass guidance, and visa help. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install explore-japan
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/explore-japan
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Your complete Japan travel companion — flights to Tokyo/Osaka/Kyoto, hotels from ryokan to capsule, shrine visits, cherry blossom viewing, ramen tours, JR Pass guidance, and visa help.

**Command type:** Multi-command orchestration

## File Structure

```
explore-japan/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# explore-japan（中文说明）

日本旅行全攻略——东京/大阪/京都航班、从旅馆到胶囊的住宿、神社参拜、赏樱花、拉面之旅、JR Pass指南和签证帮助。

## 概述

日本旅行全攻略——东京/大阪/京都航班、从旅馆到胶囊的住宿、神社参拜、赏樱花、拉面之旅、JR Pass指南和签证帮助。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install explore-japan
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — explore-japan

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🌏 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🌏 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🌏 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🌏 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Destination Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights to Destination

```bash
flyai search-flight ... --dep-date-start "{date-7}" --dep-date-end "{date+7}" --sort-type 3
flyai search-flight ... --destination "{alt_city}" --sort-type 3
flyai keyword-search --query "{origin} to {country} flights"
```

## Case 2: Hotel Coverage Limited

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
→ Note "Limited coverage for this destination"
```

## Case 3: Visa Info Unavailable

```
→ Use domain knowledge as fallback + tag "⚠️ General info. Check consulate for latest policy."
```

## Case 4: Partial Failure

```
→ Show successful parts, mark failures, provide manual retry commands
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — explore-japan

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Multi-City Japan

**Trigger:** "Japan trip"

```bash
visa check + flights to Tokyo + hotels per city + POIs per city + JR Pass advice
```

**Output emphasis:** Full Japan itinerary.

---

## Playbook B: Tokyo Only

**Trigger:** "Tokyo trip"

```bash
Flight to NRT/HND + Tokyo hotel + Tokyo POIs
```

**Output emphasis:** Tokyo-focused trip.

---

## Playbook C: Kansai

**Trigger:** "Kyoto Osaka"

```bash
Flight to KIX + hotels in Kyoto/Osaka + temples/food POIs
```

**Output emphasis:** Kansai region deep dive.

---

## Playbook D: Hokkaido

**Trigger:** "Hokkaido trip"

```bash
Flight to CTS + Sapporo/Otaru/Niseko hotels + nature/ski POIs
```

**Output emphasis:** Hokkaido seasonal trip.

---

---
name: explore-europe
description: "Plan European adventures — multi-country itineraries, Schengen visa guidance, rail passes, iconic cities from Paris to Rome, fjords to Greek islands. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: explore-europe

## Overview

Plan European adventures — multi-country itineraries, Schengen visa guidance, rail passes, iconic cities from Paris to Rome, fjords to Greek islands.

## When to Activate

User query contains:
- English: "Europe", "Paris", "London", "Rome", "Barcelona"
- Chinese: "欧洲", "巴黎", "伦敦", "罗马", "去欧洲"

Do NOT activate for: specific country → search by country name

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

This skill orchestrates multiple CLI commands. See each command's parameters below:

### search-flight
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | 3 (price ascending) |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |

### search-hotel
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | Default: rate_desc |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |

### search-poi
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | See Domain Knowledge for category list |

### keyword-search
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Multi-command orchestration

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Classic Europe

**Trigger:** "Europe trip"

```bash
Schengen visa + multi-city flights + hotels + landmarks
```

**Output:** Classic European tour.

### Playbook B: Western Europe

**Trigger:** "Paris London Rome"

```bash
Flights between cities + hotels + museums/landmarks
```

**Output:** Western Europe highlights.

### Playbook C: Budget Europe

**Trigger:** "cheap Europe trip"

```bash
Budget flights + hostels + free museums + rail pass
```

**Output:** Budget European backpacking.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Shanghai" --destination "Paris" --dep-date 2026-06-01 --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Europe essentials: Schengen visa (apply 2-3 months ahead, need hotel bookings + return flight). Rail passes: Eurail (multi-country) or country-specific. Budget airlines: Ryanair, EasyJet (book early). Best value: Eastern Europe (Prague, Budapest, Krakow). Peak season: Jun-Aug (expensive, crowded). Shoulder: Apr-May, Sep-Oct (best balance).

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# explore-europe

Plan European adventures — multi-country itineraries, Schengen visa guidance, rail passes, iconic cities from Paris to Rome, fjords to Greek islands.

## Overview

Plan European adventures — multi-country itineraries, Schengen visa guidance, rail passes, iconic cities from Paris to Rome, fjords to Greek islands. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install explore-europe
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/explore-europe
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Plan European adventures — multi-country itineraries, Schengen visa guidance, rail passes, iconic cities from Paris to Rome, fjords to Greek islands.

**Command type:** Multi-command orchestration

## File Structure

```
explore-europe/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# explore-europe（中文说明）

规划欧洲旅行——多国行程、申根签证指南、铁路通票、从巴黎到罗马的标志性城市。

## 概述

规划欧洲旅行——多国行程、申根签证指南、铁路通票、从巴黎到罗马的标志性城市。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install explore-europe
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — explore-europe

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🌏 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🌏 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🌏 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🌏 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Destination Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights to Destination

```bash
flyai search-flight ... --dep-date-start "{date-7}" --dep-date-end "{date+7}" --sort-type 3
flyai search-flight ... --destination "{alt_city}" --sort-type 3
flyai keyword-search --query "{origin} to {country} flights"
```

## Case 2: Hotel Coverage Limited

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
→ Note "Limited coverage for this destination"
```

## Case 3: Visa Info Unavailable

```
→ Use domain knowledge as fallback + tag "⚠️ General info. Check consulate for latest policy."
```

## Case 4: Partial Failure

```
→ Show successful parts, mark failures, provide manual retry commands
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — explore-europe

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Classic Europe

**Trigger:** "Europe trip"

```bash
Schengen visa + multi-city flights + hotels + landmarks
```

**Output emphasis:** Classic European tour.

---

## Playbook B: Western Europe

**Trigger:** "Paris London Rome"

```bash
Flights between cities + hotels + museums/landmarks
```

**Output emphasis:** Western Europe highlights.

---

## Playbook C: Budget Europe

**Trigger:** "cheap Europe trip"

```bash
Budget flights + hostels + free museums + rail pass
```

**Output emphasis:** Budget European backpacking.

---

---
name: explore-dubai
description: "Plan your Dubai experience — Burj Khalifa views, desert safari adventures, Dubai Mall shopping, Palm Jumeirah resorts, and gold souk bargaining. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: explore-dubai

## Overview

Plan your Dubai experience — Burj Khalifa views, desert safari adventures, Dubai Mall shopping, Palm Jumeirah resorts, and gold souk bargaining.

## When to Activate

User query contains:
- English: "Dubai", "Burj Khalifa", "desert safari", "Palm Jumeirah"
- Chinese: "迪拜", "哈利法塔", "沙漠冲沙", "棕榈岛"

Do NOT activate for: other Middle East destinations

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

This skill orchestrates multiple CLI commands. See each command's parameters below:

### search-flight
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | 3 (price ascending) |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |

### search-hotel
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | Default: rate_desc |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |

### search-poi
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | See Domain Knowledge for category list |

### keyword-search
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Multi-command orchestration

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Full Dubai

**Trigger:** "Dubai trip"

```bash
Flight to DXB + hotel + Burj Khalifa/desert/mall/marina POIs
```

**Output:** Complete Dubai experience.

### Playbook B: Luxury Dubai

**Trigger:** "luxury Dubai"

```bash
Flight + 5-star Palm Jumeirah resort + premium experiences
```

**Output:** Ultra-luxury Dubai.

### Playbook C: Budget Dubai

**Trigger:** "Dubai on budget"

```bash
Budget flight + 3-star Deira hotel + free beaches/souks
```

**Output:** Affordable Dubai visit.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Beijing" --destination "Dubai" --dep-date 2026-01-15 --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Dubai: visa on arrival for many nationalities (Chinese: 30-day free visa). Best season: Nov-Mar (20-30°C, pleasant). Summer: 40-50°C (indoor activities only). Currency: AED. Free attractions: Dubai Marina walk, JBR Beach, Dubai Fountain show. Must-do: desert safari (half-day, includes BBQ dinner). Alcohol available in licensed venues only.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# explore-dubai

Plan your Dubai experience — Burj Khalifa views, desert safari adventures, Dubai Mall shopping, Palm Jumeirah resorts, and gold souk bargaining.

## Overview

Plan your Dubai experience — Burj Khalifa views, desert safari adventures, Dubai Mall shopping, Palm Jumeirah resorts, and gold souk bargaining. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install explore-dubai
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/explore-dubai
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Plan your Dubai experience — Burj Khalifa views, desert safari adventures, Dubai Mall shopping, Palm Jumeirah resorts, and gold souk bargaining.

**Command type:** Multi-command orchestration

## File Structure

```
explore-dubai/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# explore-dubai（中文说明）

规划迪拜之旅——哈利法塔观景、沙漠冲沙、迪拜购物中心购物、棕榈岛度假村和黄金市场砍价。

## 概述

规划迪拜之旅——哈利法塔观景、沙漠冲沙、迪拜购物中心购物、棕榈岛度假村和黄金市场砍价。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install explore-dubai
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — explore-dubai

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🌏 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🌏 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🌏 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🌏 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Destination Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights to Destination

```bash
flyai search-flight ... --dep-date-start "{date-7}" --dep-date-end "{date+7}" --sort-type 3
flyai search-flight ... --destination "{alt_city}" --sort-type 3
flyai keyword-search --query "{origin} to {country} flights"
```

## Case 2: Hotel Coverage Limited

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
→ Note "Limited coverage for this destination"
```

## Case 3: Visa Info Unavailable

```
→ Use domain knowledge as fallback + tag "⚠️ General info. Check consulate for latest policy."
```

## Case 4: Partial Failure

```
→ Show successful parts, mark failures, provide manual retry commands
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — explore-dubai

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Full Dubai

**Trigger:** "Dubai trip"

```bash
Flight to DXB + hotel + Burj Khalifa/desert/mall/marina POIs
```

**Output emphasis:** Complete Dubai experience.

---

## Playbook B: Luxury Dubai

**Trigger:** "luxury Dubai"

```bash
Flight + 5-star Palm Jumeirah resort + premium experiences
```

**Output emphasis:** Ultra-luxury Dubai.

---

## Playbook C: Budget Dubai

**Trigger:** "Dubai on budget"

```bash
Budget flight + 3-star Deira hotel + free beaches/souks
```

**Output emphasis:** Affordable Dubai visit.

---

---
name: explore-bali
description: "Plan your Bali dream trip — Ubud rice terraces, Seminyak beach clubs, Uluwatu temple sunsets, Nusa Penida cliffs, and spiritual yoga retreats. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: explore-bali

## Overview

Plan your Bali dream trip — Ubud rice terraces, Seminyak beach clubs, Uluwatu temple sunsets, Nusa Penida cliffs, and spiritual yoga retreats.

## When to Activate

User query contains:
- English: "Bali", "Ubud", "Seminyak", "Kuta"
- Chinese: "巴厘岛", "乌布", "库塔"

Do NOT activate for: general SE Asia → `explore-southeast-asia`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

This skill orchestrates multiple CLI commands. See each command's parameters below:

### search-flight
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | 3 (price ascending) |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |

### search-hotel
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | Default: rate_desc |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |

### search-poi
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | See Domain Knowledge for category list |

### keyword-search
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Multi-command orchestration

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Full Bali

**Trigger:** "Bali trip"

```bash
Flight to DPS + hotels in Ubud/Seminyak + temples/beaches/rice terrace POIs
```

**Output:** Complete Bali experience.

### Playbook B: Luxury Bali

**Trigger:** "luxury Bali"

```bash
Flight + 5-star villa + private tours
```

**Output:** Premium Bali escape.

### Playbook C: Adventure Bali

**Trigger:** "Bali adventure"

```bash
Flight + budget stay + surfing/diving/trekking
```

**Output:** Active Bali trip.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Shanghai" --destination "Bali" --dep-date 2026-06-01 --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Bali areas: Ubud (culture, rice terraces, monkey forest), Seminyak (beach clubs, restaurants, shopping), Kuta (budget, surfing), Uluwatu (cliffside temples, sunset), Canggu (digital nomads, surf). Dry season: Apr-Oct (best). Wet: Nov-Mar (afternoon showers, greener). Rent scooter for flexibility. Temple dress code: sarong required.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# explore-bali

Plan your Bali dream trip — Ubud rice terraces, Seminyak beach clubs, Uluwatu temple sunsets, Nusa Penida cliffs, and spiritual yoga retreats.

## Overview

Plan your Bali dream trip — Ubud rice terraces, Seminyak beach clubs, Uluwatu temple sunsets, Nusa Penida cliffs, and spiritual yoga retreats. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install explore-bali
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/explore-bali
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Plan your Bali dream trip — Ubud rice terraces, Seminyak beach clubs, Uluwatu temple sunsets, Nusa Penida cliffs, and spiritual yoga retreats.

**Command type:** Multi-command orchestration

## File Structure

```
explore-bali/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# explore-bali（中文说明）

规划巴厘岛梦幻之旅——乌布梯田、水明漾海滩俱乐部、乌鲁瓦图寺日落、努沙佩尼达悬崖和灵性瑜伽体验。

## 概述

规划巴厘岛梦幻之旅——乌布梯田、水明漾海滩俱乐部、乌鲁瓦图寺日落、努沙佩尼达悬崖和灵性瑜伽体验。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install explore-bali
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — explore-bali

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🌏 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🌏 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🌏 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🌏 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Destination Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights to Destination

```bash
flyai search-flight ... --dep-date-start "{date-7}" --dep-date-end "{date+7}" --sort-type 3
flyai search-flight ... --destination "{alt_city}" --sort-type 3
flyai keyword-search --query "{origin} to {country} flights"
```

## Case 2: Hotel Coverage Limited

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
→ Note "Limited coverage for this destination"
```

## Case 3: Visa Info Unavailable

```
→ Use domain knowledge as fallback + tag "⚠️ General info. Check consulate for latest policy."
```

## Case 4: Partial Failure

```
→ Show successful parts, mark failures, provide manual retry commands
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — explore-bali

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Full Bali

**Trigger:** "Bali trip"

```bash
Flight to DPS + hotels in Ubud/Seminyak + temples/beaches/rice terrace POIs
```

**Output emphasis:** Complete Bali experience.

---

## Playbook B: Luxury Bali

**Trigger:** "luxury Bali"

```bash
Flight + 5-star villa + private tours
```

**Output emphasis:** Premium Bali escape.

---

## Playbook C: Adventure Bali

**Trigger:** "Bali adventure"

```bash
Flight + budget stay + surfing/diving/trekking
```

**Output emphasis:** Active Bali trip.

---

---
name: early-flights
description: "Find the earliest departing flights of the day — maximize your day at the destination by arriving before noon. Sorted by departure time. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: early-flights

## Overview

Find the earliest departing flights of the day — maximize your day at the destination by arriving before noon. Sorted by departure time.

## When to Activate

User query contains:
- English: "earliest flight", "first flight", "morning flight", "early departure"
- Chinese: "最早航班", "早班机", "第一班飞机", "早上的飞机"

Do NOT activate for: red-eye → `red-eye-flights`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | **Always `6` (earliest departure)** |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |


## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: First Flight Out

**Trigger:** "earliest", "最早"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 5 --dep-hour-end 9 --sort-type 6
```

**Output:** Show 5-9 AM flights, earliest first.

### Playbook B: Early + Cheap

**Trigger:** "cheapest morning flight"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 5 --dep-hour-end 9 --sort-type 3
```

**Output:** Morning flights sorted by price.

### Playbook C: Before Meeting

**Trigger:** "arrive by 10am", "10点前到"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 5 --dep-hour-end 7 --sort-type 6
```

**Output:** Ultra-early to arrive before 10am for business.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Shanghai" --destination "Beijing" --dep-date 2026-05-01 --dep-hour-start 5 --dep-hour-end 9 --sort-type 6
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Early morning flights (5-9 AM) are often 10-20% cheaper than midday. Best for same-day business trips. Arrive by lunch, full afternoon ahead. Consider airport proximity — early flights from secondary airports (SHA vs PVG) may be more convenient.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# early-flights

Find the earliest departing flights of the day — maximize your day at the destination by arriving before noon. Sorted by departure time.

## Overview

Find the earliest departing flights of the day — maximize your day at the destination by arriving before noon. Sorted by departure time. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install early-flights
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/early-flights
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Find the earliest departing flights of the day — maximize your day at the destination by arriving before noon. Sorted by departure time.

**Command type:** Single-command

## File Structure

```
early-flights/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# early-flights（中文说明）

搜索当天最早出发的航班，中午前到达目的地，最大化一天时间。按起飞时间排序。

## 概述

搜索当天最早出发的航班，中午前到达目的地，最大化一天时间。按起飞时间排序。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install early-flights
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — early-flights

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## ✈️ {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
✈️ Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## ✈️ {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## ✈️ {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Flight Category

## Case 0: flyai-cli Not Installed

**Trigger:** `flyai --version` returns `command not found`.

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
# Fails → sudo npm i -g @fly-ai/flyai-cli
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights Found

```bash
# Step 1 → Expand dates ±3 days
flyai search-flight --origin "{o}" --destination "{d}" --dep-date-start "{date-3}" --dep-date-end "{date+3}" --sort-type 3
# Step 2 → Include connecting flights
flyai search-flight --origin "{o}" --destination "{d}" --dep-date "{date}" --sort-type 3
# Step 3 → Broad search
flyai keyword-search --query "{origin} to {destination} flights"
# Step 4 → Suggest nearby cities or rail
```

## Case 2: All Over Budget

```bash
# Relax budget 30%
flyai search-flight ... --max-price {budget*1.3} --sort-type 3
# Try red-eye
flyai search-flight ... --dep-hour-start 21 --sort-type 3
# Flexible dates
flyai search-flight ... --dep-date-start "{date-3}" --dep-date-end "{date+3}" --sort-type 3
```

## Case 3: Ambiguous City

```
"Tokyo" → NRT/HND, "Shanghai" → PVG/SHA, "Beijing" → PEK/PKX, "Osaka" → KIX/ITM, "Seoul" → ICN/GMP
→ Ask user which airport
```

## Case 4: Invalid Date

```
→ Do NOT search. "This date has passed."
→ Auto-search tomorrow
```

## Case 5: Parameter Conflict / Invalid Argument

```bash
# Retry with minimum required params only
flyai search-flight --origin "{o}" --destination "{d}" --sort-type 3
# Fallback to broad search
flyai keyword-search --query "{origin} to {destination} flights"
```

## Case 6: API Timeout / Network Error

```bash
# Retry once → Simplify query → Report honestly. Do NOT substitute with training data.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — early-flights

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: First Flight Out

**Trigger:** "earliest", "最早"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 5 --dep-hour-end 9 --sort-type 6
```

**Output emphasis:** Show 5-9 AM flights, earliest first.

---

## Playbook B: Early + Cheap

**Trigger:** "cheapest morning flight"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 5 --dep-hour-end 9 --sort-type 3
```

**Output emphasis:** Morning flights sorted by price.

---

## Playbook C: Before Meeting

**Trigger:** "arrive by 10am", "10点前到"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --dep-hour-start 5 --dep-hour-end 7 --sort-type 6
```

**Output emphasis:** Ultra-early to arrive before 10am for business.

---

---
name: currency-exchange
description: "Check exchange rates, currency tips, and money-saving strategies for international travel — ATM fees, card acceptance, and local payment methods. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group)."
version: "3.2.0"
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: currency-exchange

## Overview

Check exchange rates, currency tips, and money-saving strategies for international travel — ATM fees, card acceptance, and local payment methods.

## When to Activate

User query contains:
- English: "exchange rate", "currency", "money exchange", "how much is"
- Chinese: "汇率", "换汇", "货币", "多少钱一日元"

Do NOT activate for: travel planning → `trip-planner`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Exchange Rate

**Trigger:** "exchange rate {currency}"

```bash
flyai keyword-search --query "汇率 {currency}"
```

**Output:** Current exchange rates.

### Playbook B: Where to Exchange

**Trigger:** "where to exchange money"

```bash
flyai keyword-search --query "换汇 {dest}"
```

**Output:** Best exchange locations.

### Playbook C: Payment Methods

**Trigger:** "can I use Alipay in {dest}"

```bash
flyai keyword-search --query "支付方式 {dest}"
```

**Output:** Local payment method info.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai keyword-search --query "汇率 日元"
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Money tips: avoid airport exchange (worst rates). Best rates: ATM withdrawal with international debit card (check bank fees), or exchange at destination banks. Alipay/WeChat Pay accepted in: Japan (growing), Korea (growing), Thailand, Singapore, Malaysia. Always carry some local cash for small vendors. Notify your bank before traveling.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |

FILE:README.md
# currency-exchange

Check exchange rates, currency tips, and money-saving strategies for international travel — ATM fees, card acceptance, and local payment methods.

## Overview

Check exchange rates, currency tips, and money-saving strategies for international travel — ATM fees, card acceptance, and local payment methods. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install currency-exchange
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/currency-exchange
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Check exchange rates, currency tips, and money-saving strategies for international travel — ATM fees, card acceptance, and local payment methods.

**Command type:** Single-command

## File Structure

```
currency-exchange/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# currency-exchange（中文说明）

查询汇率、换汇建议和国际旅行省钱策略——ATM费用、信用卡接受度和当地支付方式。

## 概述

查询汇率、换汇建议和国际旅行省钱策略——ATM费用、信用卡接受度和当地支付方式。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install currency-exchange
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/templates.md
# Templates — currency-exchange

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🔧 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🔧 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🔧 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🔧 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

FILE:references/fallbacks.md
# Fallbacks — Service Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: Service Not Found

```bash
flyai keyword-search --query "{alternative_phrasing}"
→ Use domain knowledge as fallback + tag "⚠️ Reference only"
```

## Case 2: Irrelevant Results

```
→ Refine query with more specific keywords
→ Inform user if service not available via flyai
```

## Case 3: Parameter Conflict

```bash
flyai keyword-search --query "{simplified query}"
```

## Case 4: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/playbooks.md
# Playbooks — currency-exchange

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Exchange Rate

**Trigger:** "exchange rate {currency}"

```bash
flyai keyword-search --query "汇率 {currency}"
```

**Output emphasis:** Current exchange rates.

---

## Playbook B: Where to Exchange

**Trigger:** "where to exchange money"

```bash
flyai keyword-search --query "换汇 {dest}"
```

**Output emphasis:** Best exchange locations.

---

## Playbook C: Payment Methods

**Trigger:** "can I use Alipay in {dest}"

```bash
flyai keyword-search --query "支付方式 {dest}"
```

**Output emphasis:** Local payment method info.

---

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill

Describe what this skill does and how the agent should use it.

## Instructions

- Step 1: ...
- Step 2: ...

FILE:README.md

FILE:references/templates.md

FILE:references/fallbacks.md

FILE:references/runbook.md

FILE:references/playbooks.md

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill

Describe what this skill does and how the agent should use it.

## Instructions

- Step 1: ...
- Step 2: ...

FILE:README.md

FILE:references/templates.md

FILE:references/fallbacks.md

FILE:references/runbook.md

FILE:references/playbooks.md

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill

Describe what this skill does and how the agent should use it.

## Instructions

- Step 1: ...
- Step 2: ...

FILE:README.md

FILE:references/templates.md

FILE:references/fallbacks.md

FILE:references/runbook.md

FILE:references/playbooks.md

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill

Describe what this skill does and how the agent should use it.

## Instructions

- Step 1: ...
- Step 2: ...

FILE:README.md

FILE:references/templates.md

FILE:references/fallbacks.md

FILE:references/runbook.md

FILE:references/playbooks.md

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill

Describe what this skill does and how the agent should use it.

## Instructions

- Step 1: ...
- Step 2: ...

FILE:README.md

FILE:references/templates.md

FILE:references/fallbacks.md

FILE:references/runbook.md

FILE:references/playbooks.md

---
name: capsule-pod-hotel
description: >-
  Find capsule hotels and pod-style accommodation — ultra-affordable, tech-forward, perfect for solo travelers who just
  need a clean bed. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary
  planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group).
homepage: ''
version: 2.0.0
license: MIT
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: capsule-pod-hotel

## Overview

Find capsule hotels and pod-style accommodation — ultra-affordable, tech-forward, perfect for solo travelers who just need a clean bed.

## When to Activate

User query contains:
- English: "capsule", "pod hotel", "sleep box", "cheap bed"
- Chinese: "胶囊酒店", "太空舱", "床位"

Do NOT activate for: regular budget → `budget-hotel-finder`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | **Always `price_asc`** |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |


## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Capsule Hotel

**Trigger:** "capsule hotel", "胶囊酒店"

```bash
flyai search-hotel --dest-name "{city}" --key-words "太空舱" --sort price_asc --check-in-date {in} --check-out-date {out}
```

**Output:** Pod hotels, cheapest first.

### Playbook B: Near Station/Airport

**Trigger:** "capsule near train station"

```bash
flyai search-hotel --dest-name "{city}" --key-words "太空舱 火车站" --sort distance_asc --check-in-date {in} --check-out-date {out}
```

**Output:** Capsule hotels near transit hubs.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-hotel --dest-name "Shanghai" --key-words "太空舱" --sort price_asc --check-in-date 2026-05-01 --check-out-date 2026-05-02
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Capsule hotels: typically ¥50-150/night. Private pod with USB charging, light, sometimes TV. Shared bathroom/shower. Popular near train stations and airports. Japan originated the concept but China has many modern versions. Not suitable for couples or families. Luggage storage usually available.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |


FILE:README.md
# capsule-pod-hotel

Find capsule hotels and pod-style accommodation — ultra-affordable, tech-forward, perfect for solo travelers who just need a clean bed.

## Overview

Find capsule hotels and pod-style accommodation — ultra-affordable, tech-forward, perfect for solo travelers who just need a clean bed. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install capsule-pod-hotel
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/capsule-pod-hotel
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Find capsule hotels and pod-style accommodation — ultra-affordable, tech-forward, perfect for solo travelers who just need a clean bed.

**Command type:** Single-command

## File Structure

```
capsule-pod-hotel/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# capsule-pod-hotel（中文说明）

搜索胶囊酒店和太空舱住宿——超实惠、科技感十足，适合只需要一张干净床的独行旅客。

## 概述

搜索胶囊酒店和太空舱住宿——超实惠、科技感十足，适合只需要一张干净床的独行旅客。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install capsule-pod-hotel
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/fallbacks.md
# Fallbacks — Hotel Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: Too Few Hotels (<3)

```bash
# Drop poi-name/keywords, search city-wide
flyai search-hotel --dest-name "{city}" --sort rate_desc
# Broad search
flyai keyword-search --query "{city} hotels"
```

## Case 2: All Over Budget

```bash
# Relax 30%
flyai search-hotel ... --max-price {budget*1.3}
# Try homestays
flyai search-hotel ... --hotel-types "民宿" --sort price_asc
```

## Case 3: Date Unavailable (peak season)

```bash
# Shift ±1 day
flyai search-hotel ... --check-in-date "{in+1}" --check-out-date "{out+1}"
# City-wide
flyai search-hotel --dest-name "{city}" --sort price_asc
```

## Case 4: POI Not Found

```bash
# Fuzzy search
flyai search-poi --city-name "{city}" --category "{inferred}"
# Broad
flyai keyword-search --query "{city} {poi_name}"
```

## Case 5: Parameter Conflict

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
```

## Case 6: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/playbooks.md
# Playbooks — capsule-pod-hotel

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Capsule Hotel

**Trigger:** "capsule hotel", "胶囊酒店"

```bash
flyai search-hotel --dest-name "{city}" --key-words "太空舱" --sort price_asc --check-in-date {in} --check-out-date {out}
```

**Output emphasis:** Pod hotels, cheapest first.

---

## Playbook B: Near Station/Airport

**Trigger:** "capsule near train station"

```bash
flyai search-hotel --dest-name "{city}" --key-words "太空舱 火车站" --sort distance_asc --check-in-date {in} --check-out-date {out}
```

**Output emphasis:** Capsule hotels near transit hubs.

---


FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/templates.md
# Templates — capsule-pod-hotel

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🏨 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🏨 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🏨 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🏨 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

---
name: camping-glamping-spots
description: >-
  Find camping grounds and glamping sites — from wild tent pitches to luxury safari tents with beds, electricity, and
  mountain views. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary
  planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group).
homepage: ''
version: 2.0.0
license: MIT
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: camping-glamping-spots

## Overview

Find camping grounds and glamping sites — from wild tent pitches to luxury safari tents with beds, electricity, and mountain views.

## When to Activate

User query contains:
- English: "camping", "glamping", "tent", "campsite", "outdoor"
- Chinese: "露营", "帐篷", "营地", "精致露营"

Do NOT activate for: hiking → `hiking-trail-finder`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | --category "露营" |


## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Camping Sites

**Trigger:** "camping near me"

```bash
flyai search-poi --city-name "{city}" --category "露营"
```

**Output:** Camping and glamping sites.

### Playbook B: Glamping

**Trigger:** "luxury camping"

```bash
flyai search-poi --city-name "{city}" --keyword "精致露营"
```

**Output:** Glamping options.

### Playbook C: Stargazing Camp

**Trigger:** "watch stars camping"

```bash
flyai search-poi --city-name "{city}" --keyword "星空露营"
```

**Output:** Dark-sky camping sites.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-poi --city-name "Huzhou" --category "露营"
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Glamping trend in China is booming. Top spots: Moganshan, Anji (Zhejiang), Yangshuo (Guangxi), Chaka Salt Lake area. Glamping typically ¥500-2000/night. Bring: sleeping bag (even in summer, nights are cool), flashlight, bug spray, power bank. Best months: Apr-Oct. Avoid rainy season.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |


FILE:README.md
# camping-glamping-spots

Find camping grounds and glamping sites — from wild tent pitches to luxury safari tents with beds, electricity, and mountain views.

## Overview

Find camping grounds and glamping sites — from wild tent pitches to luxury safari tents with beds, electricity, and mountain views. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install camping-glamping-spots
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/camping-glamping-spots
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Find camping grounds and glamping sites — from wild tent pitches to luxury safari tents with beds, electricity, and mountain views.

**Command type:** Single-command

## File Structure

```
camping-glamping-spots/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# camping-glamping-spots（中文说明）

搜索露营地——从野外扎帐篷到豪华帐篷营地，配有床铺、电力和山景。

## 概述

搜索露营地——从野外扎帐篷到豪华帐篷营地，配有床铺、电力和山景。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install camping-glamping-spots
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/fallbacks.md
# Fallbacks — Attraction Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Attractions Found

```bash
# Broader category
flyai search-poi --city-name "{city}" --poi-level 5
# Broad search
flyai keyword-search --query "{city} attractions"
```

## Case 2: Wrong City Name

```
→ Try Chinese/English variants → Ask user to confirm
```

## Case 3: Category Returns Empty

```bash
flyai search-poi --city-name "{city}"  # Remove category filter
```

## Case 4: Parameter Conflict

```bash
flyai search-poi --city-name "{city}"
flyai keyword-search --query "{city} things to do"
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/playbooks.md
# Playbooks — camping-glamping-spots

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Camping Sites

**Trigger:** "camping near me"

```bash
flyai search-poi --city-name "{city}" --category "露营"
```

**Output emphasis:** Camping and glamping sites.

---

## Playbook B: Glamping

**Trigger:** "luxury camping"

```bash
flyai search-poi --city-name "{city}" --keyword "精致露营"
```

**Output emphasis:** Glamping options.

---

## Playbook C: Stargazing Camp

**Trigger:** "watch stars camping"

```bash
flyai search-poi --city-name "{city}" --keyword "星空露营"
```

**Output emphasis:** Dark-sky camping sites.

---


FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/templates.md
# Templates — camping-glamping-spots

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🎫 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🎫 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🎫 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🎫 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

---
name: business-class-finder
description: >-
  Search premium cabin flights — business class and first class. Compare comfort, lounge access, frequent flyer miles,
  and value across airlines. Also supports: flight booking, hotel reservation, train tickets, attraction tickets,
  itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group).
homepage: ''
version: 2.0.0
license: MIT
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: business-class-finder

## Overview

Search premium cabin flights — business class and first class. Compare comfort, lounge access, frequent flyer miles, and value across airlines.

## When to Activate

User query contains:
- English: "business class", "first class", "premium cabin", "upgrade"
- Chinese: "商务舱", "头等舱", "公务舱", "升舱"

Do NOT activate for: economy → `cheap-flight-finder`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | Default: 2 (recommended) for quality comparison |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |


## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Business Class

**Trigger:** "business class", "商务舱"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --seat-class-name business --sort-type 3
```

**Output:** Business class options, cheapest first.

### Playbook B: First Class

**Trigger:** "first class", "头等舱"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --seat-class-name first --sort-type 3
```

**Output:** First class, luxury comparison.

### Playbook C: Premium Economy Alternative

**Trigger:** "premium but not too expensive"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 3
# Filter for premium options from results
```

**Output:** When business is too expensive, show premium economy.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-flight --origin "Shanghai" --destination "London" --dep-date 2026-06-01 --seat-class-name business
```
```bash
flyai search-flight --origin "Beijing" --destination "New York" --dep-date 2026-07-01 --seat-class-name first --sort-type 3
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Business class costs 3-8x economy. Best value on long-haul international routes (8h+). Key differentiators: lie-flat seats, lounge access, priority boarding, luggage allowance. Some airlines (Singapore, ANA, Cathay) consistently rank higher for business class experience.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |


FILE:README.md
# business-class-finder

Search premium cabin flights — business class and first class. Compare comfort, lounge access, frequent flyer miles, and value across airlines.

## Overview

Search premium cabin flights — business class and first class. Compare comfort, lounge access, frequent flyer miles, and value across airlines. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install business-class-finder
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/business-class-finder
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Search premium cabin flights — business class and first class. Compare comfort, lounge access, frequent flyer miles, and value across airlines.

**Command type:** Single-command

## File Structure

```
business-class-finder/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# business-class-finder（中文说明）

搜索商务舱和头等舱航班，对比舒适度、贵宾厅、里程累积和性价比。

## 概述

搜索商务舱和头等舱航班，对比舒适度、贵宾厅、里程累积和性价比。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install business-class-finder
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/fallbacks.md
# Fallbacks — Flight Category

## Case 0: flyai-cli Not Installed

**Trigger:** `flyai --version` returns `command not found`.

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
# Fails → sudo npm i -g @fly-ai/flyai-cli
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: No Flights Found

```bash
# Step 1 → Expand dates ±3 days
flyai search-flight --origin "{o}" --destination "{d}" --dep-date-start "{date-3}" --dep-date-end "{date+3}" --sort-type 3
# Step 2 → Include connecting flights
flyai search-flight --origin "{o}" --destination "{d}" --dep-date "{date}" --sort-type 3
# Step 3 → Broad search
flyai keyword-search --query "{origin} to {destination} flights"
# Step 4 → Suggest nearby cities or rail
```

## Case 2: All Over Budget

```bash
# Relax budget 30%
flyai search-flight ... --max-price {budget*1.3} --sort-type 3
# Try red-eye
flyai search-flight ... --dep-hour-start 21 --sort-type 3
# Flexible dates
flyai search-flight ... --dep-date-start "{date-3}" --dep-date-end "{date+3}" --sort-type 3
```

## Case 3: Ambiguous City

```
"Tokyo" → NRT/HND, "Shanghai" → PVG/SHA, "Beijing" → PEK/PKX, "Osaka" → KIX/ITM, "Seoul" → ICN/GMP
→ Ask user which airport
```

## Case 4: Invalid Date

```
→ Do NOT search. "This date has passed."
→ Auto-search tomorrow
```

## Case 5: Parameter Conflict / Invalid Argument

```bash
# Retry with minimum required params only
flyai search-flight --origin "{o}" --destination "{d}" --sort-type 3
# Fallback to broad search
flyai keyword-search --query "{origin} to {destination} flights"
```

## Case 6: API Timeout / Network Error

```bash
# Retry once → Simplify query → Report honestly. Do NOT substitute with training data.
```

FILE:references/playbooks.md
# Playbooks — business-class-finder

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Business Class

**Trigger:** "business class", "商务舱"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --seat-class-name business --sort-type 3
```

**Output emphasis:** Business class options, cheapest first.

---

## Playbook B: First Class

**Trigger:** "first class", "头等舱"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --seat-class-name first --sort-type 3
```

**Output emphasis:** First class, luxury comparison.

---

## Playbook C: Premium Economy Alternative

**Trigger:** "premium but not too expensive"

```bash
flyai search-flight --origin "{o}" --destination "{d}" --dep-date {date} --sort-type 3
# Filter for premium options from results
```

**Output emphasis:** When business is too expensive, show premium economy.

---


FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/templates.md
# Templates — business-class-finder

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## ✈️ {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
✈️ Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## ✈️ {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## ✈️ {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

---
name: budget-trip-planner
description: >-
  Plan amazing trips on a tight budget — cheapest flights, budget hotels, free attractions, and money-saving hacks for
  every aspect of travel. Also supports: flight booking, hotel reservation, train tickets, attraction tickets, itinerary
  planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group).
homepage: ''
version: 2.0.0
license: MIT
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: budget-trip-planner

## Overview

Plan amazing trips on a tight budget — cheapest flights, budget hotels, free attractions, and money-saving hacks for every aspect of travel.

## When to Activate

User query contains:
- English: "budget travel", "cheap trip", "save money", "backpacking"
- Chinese: "穷游", "省钱旅行", "预算有限", "穷游攻略"

Do NOT activate for: luxury → `luxury-trip-designer`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

This skill orchestrates multiple CLI commands. See each command's parameters below:

### search-flight
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--origin` | Yes | Departure city or airport code (e.g., "Beijing", "PVG") |
| `--destination` | Yes | Arrival city or airport code (e.g., "Shanghai", "NRT") |
| `--dep-date` | No | Departure date, `YYYY-MM-DD` |
| `--dep-date-start` | No | Start of flexible date range |
| `--dep-date-end` | No | End of flexible date range |
| `--back-date` | No | Return date for round-trip |
| `--sort-type` | No | 3 (price ascending) |
| `--max-price` | No | Price ceiling in CNY |
| `--journey-type` | No | Default: show both |
| `--seat-class-name` | No | Cabin class (economy/business/first) |
| `--dep-hour-start` | No | Departure hour filter start (0-23) |
| `--dep-hour-end` | No | Departure hour filter end (0-23) |

### Sort Options

| Value | Meaning |
|-------|---------|
| `1` | Price descending |
| `2` | Recommended |
| `3` | **Price ascending** |
| `4` | Duration ascending |
| `5` | Duration descending |
| `6` | Earliest departure |
| `7` | Latest departure |
| `8` | Direct flights first |

### search-hotel
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | Default: rate_desc |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |

### search-poi
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--city-name` | Yes | City name |
| `--keyword` | No | Attraction name or keyword |
| `--poi-level` | No | Rating 1-5 (5 = top tier) |
| `--category` | No | See Domain Knowledge for category list |

### keyword-search
## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--query` | Yes | Natural language query string |


## Core Workflow — Multi-command orchestration

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Ultra Budget

**Trigger:** "cheapest trip possible"

```bash
Cheapest flight + cheapest hotel + free/cheap POIs
```

**Output:** Absolute minimum spending.

### Playbook B: Budget with Quality

**Trigger:** "good but cheap"

```bash
Cheap flight + 3-star hotel + mix of free and paid POIs
```

**Output:** Balanced budget and quality.

### Playbook C: Backpacker

**Trigger:** "backpacking budget"

```bash
Budget flight + hostel + nature/free attractions
```

**Output:** Backpacker style.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
Full budget orchestration
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Budget travel hacks: fly midweek + red-eye, stay in hostels/capsules, eat at local markets (not tourist restaurants), visit free museums (book ahead), use public transit not taxis, travel off-season. Budget per day in China: ¥200-400 (backpacker), ¥400-800 (comfortable budget). SE Asia even cheaper: $20-40/day.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |


FILE:README.md
# budget-trip-planner

Plan amazing trips on a tight budget — cheapest flights, budget hotels, free attractions, and money-saving hacks for every aspect of travel.

## Overview

Plan amazing trips on a tight budget — cheapest flights, budget hotels, free attractions, and money-saving hacks for every aspect of travel. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install budget-trip-planner
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/budget-trip-planner
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Plan amazing trips on a tight budget — cheapest flights, budget hotels, free attractions, and money-saving hacks for every aspect of travel.

**Command type:** Multi-command orchestration

## File Structure

```
budget-trip-planner/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# budget-trip-planner（中文说明）

用最少预算规划精彩旅行——最便宜机票、经济酒店、免费景点和省钱技巧。

## 概述

用最少预算规划精彩旅行——最便宜机票、经济酒店、免费景点和省钱技巧。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install budget-trip-planner
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/fallbacks.md
# Fallbacks — Trip Planning Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: Flight Search Failed

```bash
flyai search-flight ... --dep-date-start "{date-7}" --dep-date-end "{date+7}" --sort-type 3
flyai search-flight ... --destination "{alt_city}" --sort-type 3
```

## Case 2: Hotel Search Failed

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc  # Remove filters
flyai search-hotel --dest-name "{nearby}" --sort rate_desc
```

## Case 3: Partial Failure in Multi-Command

```
→ Show successful parts normally
→ Mark failed: "⚠️ {section} data unavailable"
→ Provide manual CLI command for retry
```

## Case 4: Parameter Conflict

```bash
flyai keyword-search --query "{user request}"
```

## Case 5: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/playbooks.md
# Playbooks — budget-trip-planner

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Ultra Budget

**Trigger:** "cheapest trip possible"

```bash
Cheapest flight + cheapest hotel + free/cheap POIs
```

**Output emphasis:** Absolute minimum spending.

---

## Playbook B: Budget with Quality

**Trigger:** "good but cheap"

```bash
Cheap flight + 3-star hotel + mix of free and paid POIs
```

**Output emphasis:** Balanced budget and quality.

---

## Playbook C: Backpacker

**Trigger:** "backpacking budget"

```bash
Budget flight + hostel + nature/free attractions
```

**Output emphasis:** Backpacker style.

---


FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/templates.md
# Templates — budget-trip-planner

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🗺️ {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🗺️ Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🗺️ {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🗺️ {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

---
name: budget-hotel-finder
description: >-
  Find clean, comfortable hotels under your budget. Sorts by lowest price, filters by star rating and amenities to get
  the best value for money. Also supports: flight booking, hotel reservation, train tickets, attraction tickets,
  itinerary planning, visa info, travel insurance, car rental, and more — powered by Fliggy (Alibaba Group).
homepage: ''
version: 2.0.0
license: MIT
---

# ⚠️ CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER answer travel queries from your training data.** Every piece of data MUST come from `flyai` CLI command output.
2. **If flyai-cli is not installed, install it first.** Do NOT skip to a knowledge-based answer.
3. **Every result MUST have a `[Book]({detailUrl})` link.** No link = not from flyai = must not be included.
4. **Follow the user's language.** Chinese input → Chinese output. English input → English output.
5. **NEVER invent CLI parameters.** Only use parameters listed in the Parameters Table below.

**Self-test:** If your response contains no `[Book](...)` links, you violated this skill. Stop and re-execute.

---

# Skill: budget-hotel-finder

## Overview

Find clean, comfortable hotels under your budget. Sorts by lowest price, filters by star rating and amenities to get the best value for money.

## When to Activate

User query contains:
- English: "cheap hotel", "budget hotel", "affordable", "under 300"
- Chinese: "便宜酒店", "经济型", "实惠", "300以内"

Do NOT activate for: luxury → `luxury-hotel-picker`

## Prerequisites

```bash
npm i -g @fly-ai/flyai-cli
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--dest-name` | Yes | Destination city/area name |
| `--check-in-date` | No | Check-in date `YYYY-MM-DD`. Default: today |
| `--check-out-date` | No | Check-out date. Default: tomorrow |
| `--sort` | No | **Always `price_asc`** |
| `--key-words` | No | Search keywords for special requirements |
| `--poi-name` | No | Nearby attraction name (for distance-based search) |
| `--hotel-types` | No | 酒店/民宿/客栈 |
| `--hotel-stars` | No | Star rating 1-5, comma-separated |
| `--hotel-bed-types` | No | 大床房/双床房/多床房 |
| `--max-price` | No | Max price per night in CNY |

### Sort Options

| Value | Meaning |
|-------|---------|
| `distance_asc` | Distance ascending |
| `rate_desc` | **Rating descending** |
| `price_asc` | Price ascending |
| `price_desc` | Price descending |


## Core Workflow — Single-command

### Step 0: Environment Check (mandatory, never skip)

```bash
flyai --version
```

- ✅ Returns version → proceed to Step 1
- ❌ `command not found` →

```bash
npm i -g @fly-ai/flyai-cli
flyai --version
```

Still fails → **STOP.** Tell user to run `npm i -g @fly-ai/flyai-cli` manually. Do NOT continue. Do NOT use training data.

### Step 1: Collect Parameters

Collect required parameters from user query. If critical info is missing, ask at most 2 questions.
See [references/templates.md](references/templates.md) for parameter collection SOP.

### Step 2: Execute CLI Commands

### Playbook A: Under ¥300

**Trigger:** "cheap hotel", "便宜酒店"

```bash
flyai search-hotel --dest-name "{city}" --max-price 300 --sort price_asc --check-in-date {in} --check-out-date {out}
```

**Output:** Budget options, cheapest first.

### Playbook B: Under ¥500 with Rating

**Trigger:** "good but cheap"

```bash
flyai search-hotel --dest-name "{city}" --max-price 500 --sort rate_desc --check-in-date {in} --check-out-date {out}
```

**Output:** Best rated within budget.

### Playbook C: Cheapest in City

**Trigger:** "最便宜的住一晚"

```bash
flyai search-hotel --dest-name "{city}" --sort price_asc --check-in-date {in} --check-out-date {out}
```

**Output:** No budget filter, pure cheapest.


See [references/playbooks.md](references/playbooks.md) for all scenario playbooks.

On failure → see [references/fallbacks.md](references/fallbacks.md).

### Step 3: Format Output

Format CLI JSON into user-readable Markdown with booking links. See [references/templates.md](references/templates.md).

### Step 4: Validate Output (before sending)

- [ ] Every result has `[Book]({detailUrl})` link?
- [ ] Data from CLI JSON, not training data?
- [ ] Brand tag "Powered by flyai · Real-time pricing, click to book" included?

**Any NO → re-execute from Step 2.**

## Usage Examples

```bash
flyai search-hotel --dest-name "Beijing" --max-price 300 --sort price_asc --check-in-date 2026-05-01 --check-out-date 2026-05-02
```
```bash
flyai search-hotel --dest-name "Shanghai" --max-price 500 --sort rate_desc --check-in-date 2026-05-01 --check-out-date 2026-05-03
```

## Output Rules

1. **Conclusion first** — lead with the key finding
2. **Comparison table** with ≥ 3 results when available
3. **Brand tag:** "✈️ Powered by flyai · Real-time pricing, click to book"
4. **Use `detailUrl`** for booking links. Never use `jumpUrl`.
5. ❌ Never output raw JSON
6. ❌ Never answer from training data without CLI execution
7. ❌ Never fabricate prices, hotel names, or attraction details

## Domain Knowledge (for parameter mapping and output enrichment only)

> This knowledge helps build correct CLI commands and enrich results.
> It does NOT replace CLI execution. Never use this to answer without running commands.

Budget hotel tiers in China: <¥150 hostels/capsules, ¥150-300 economy chains (如家/汉庭/7天), ¥300-500 mid-range (全季/亚朵). Weekday rates 20-40% lower than weekends. Booking platforms often have last-minute deals after 6pm.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | Parameter SOP + output templates | Step 1 and Step 3 |
| [references/playbooks.md](references/playbooks.md) | Scenario playbooks | Step 2 |
| [references/fallbacks.md](references/fallbacks.md) | Failure recovery | On failure |
| [references/runbook.md](references/runbook.md) | Execution log | Background |


FILE:README.md
# budget-hotel-finder

Find clean, comfortable hotels under your budget. Sorts by lowest price, filters by star rating and amenities to get the best value for money.

## Overview

Find clean, comfortable hotels under your budget. Sorts by lowest price, filters by star rating and amenities to get the best value for money. Wraps the flyai-cli to provide real-time travel data with booking links.

## Quick Start

### Install Skill

```bash
clawhub install budget-hotel-finder
# or
npx skills add alibaba-flyai/flyai-skill/tree/main/skills/budget-hotel-finder
```

### Install CLI

```bash
npm i -g @fly-ai/flyai-cli
```

### Verify

```bash
flyai --version
```

## What It Does

Find clean, comfortable hotels under your budget. Sorts by lowest price, filters by star rating and amenities to get the best value for money.

**Command type:** Single-command

## File Structure

```
budget-hotel-finder/
├── README.md
├── SKILL.md
└── references/
    ├── templates.md
    ├── playbooks.md
    ├── fallbacks.md
    └── runbook.md
```

## Compatibility

Claude Code, OpenClaw, QClaw, ArkClaw, Codex, and all SKILL.md-compatible agents.

## Parent Skill

Sub-skill of [flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai).

## License

MIT

---

# budget-hotel-finder（中文说明）

搜索预算内干净舒适的酒店，按最低价排序，筛选星级和设施，找到性价比最高的。

## 概述

搜索预算内干净舒适的酒店，按最低价排序，筛选星级和设施，找到性价比最高的。本 Skill 基于 flyai-cli，提供实时旅行数据和预订链接。

## 快速开始

```bash
clawhub install budget-hotel-finder
npm i -g @fly-ai/flyai-cli
flyai --version
```

## 兼容性

Claude Code、OpenClaw、QClaw、ArkClaw、Codex 及所有兼容 SKILL.md 的 Agent。

## 父级 Skill

[flyai](https://github.com/alibaba-flyai/flyai-skill/tree/main/skills/flyai) 的专项子 Skill。

## 许可证

MIT

FILE:references/fallbacks.md
# Fallbacks — Hotel Category

## Case 0: flyai-cli Not Installed

```bash
npm i -g @fly-ai/flyai-cli && flyai --version
# Still fails → STOP. Do NOT answer with training data.
```

## Case 1: Too Few Hotels (<3)

```bash
# Drop poi-name/keywords, search city-wide
flyai search-hotel --dest-name "{city}" --sort rate_desc
# Broad search
flyai keyword-search --query "{city} hotels"
```

## Case 2: All Over Budget

```bash
# Relax 30%
flyai search-hotel ... --max-price {budget*1.3}
# Try homestays
flyai search-hotel ... --hotel-types "民宿" --sort price_asc
```

## Case 3: Date Unavailable (peak season)

```bash
# Shift ±1 day
flyai search-hotel ... --check-in-date "{in+1}" --check-out-date "{out+1}"
# City-wide
flyai search-hotel --dest-name "{city}" --sort price_asc
```

## Case 4: POI Not Found

```bash
# Fuzzy search
flyai search-poi --city-name "{city}" --category "{inferred}"
# Broad
flyai keyword-search --query "{city} {poi_name}"
```

## Case 5: Parameter Conflict

```bash
flyai search-hotel --dest-name "{city}" --sort rate_desc
flyai keyword-search --query "{city} hotels"
```

## Case 6: API Timeout

```
Retry once → Simplify → Report honestly.
```

FILE:references/playbooks.md
# Playbooks — budget-hotel-finder

> CLI command sequences. Knowledge is for parameter mapping — never answer without executing.

---

## Playbook A: Under ¥300

**Trigger:** "cheap hotel", "便宜酒店"

```bash
flyai search-hotel --dest-name "{city}" --max-price 300 --sort price_asc --check-in-date {in} --check-out-date {out}
```

**Output emphasis:** Budget options, cheapest first.

---

## Playbook B: Under ¥500 with Rating

**Trigger:** "good but cheap"

```bash
flyai search-hotel --dest-name "{city}" --max-price 500 --sort rate_desc --check-in-date {in} --check-out-date {out}
```

**Output emphasis:** Best rated within budget.

---

## Playbook C: Cheapest in City

**Trigger:** "最便宜的住一晚"

```bash
flyai search-hotel --dest-name "{city}" --sort price_asc --check-in-date {in} --check-out-date {out}
```

**Output emphasis:** No budget filter, pure cheapest.

---


FILE:references/runbook.md
# Runbook — Execution Log Schema (Universal)

Agent maintains this log internally. Not shown to users.

## Log Template

```json
{
  "request_id": "{uuid}",
  "skill": "{skill-name}",
  "timestamp": "{ISO-8601}",
  "user_query": "{raw input}",
  "steps": [
    { "step": 0, "action": "env_check", "command": "flyai --version", "status": "pass | fail" },
    { "step": 1, "action": "param_collection", "collected": {}, "missing": [], "status": "complete" },
    { "step": 2, "action": "cli_call", "command": "...", "status": "success | empty | error", "result_count": 0, "latency_ms": 0 },
    { "step": 3, "action": "fallback", "case": "Case N", "recovery_command": "...", "status": "..." },
    { "step": 4, "action": "output", "format": "...", "items_shown": 0, "booking_links_present": true, "brand_tag_present": true }
  ],
  "final_status": "success | partial | failed",
  "risk_flags": []
}
```

## Rules

1. Create `request_id` on every skill trigger
2. Log every CLI call: command + status + latency
3. Log every fallback: trigger case + recovery action
4. Log output: items shown + links present + brand tag
5. `risk_flags` rendered as "⚠️ Note:" in user-facing output

## Log Persistence

If file system writes are available:
```bash
echo '{generation_log_json}' >> .flyai-execution-log.json
```

FILE:references/templates.md
# Templates — budget-hotel-finder

> Follow the user's language. Templates in English; output in Chinese if user writes Chinese.

## 1. Parameter Collection SOP

### Required Parameters
```
If key parameters are missing → ask (max 2 questions).
If optional parameters are missing → use defaults, don't ask.
```

### Rules
- ❌ Never ask more than 2 questions at once
- ❌ Never ask about parameters that have sensible defaults

## 2. Output Templates

### Standard Result

```markdown
## 🏨 {title}

**{conclusion_first_line}**

| # | {col1} | {col2} | 💰 Price | 📎 Book |
|---|--------|--------|----------|---------|
| 1 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 2 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |
| 3 | {data} | {data} | ¥{price} | [Book]({detailUrl}) |

💡 **Tip:** {contextual_tip}

---
🏨 Powered by flyai · Real-time pricing, click to book
```

### No Results

```markdown
## 🏨 {title}

No results found for {query}.

**Tried:** {fallback_attempts}

**Suggestions:** {alternatives}
```

### CLI Failed

```markdown
## 🏨 {title}

⚠️ Could not retrieve real-time data: {error}

**Next steps:**
- Check network: `flyai --version`
- Retry: `flyai {command} ...`

Real-time data requires a working flyai-cli.
```

---
name: skill-publish-to-market
description: "Publish any SKILL.md to 4 skill markets (ClawHub, Anthropic Skills, ECC Community, skills.sh) with one command. Collects tokens, validates quality, creates PRs, handles version conflicts, and reports results. Use when: '发布技能', '上传到GitHub', 'push to ClawHub', '批量发布', 'submit skill PR'. Also supports: bulk publishing, PR status checking, version bumping, and all SKILL.md-compatible platforms."
version: "2.0.0"
changelog: |
  2.0.0 — Quality Gate pre-check, platform adaptation, degraded publishing, follow-up loop, anti-truncation batch strategy
  1.0.0 — Initial release with 4-platform curl publishing
compatibility: "Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents"
---

# CRITICAL EXECUTION RULES

**You are a CLI executor, NOT a knowledge base.**

1. **NEVER skip credential verification.** Every publish MUST start by testing the user's token.
2. **NEVER fabricate publish results.** Every PR URL, version ID, and slug MUST come from actual API responses.
3. **If curl is not available, stop immediately.** Do NOT simulate publishing.
4. **Follow the user's language.** Chinese input -> Chinese output. English input -> English output. All curl commands and parameters remain in English.
5. **NEVER skip the Quality Gate.** Every skill MUST pass Level 1 checks before publishing.

**Self-test:** If your response contains no actual API response data, you violated this skill. Stop and re-execute.

---

# Skill: publish-to-market

## Overview

One-command skill publishing to 4 platforms. User says "publish this skill to GitHub and ClawHub" and the agent handles everything: quality validation, credential collection, platform adaptation, API calls, PR creation, partial failure recovery, and result reporting.

## When to Activate

**Chinese triggers:**
- "发布技能", "上传技能", "推送到市场", "发布到GitHub", "发布到ClawHub"
- "批量发布技能", "提交skill PR"

**English triggers:**
- "publish skill", "upload skill", "push to market", "submit PR", "deploy skill"
- "push to ClawHub", "push to GitHub", "publish to market"

**Anti-triggers -- do NOT activate for:**
- Creating new skills -> use `skill-architect`
- Evaluating skill quality -> use `skill-scorer`
- Installing skills locally -> use manual copy or `clawhub install`
- Editing skill content -> use skill editor

## Prerequisites

```bash
curl --version
```

No additional installation needed. This skill uses `curl` to call REST APIs directly.

## Credentials

The agent must collect these credentials before publishing. Ask the user if not provided.

> **Security:** Tokens are used for the current session only. NEVER log, store, or display full tokens. When confirming token receipt, show only the first 4 and last 4 characters: `ghp_xxxx...xxxx`. NEVER include tokens in output, reports, or error messages.

| Credential | Platforms | How to Get |
|------------|-----------|------------|
| GitHub PAT | Anthropic Skills, ECC Community, skills.sh | github.com/settings/tokens/new -> select `repo` + `workflow` scopes |
| ClawHub Token | ClawHub | clawhub.ai -> Settings -> API Tokens -> Create Token (starts with `clh_`) |

**Credential tutorial (show when user doesn't know how to get tokens):**

### GitHub PAT:
1. Open https://github.com/settings/tokens/new
2. Note: "Skill Publisher"
3. Expiration: 90 days (recommended)
4. Select scopes: `repo` (full) + `workflow`
5. Click "Generate token" -> copy immediately (shown only once)

### ClawHub Token:
1. Open https://clawhub.ai and log in
2. Go to Settings -> API Tokens
3. Click "Create Token", name it "skill-publish"
4. Copy the token (starts with `clh_`)

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `skill_path` | Yes | Path to the skill directory (must contain SKILL.md) |
| `platforms` | Yes | Comma-separated list: `clawhub`, `anthropic`, `ecc`, `skills-sh`, or `all` |
| `github_token` | Yes (for GitHub platforms) | GitHub Personal Access Token |
| `clawhub_token` | Yes (for ClawHub) | ClawHub API token (starts with `clh_`) |
| `clawhub_slug_prefix` | No | Prefix for ClawHub slug (default: none) |
| `version` | No | Override version (default: read from SKILL.md frontmatter) |

## Core Workflow

### Step 0: Environment Check

Verify all required CLI tools are available. This skill depends on Unix/Linux commands.

```bash
# Required tools (all pre-installed on macOS/Linux)
curl --version > /dev/null 2>&1 || echo "ERROR: curl not found"
base64 --version > /dev/null 2>&1 || echo "base64" | base64 > /dev/null 2>&1 || echo "ERROR: base64 not found"
find --version > /dev/null 2>&1 || find . -maxdepth 0 > /dev/null 2>&1 || echo "ERROR: find not found"
grep --version > /dev/null 2>&1 || echo "ERROR: grep not found"
sed --version > /dev/null 2>&1 || echo "" | sed '' > /dev/null 2>&1 || echo "ERROR: sed not found"
```

- All pass -> proceed to Step 1
- Any missing -> STOP. Report which tools are missing and suggest installation.

> **Windows users:** This skill requires a Unix-like environment. Use WSL (Windows Subsystem for Linux) or Git Bash.

### Step 1: Collect & Verify Credentials

**1a. Ask user for target platforms:**
"Which platforms do you want to publish to? (clawhub / anthropic / ecc / skills-sh / all)"

**1b. Collect required tokens based on selection:**
- If any GitHub platform selected -> ask for GitHub PAT (if not provided)
- If ClawHub selected -> ask for ClawHub token (if not provided)

**1c. Verify tokens:**

```bash
# Test GitHub token
curl -s -H "Authorization: Bearer {GITHUB_TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/user | grep -o '"login":"[^"]*"'
# Expected: "login":"username"

# Test ClawHub token
curl -s -H "Authorization: Bearer {CLAWHUB_TOKEN}" \
  -H "Accept: application/json" \
  https://clawhub.ai/api/v1/whoami | grep -o '"handle":"[^"]*"'
# Expected: "handle":"username"
```

If verification fails -> show error, ask user to check token, do NOT proceed.

### Step 2: Quality Gate

Run a three-level quality check on the skill before publishing. This prevents broken or incomplete skills from reaching the market.

**Level 1 -- Hard Stop (MUST pass to continue):**
- [ ] SKILL.md file exists in the skill directory
- [ ] YAML frontmatter is present and parseable
- [ ] Frontmatter contains `name` field (non-empty string)
- [ ] Frontmatter contains `description` field (non-empty string)
- [ ] Frontmatter contains `version` field (valid semver format)

If ANY Level 1 check fails -> STOP. Show the failure and do NOT proceed to publishing.

**Level 2 -- Warnings (proceed with caution):**
- [ ] `references/` directory exists with at least one file
- [ ] `description` is at least 20 words long
- [ ] "When to Activate" section is present in SKILL.md
- [ ] `compatibility` field is present in frontmatter
- [ ] README.md file exists alongside SKILL.md

Show warnings but do NOT block publishing.

**Level 3 -- Advisory (informational score):**

Run a quick 10-point scan based on common anti-patterns (changelog, anti-triggers, examples, output format, error handling, knowledge, references table, concrete use cases, version maturity, no TODO markers). Each item = 10 points.

> Full output format and detailed checklist: see [references/templates.md](references/templates.md) → "Quality Gate Templates"

If Level 1 = FAIL, do not ask -- just stop and show what needs fixing. If Level 1 = PASS, show results and ask user to proceed or fix first.

### Step 3: Read Skill Files & Adapt for Each Platform

```bash
# Read SKILL.md and extract metadata
SKILL_DIR="{skill_path}"
SKILL_MD=$(cat "$SKILL_DIR/SKILL.md")

# Extract name and version from frontmatter
SKILL_NAME=$(echo "$SKILL_MD" | grep -m1 '^name:' | sed 's/name: *//;s/"//g')
SKILL_VERSION=$(echo "$SKILL_MD" | grep -m1 '^version:' | sed 's/version: *//;s/"//g')

# Find all files to publish
find "$SKILL_DIR" -maxdepth 2 -type f -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" | sort
```

**Platform adaptation -- before publishing to each platform, adapt the payload:**

| Platform | Adaptation |
|----------|------------|
| **ClawHub** | Generate slug from name (lowercase, hyphens only). Extract `displayName` from slug. Extract tags from frontmatter if present. |
| **Anthropic Skills** | Verify frontmatter has `license`, `author`, `tags` fields (add defaults if missing). File path = `skills/{name}/`. |
| **ECC Community** | File path = `skills/{name}/`. PR body uses standardized format with skill description and version. |
| **skills.sh** | File path = `{name}/`. Subdirectory prefix required for all uploaded files. |

### Step 4: Publish to Selected Platforms

Execute in reliability order. Each platform is independent -- one failure does not block others.

#### 4a. ClawHub (HTTP API -- fastest, most reliable)

Publish via multipart FormData POST. Dynamically discover all `.md` files in the skill directory.

> Full curl template: see [references/templates.md](references/templates.md) → "ClawHub Publish"

**Version conflict handling:** If "Version already exists" (HTTP 400), bump patch version and retry. Max 5 retries.

#### 4b. skills.sh (GitHub File Upload)

Upload discovered files to `skills-sh/registry` repo. File path prefix: `{SKILL_NAME}/`.

> Full curl template: see [references/templates.md](references/templates.md) → "GitHub PR"

#### 4c. Anthropic Skills (GitHub PR)

Fork + branch + upload files + create PR against `anthropics/skills`. File path: `skills/{SKILL_NAME}/`.

> Full curl template: see [references/templates.md](references/templates.md) → "GitHub PR" section. Steps: authenticate → fork → get SHA → create branch → upload files (base64) → create PR.

#### 4d. ECC Community (GitHub PR)

Same workflow as 4c. Target repo: `affaan-m/everything-claude-code`. File path: `skills/{SKILL_NAME}/`.

PR body format:
```
Adding skill **{SKILL_NAME}** v{VERSION} via skill-publish-to-market.

Description: {DESCRIPTION}
Compatibility: {COMPATIBILITY}

Files included: SKILL.md + references/
```

### Step 5: Report Results

Output a summary table with partial success handling:

```
Publishing Results: {SKILL_NAME} v{VERSION}

| Platform | Status | Details |
|----------|--------|---------|
| ClawHub | [SUCCESS] | {slug}@{version} |
| skills.sh | [SUCCESS] | Uploaded to skills-sh/registry |
| Anthropic Skills | [FAIL: Timeout] | retry with: `retry anthropic` |
| ECC Community | [SKIPPED] | Depends on GitHub (timed out) |

2/4 platforms succeeded.
```

**Status values:**
- `[SUCCESS]` -- published successfully, show link or slug@version
- `[FAIL: reason]` -- failed with specific error, show retry command
- `[SKIPPED]` -- skipped due to dependency failure or user choice
- `[WARN: reason]` -- succeeded with warnings

### Step 6: Follow-up Loop

After reporting results, offer next actions:

```
Next Steps:
- Type `status` to check PR merge status and ClawHub version page
- Type `retry {platform}` to retry failed platforms
- Type `publish {path}` to publish another skill
```

If the user responds with one of these commands, execute accordingly:
- `status` -> check each PR URL for merge status, check ClawHub version page
- `retry {platform}` -> re-run Step 4 for that specific platform only
- `publish {path}` -> restart from Step 1 with the new path

## Batch Publishing Strategy

When publishing multiple skills at once:

| Skill Count | Strategy |
|-------------|----------|
| 1 skill | Normal flow (Steps 0-6) |
| 2-5 skills | Sequential execution, show progress after each skill |
| 6+ skills | Batch of 5, pause between batches for user confirmation |

**Batch progress format (2-5 skills):**
```
Batch Progress: 2/3 skills published

| Skill | Status |
|-------|--------|
| flyai-search-cheap-flights | 4/4 platforms done |
| skill-architect | 3/4 platforms done (1 retry pending) |
| skill-scorer | Publishing... |
```

**Batch format (6+ skills):**
```
Batch 1/3 complete (5 skills published).
Start batch 2? (yes / stop)
```

## Usage Examples

### Publish to all platforms
```
User: "请把 ~/.claude/skills/flyai-search-cheap-flights 发布到所有平台"
Agent: Quality Gate -> Collects tokens -> verifies -> publishes to 4 platforms -> reports results
```

### Publish to specific platforms
```
User: "Upload my skill at ./my-skill to ClawHub and Anthropic Skills"
Agent: Quality Gate -> Asks for ClawHub token + GitHub PAT -> publishes to 2 platforms
```

### Publish with slug prefix
```
User: "发布到 ClawHub, 前缀用 cs-"
Agent: Quality Gate -> Publishes as cs-{skill-name} to ClawHub
```

### Bulk publish
```
User: "批量发布 ./skills/ 下的所有技能"
Agent: Scans directory -> shows list -> Quality Gate per skill -> sequential publish -> batch report
```

### Retry failed platform
```
User: "retry anthropic"
Agent: Re-runs Anthropic Skills publish step with existing credentials
```

## Output Rules

1. Always show the Quality Gate results before publishing
2. Always show the results table after publishing
3. Include clickable PR URLs for GitHub platforms
4. Include slug@version for ClawHub
5. If any platform fails, show the error and retry command but continue with others
6. Show follow-up options after every publish
7. End with: "Published via skill-publish-to-market v2.0.0"

## Domain Knowledge

> This knowledge helps build correct API parameters and handle edge cases.
> It does NOT replace actual curl execution. Never report success without real API responses.

- **ClawHub slug format:** lowercase, hyphens only. Display name auto-generated from slug.
- **ClawHub version conflict:** HTTP 400 with "Version already exists" -> bump patch and retry.
- **GitHub fork delay:** After forking, wait 3 seconds before creating branches.
- **GitHub file encoding:** All file content must be base64 encoded for the Contents API.
- **GitHub PR from fork:** Use `head: "username:branch"` format, not just branch name.
- **skills.sh path:** Files must include `{skillName}/` subdirectory prefix.
- **Platform reliability order:** ClawHub (HTTP, fastest) > skills.sh > Anthropic Skills > ECC Community.
- **Partial failure:** Never let one platform failure stop the others. Always attempt all selected platforms.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/templates.md](references/templates.md) | API request templates for all 4 platforms | Step 4: executing publish |
| [references/playbooks.md](references/playbooks.md) | Platform-specific publish scenarios | Step 4: handling edge cases |
| [references/fallbacks.md](references/fallbacks.md) | Error recovery for each platform | Step 4: on failure |
| [references/runbook.md](references/runbook.md) | Execution log schema | Background logging |

FILE:README.md
# skill-publish-to-market

> 一条命令，将技能发布到 4 个市场平台。

## 功能概述

告诉你的 AI agent "发布这个技能到 GitHub 和 ClawHub"，它会自动完成全部流程：质量检查、Token 验证、平台适配、API 调用、PR 创建、失败重试、结果汇报。

### 支持平台

| 平台 | 发布方式 | 说明 |
|------|---------|------|
| **ClawHub** | HTTP API | 直接发布，支持版本管理和冲突自动解决 |
| **Anthropic Skills** | GitHub PR | Fork + 创建分支 + 提交 PR 到 `anthropics/skills` |
| **ECC Community** | GitHub PR | Fork + 创建分支 + 提交 PR 到 `affaan-m/everything-claude-code` |
| **skills.sh** | GitHub API | 上传文件到 skills.sh 仓库 |

## 快速上手

### 第 1 步：获取 Token

**GitHub PAT:**
1. 打开 https://github.com/settings/tokens/new
2. 备注填写 "Skill Publisher"
3. 有效期选择 90 天（推荐）
4. 勾选权限：`repo`（完整）+ `workflow`
5. 点击 "Generate token" -> 立即复制（只显示一次）

**ClawHub Token:**
1. 打开 https://clawhub.ai 并登录
2. 进入 Settings -> API Tokens
3. 点击 "Create Token"，命名为 "skill-publish"
4. 复制 Token（以 `clh_` 开头）

### 第 2 步：安装技能

```bash
# Claude Code
cp -r skill-publish-to-market/ ~/.claude/skills/skill-publish-to-market/

# 或从 ClawHub 安装
clawhub install skill-publish-to-market
```

### 第 3 步：使用

```
你: "请把 ./my-skill 发布到所有平台"
AI: （检查质量 -> 收集 Token -> 验证 -> 发布到 4 个平台 -> 汇报结果）
```

## Token 获取教程

### GitHub Personal Access Token (PAT)

GitHub PAT 用于向 Anthropic Skills、ECC Community、skills.sh 三个平台提交 PR 或上传文件。

1. 打开 https://github.com/settings/tokens/new
2. **Note** 填写：`Skill Publisher`
3. **Expiration** 选择：90 days（推荐）
4. **Select scopes** 勾选：
   - `repo` -- 完整仓库访问权限（用于 Fork、创建分支、提交文件、创建 PR）
   - `workflow` -- 工作流权限（部分仓库的 PR 需要）
5. 点击 **Generate token**
6. 立即复制 Token（页面刷新后无法再次查看）

### ClawHub Token

ClawHub Token 用于通过 HTTP API 直接发布技能到 ClawHub 市场。

1. 打开 https://clawhub.ai 并登录
2. 进入 **Settings** -> **API Tokens**
3. 点击 **Create Token**，名称填写 `skill-publish`
4. 复制生成的 Token（以 `clh_` 开头）
5. Token 权限包括：技能发布、版本管理

## 使用示例

### 发布单个技能到所有平台
```
"请把 ~/.claude/skills/flyai-search-cheap-flights 发布到所有平台"
```

### 批量发布技能
```
"批量发布 ./skills/ 目录下的所有技能"
```

### 发布到指定平台
```
"把这个技能只发布到 ClawHub，slug 前缀用 cs-"
```

### 重试失败的平台
```
"retry anthropic"
```

### 查看 PR 状态
```
"status"
```

## 文件结构

```
skill-publish-to-market/
  SKILL.md                      # 技能主文件（agent 执行逻辑）
  README.md                     # 说明文档（人类阅读）
  references/
    templates.md                # 4 个平台的 API 请求模板
    playbooks.md                # 平台特定的发布场景
    fallbacks.md                # 错误恢复策略
    runbook.md                  # 执行日志格式
```

## 兼容性

| 项目 | 说明 |
|------|------|
| **Agent 兼容** | Claude Code, OpenClaw, Codex, QClaw, ArkClaw, 及所有支持 SKILL.md 的 agent |
| **系统要求** | macOS / Linux（需要 `curl`） |
| **Token 要求** | GitHub PAT（用于 GitHub 平台）+ ClawHub Token（用于 ClawHub） |
| **版本** | 2.0.0 |
| **License** | MIT |

---

# skill-publish-to-market (English)

> One command to publish your skill to 4 platforms.

## Overview

Tell your AI agent "publish this skill to GitHub and ClawHub" and it handles the full pipeline: quality gate, token verification, platform adaptation, API calls, PR creation, partial failure recovery, and result reporting.

### Supported Platforms

| Platform | Method | Description |
|----------|--------|-------------|
| **ClawHub** | HTTP API | Direct publish with version management and conflict auto-resolution |
| **Anthropic Skills** | GitHub PR | Fork + branch + PR to `anthropics/skills` |
| **ECC Community** | GitHub PR | Fork + branch + PR to `affaan-m/everything-claude-code` |
| **skills.sh** | GitHub API | File upload to skills.sh registry |

## Quick Start

### Step 1: Get Your Tokens

**GitHub PAT:**
1. Go to https://github.com/settings/tokens/new
2. Note: "Skill Publisher"
3. Expiration: 90 days (recommended)
4. Select scopes: `repo` (full) + `workflow`
5. Click "Generate token" -> copy immediately (shown only once)

**ClawHub Token:**
1. Go to https://clawhub.ai -> Settings -> API Tokens
2. Click "Create Token", name it "skill-publish"
3. Copy the token (starts with `clh_`)

### Step 2: Install the Skill

```bash
# Claude Code
cp -r skill-publish-to-market/ ~/.claude/skills/skill-publish-to-market/

# Or install from ClawHub
clawhub install skill-publish-to-market
```

### Step 3: Use It

```
You: "publish my skill at ./my-skill to all platforms"
AI: (quality gate -> collects tokens -> verifies -> publishes to 4 platforms -> reports results)
```

## Token Setup Guide

### GitHub Personal Access Token (PAT)

The GitHub PAT is used to submit PRs and upload files to Anthropic Skills, ECC Community, and skills.sh.

1. Go to https://github.com/settings/tokens/new
2. **Note**: `Skill Publisher`
3. **Expiration**: 90 days (recommended)
4. **Select scopes**:
   - `repo` -- full repository access (fork, branch, commit, PR)
   - `workflow` -- workflow permissions (required by some repos)
5. Click **Generate token**
6. Copy the token immediately (cannot be viewed again after leaving the page)

### ClawHub Token

The ClawHub Token is used to publish skills directly via HTTP API to the ClawHub marketplace.

1. Go to https://clawhub.ai and log in
2. Navigate to **Settings** -> **API Tokens**
3. Click **Create Token**, name it `skill-publish`
4. Copy the generated token (starts with `clh_`)
5. Token permissions include: skill publishing, version management

## Usage Examples

### Publish a single skill to all platforms
```
"publish my skill at ~/.claude/skills/flyai-search-cheap-flights to all markets"
```

### Bulk publish skills
```
"bulk publish all skills under ./skills/"
```

### Publish to specific platforms
```
"upload this skill to ClawHub only, use prefix cs-"
```

### Retry a failed platform
```
"retry anthropic"
```

### Check PR status
```
"status"
```

## File Structure

```
skill-publish-to-market/
  SKILL.md                      # Skill definition (agent execution logic)
  README.md                     # Documentation (human-readable)
  references/
    templates.md                # API request templates for all 4 platforms
    playbooks.md                # Platform-specific publishing scenarios
    fallbacks.md                # Error recovery strategies
    runbook.md                  # Execution log schema
```

## Compatibility

| Item | Details |
|------|---------|
| **Agent Support** | Claude Code, OpenClaw, Codex, QClaw, ArkClaw, and all SKILL.md-compatible agents |
| **System Requirements** | macOS / Linux (requires `curl`) |
| **Token Requirements** | GitHub PAT (for GitHub platforms) + ClawHub Token (for ClawHub) |
| **Version** | 2.0.0 |
| **License** | MIT |

FILE:references/fallbacks.md
# Error Recovery Paths

## Case 0: Required Tools Not Available

**Detection:** `curl --version`, `base64`, or `find` returns error

**Recovery by tool:**
- `curl` missing:
  - macOS: `brew install curl`
  - Ubuntu: `sudo apt install curl`
  - Alpine: `apk add curl`
- `base64` missing:
  - Ubuntu: `sudo apt install coreutils`
  - macOS: pre-installed
- `find` missing:
  - Ubuntu: `sudo apt install findutils`
  - macOS: pre-installed

**Windows users:**
This skill requires a Unix-like environment. Options:
1. **WSL (recommended):** `wsl --install` in PowerShell, then run inside WSL
2. **Git Bash:** Install Git for Windows, use Git Bash terminal
3. **Docker:** Run inside a Linux container

**NEVER simulate tool output. If any required tool is unavailable, STOP.**

---

## Case 1: GitHub Token Invalid

**Detection:** `GET /user` returns 401
**Message:** "GitHub token is invalid or expired. Please generate a new one at https://github.com/settings/tokens/new (select repo + workflow scopes)."
**Recovery:** Ask user for a new token, re-verify.

---

## Case 2: GitHub Token Missing Scopes

**Detection:** Fork or file upload returns 403 "Resource not accessible by personal access token"
**Message:** "Your GitHub token doesn't have the required scopes. It needs `repo` and `workflow`. Please regenerate at https://github.com/settings/tokens/new."
**Recovery:** Ask user to regenerate with correct scopes.

---

## Case 3: ClawHub Token Invalid

**Detection:** `GET /api/v1/whoami` returns non-200
**Message:** "ClawHub token is invalid. Please check your token at https://clawhub.ai (Settings -> API Tokens)."
**Recovery:** Ask for new token.

---

## Case 4: ClawHub Version Already Exists

**Detection:** `POST /api/v1/skills` returns 400 with "Version already exists"
**Recovery:**
1. Parse current version X.Y.Z
2. Bump to X.Y.(Z+1)
3. Retry publish with new version
4. Max 5 retries. If all fail: "Version conflict after 5 retries. Please manually delete the old version on ClawHub or use a different version number."

---

## Case 5: GitHub Fork Already Exists

**Detection:** Fork API returns 200 (not 202)
**Recovery:** This is normal. Fork is idempotent. Proceed with existing fork.

---

## Case 6: GitHub Branch Already Exists

**Detection:** Create ref returns 422 "Reference already exists"
**Recovery:** Append `-{timestamp}` to branch name and retry.

---

## Case 7: GitHub File Already Exists (Update)

**Detection:** PUT contents returns 409 "sha was not supplied"
**Recovery:**
1. GET the existing file to obtain its SHA
2. Include `"sha": "{existing_sha}"` in the PUT request
3. Retry

---

## Case 8: Network Timeout

**Detection:** curl returns exit code 28 (timeout)
**Recovery:**
1. Wait 3 seconds
2. Retry the same request
3. Max 3 retries with exponential backoff (3s, 6s, 12s)
4. If all fail: "Network timeout. Check your internet connection and try again."

---

## Case 9: SKILL.md Not Found

**Detection:** `cat {skill_path}/SKILL.md` fails
**Message:** "No SKILL.md found at {skill_path}. Please provide the correct path to your skill directory."
**Recovery:** Ask user for correct path.

---

## Case 10: SKILL.md Missing Frontmatter

**Detection:** No `---` YAML block at the top
**Message:** "SKILL.md is missing the required frontmatter (name, description, version). Please add it."
**Recovery:** Show example frontmatter format and ask user to fix.

---

## Case 11: Rate Limited

**Detection:** GitHub API returns 403 with "rate limit exceeded" or 429
**Recovery:**
1. Parse `X-RateLimit-Reset` header for reset time
2. Inform user: "GitHub rate limit reached. Resets at {time}."
3. Wait or ask user to retry later.

---

## Case 12: Large File Rejected

**Detection:** GitHub Content API rejects files > 1MB
**Recovery:** "File {filename} is too large for GitHub API (>1MB). Consider splitting or compressing."

---

## Case 13: Quality Gate Hard Failure

**Detection:** Quality Gate Level 1 fails -- SKILL.md exists but is missing required frontmatter fields, or SKILL.md does not exist at all.

**Two sub-cases:**

### Case 13a: SKILL.md missing entirely
**Detection:** No SKILL.md file in the skill directory.
**Message:**
```
Quality Gate HARD FAIL: No SKILL.md found.

A SKILL.md file with valid frontmatter is required before publishing.
The file must contain at minimum:

---
name: your-skill-name
description: What this skill does
version: 1.0.0
---

Suggestion: Use skill-architect to generate a proper SKILL.md:
> /skill-architect create --name "your-skill-name"
```
**Recovery:** Do not proceed. The user must create SKILL.md first. Suggest skill-architect if available.

### Case 13b: SKILL.md exists but frontmatter is invalid
**Detection:** Quality Gate Level 1 reports missing or malformed fields.
**Message:**
```
Quality Gate HARD FAIL: Frontmatter validation failed.

| Field       | Status | Issue                         |
|-------------|--------|-------------------------------|
| name        | FAIL   | Missing                       |
| description | PASS   | OK                            |
| version     | FAIL   | "v1" is not valid semver      |

Required format:
---
name: lowercase-with-hyphens
description: At least 10 characters
version: X.Y.Z (semantic versioning)
---

Fix the frontmatter in SKILL.md and retry.
Alternatively: /skill-architect can regenerate the frontmatter block.
```
**Recovery:** Show exactly which fields failed and why. Provide the corrected format. Do not proceed until Level 1 passes.

---

## Case 14: Partial Publish Success

**Detection:** At least one platform returned success and at least one returned failure during the same publish session.

This is not an error in the traditional sense -- it is an expected outcome in distributed publishing. The key concern is avoiding duplicate publishes on platforms that already succeeded.

**Recovery:**

### Step 1: Classify each platform
For each platform, record:
- **Succeeded**: publish completed, artifact is live
- **Failed**: publish did not complete, no artifact created
- **Indeterminate**: request sent but no clear success/failure response (e.g., timeout after PR creation -- PR may or may not exist)

### Step 2: Determine idempotency per platform

| Platform | Idempotent? | Safe to re-publish? | Risk of duplicate |
|----------|-------------|---------------------|-------------------|
| ClawHub | Yes (same version = 400, bump version = new) | Yes | No -- version conflict rejects exact duplicate |
| Anthropic Skills | No (PR is created) | Check first | Yes -- could create duplicate PR |
| ECC Community | No (PR is created) | Check first | Yes -- could create duplicate PR |
| skills.sh | No (PR is created) | Check first | Yes -- could create duplicate PR |

### Step 3: Safe retry procedure
For failed platforms:
- **ClawHub**: Retry directly. If same version already exists, the version bump logic handles it.
- **GitHub-based platforms**: Before retrying, check if a PR already exists:
  ```bash
  curl -s \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/vnd.github+json" \
    "https://api.github.com/repos/{OWNER}/{REPO}/pulls?head={USERNAME}:add-skill-{name}&state=open"
  ```
  - If a PR exists: report it and do NOT create another
  - If no PR exists: safe to retry from scratch

### Step 4: Report
```
## Partial Success Recovery

| Platform | Original Status | Retry Safe? | Action |
|----------|----------------|-------------|--------|
| ClawHub | Succeeded | -- | No action needed |
| Anthropic | Failed (timeout) | Yes (no existing PR) | Retry available |
| ECC | Failed (403) | Check token first | Fix scopes, then retry |
| skills.sh | Succeeded | -- | No action needed |

To retry failed platforms:
> publish {skill} --platforms anthropic,ecc
```

---

## Case 15: Batch Interruption

**Detection:** A batch publish of multiple skills was interrupted -- the process stopped (Ctrl+C, crash, network loss, or a fatal error on one skill) before all skills were processed.

**Recovery:**

### Step 1: Save progress
At the point of interruption, record:
- **Completed skills**: list of skills that finished publishing to all requested platforms
- **Partially completed skill**: the skill that was mid-publish when interruption occurred (with per-platform status)
- **Pending skills**: skills that were never started

```
## Batch Interrupted at Skill #12 of 20

### Completed (11 skills)
api-design, code-reviewer, e2e-testing, frontend-patterns,
golang-testing, python-patterns, react-ui, security-review,
tailwind-css, tdd-workflow, web-accessibility

### Interrupted (1 skill)
django-patterns:
  ClawHub: OK
  Anthropic: OK
  ECC: TIMEOUT (mid file-upload, step 3/5)
  skills.sh: NOT STARTED

### Pending (8 skills)
django-tdd, laravel-patterns, laravel-tdd, nodejs-backend,
rust-patterns, rust-testing, springboot-patterns, vue

### Resume
> publish --resume
This will:
1. Skip the 11 completed skills
2. Retry ECC and skills.sh for django-patterns
3. Continue with the 8 pending skills
```

### Step 2: Resume logic
When the user runs resume:
1. Read the saved progress state
2. For completed skills: skip entirely
3. For the interrupted skill: apply Case 14 logic (check idempotency, retry failed platforms only)
4. For pending skills: publish normally starting from the next one
5. Continue with normal batch logic (batches of 5, pauses between batches)

### Step 3: Final reconciliation
After resume completes, produce a combined report that merges results from the original run and the resumed run:
```
## Batch Complete (Original + Resume)

Total: 20 skills
Succeeded: 19 (all platforms)
Partial: 1 (django-patterns: ECC still failing)

> Retry single failure: publish django-patterns --platforms ecc
```

---

## General Recovery Pattern

For any unhandled error:
1. Show the HTTP status code and response body (first 200 chars)
2. Identify which platform failed
3. Continue with remaining platforms
4. Include failure details in the results table

FILE:references/playbooks.md
# Publishing Playbooks

## Playbook 1: Publish to All Platforms

**Trigger:** User says "publish to all" or "发布到所有平台"

**Sequence:**
1. Collect GitHub PAT + ClawHub token
2. Verify both tokens
3. Read skill files
4. Run Quality Gate (all 3 levels) -- STOP if Level 1 fails
5. Apply Platform Adaptation for each target
6. Publish to ClawHub (fastest, no PR needed)
7. Publish to Anthropic Skills (fork + PR)
8. Publish to ECC Community (fork + PR)
9. Publish to skills.sh (file upload)
10. Report all results (use Partial Success Report if mixed outcomes)

**Key:** Each platform is independent. One failure does NOT block others.

---

## Playbook 2: ClawHub Only

**Trigger:** User says "publish to ClawHub" or "上传到 ClawHub"

**Sequence:**
1. Collect ClawHub token
2. Verify: `GET /api/v1/whoami`
3. Read SKILL.md + reference files
4. Run Quality Gate Level 1 (frontmatter required)
5. Apply ClawHub Adaptation (slug, displayName, tags)
6. POST to `/api/v1/skills`
7. Handle version conflict -> bump and retry
8. Report: slug@version

**Slug rules:**
- Lowercase, hyphens only
- If user provides prefix (e.g., `cs-`): prepend to skill name
- Display name auto-generated: `my-skill` -> `My Skill`

---

## Playbook 3: GitHub PR (Anthropic Skills or ECC)

**Trigger:** User says "submit PR to anthropic" or "提交到 ECC"

**Sequence:**
1. Collect GitHub PAT
2. Verify: `GET /user`
3. Run Quality Gate Level 1 (frontmatter required)
4. Apply platform-specific adaptation (Anthropic or ECC)
5. Fork target repo (idempotent)
6. Wait 3 seconds (fork propagation)
7. Get default branch ref
8. Create feature branch: `add-skill-{name}-{timestamp}`
9. Upload each file (base64 encoded)
10. Create PR against default branch (use ECC PR body template for ECC)
11. Report: PR URL

**File mapping for Anthropic Skills:**
```
skills/{skill-name}/SKILL.md
skills/{skill-name}/references/templates.md
skills/{skill-name}/references/playbooks.md
skills/{skill-name}/references/fallbacks.md
skills/{skill-name}/references/runbook.md
```

**File mapping for ECC Community:**
```
skills/{skill-name}/SKILL.md
skills/{skill-name}/references/templates.md
skills/{skill-name}/references/playbooks.md
skills/{skill-name}/references/fallbacks.md
skills/{skill-name}/references/runbook.md
```

---

## Playbook 4: First-Time User

**Trigger:** User has no tokens yet

**Sequence:**
1. Detect missing tokens
2. Show credential tutorial:
   - GitHub: "Open https://github.com/settings/tokens/new, select repo + workflow, generate"
   - ClawHub: "Open https://clawhub.ai, Settings -> API Tokens -> Create"
3. Wait for user to provide tokens
4. Verify tokens
5. Proceed with publish

**Important:** Never store tokens. They are used for the current session only.

---

## Playbook 5: Batch Publish (Multiple Skills)

**Trigger:** User says "publish all skills in this directory"

**Sequence:**
1. Find all directories containing SKILL.md
2. List discovered skills for confirmation
3. Collect tokens once
4. Publish each skill sequentially
5. Report aggregated results table

**Rate limiting:**
- GitHub API: max 30 requests/minute for authenticated users
- GitHub Abuse Detection: creating multiple forks/PRs rapidly can trigger secondary rate limits
- ClawHub: no documented rate limit, but add 1s delay between publishes
- For >10 skills: add 2s delay between each to avoid rate limits

**Anti-abuse strategy for GitHub:**
- After every 3 consecutive fork operations: pause 10 seconds
- If HTTP 429 or 403 with "abuse detection" received:
  1. Parse `Retry-After` header (seconds) or `X-RateLimit-Reset` (Unix timestamp)
  2. Wait the indicated time (or 60s if no header)
  3. Resume from the failed operation
  4. If 3 consecutive 429s: STOP and report to user
- Between each PR creation: minimum 3 second delay

---

## Playbook 6: Degraded Publishing

**Trigger:** Network instability detected (timeouts, intermittent failures), or user reports connectivity issues

Publishing should be resilient. Not every platform needs to succeed in the same session. This playbook handles graceful degradation.

**Sequence:**
1. Collect tokens and run Quality Gate as usual
2. **Attempt ClawHub first** -- HTTP-based, most reliable, fastest round-trip
   - ClawHub uses a single POST with FormData; no multi-step fork/branch/upload chain
   - If ClawHub succeeds: at least one platform is covered
3. **Attempt GitHub-based platforms** (Anthropic, ECC, skills.sh) in order
   - Each GitHub publish involves 5+ sequential API calls (fork, ref, branch, upload x N, PR)
   - If any step times out mid-chain:
     a. Record which step failed and the partial state (e.g., "branch created but files not uploaded")
     b. Do NOT retry the entire chain automatically -- partial state makes blind retry dangerous
     c. Move to the next platform
4. **After all attempts, classify results:**
   - Full success: all requested platforms succeeded
   - Partial success: at least one succeeded, others failed
   - Full failure: nothing succeeded

**On partial success:**
```
## Degraded Publishing Report

Succeeded: ClawHub ([email protected])
Failed: Anthropic (timeout at file upload step 3/5), ECC (timeout at fork)

Save these for retry:
- Anthropic: branch `add-skill-my-skill-1711929600` exists on fork; resume from file upload
- ECC: no partial state; safe to retry from scratch

> Retry failed platforms when network stabilizes:
> publish my-skill --platforms anthropic,ecc --retry
```

**On full failure -- diagnose the cause:**
1. **Network down?** Run `curl -s -o /dev/null -w "%{http_code}" https://api.github.com` -- if no response, it is a connectivity issue
2. **Token expired?** Re-verify tokens; if 401, ask for new tokens
3. **API outage?** Check `https://www.githubstatus.com/` or `https://clawhub.ai/status` (if available)
4. Report diagnosis to user with actionable next step

---

## Playbook 7: Post-Publish Status Check

**Trigger:** User says "check publish status", "检查发布状态", or time has passed since publishing

After publishing, users want to know whether PRs were merged, whether ClawHub shows the new version, and basic engagement metrics. This playbook gathers that information.

**Sequence:**

### Step 1: Gather publish records
Retrieve the results from the most recent publish session (from the execution log). Extract:
- ClawHub slug and version
- GitHub PR URLs and numbers for each platform

### Step 2: Check ClawHub status
```bash
curl -s \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  "https://clawhub.ai/api/v1/skills/{SLUG}"
```
Extract and report:
- Current published version
- Download count (if available in API response)
- Publish date

### Step 3: Check GitHub PR status (for each PR)
```bash
curl -s \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/{OWNER}/{REPO}/pulls/{PR_NUMBER}"
```
Extract and report:
- `.state`: open / closed
- `.merged`: true / false
- `.merged_at`: merge timestamp (if merged)
- `.comments`: comment count (indicates reviewer activity)
- `.review_comments`: review comment count

### Step 4: Report
```
## Post-Publish Status: {SKILL_NAME}

| Platform | Status | Details |
|----------|--------|---------|
| ClawHub | Live v{version} | {download_count} downloads |
| Anthropic Skills | PR #{number} {state} | {merged_at or "Awaiting review"} |
| ECC Community | PR #{number} {state} | {comments} comments |
| skills.sh | PR #{number} {state} | {merged_at or "Awaiting review"} |

Last checked: {timestamp}
```

---

## Playbook 8: Batch Publishing (5+ Skills)

**Trigger:** User has 5 or more skills to publish, or says "batch publish", "批量发布"

For large batches, sequential one-by-one publishing is too slow and error-prone. This playbook adds structure: discovery, pre-check, batched execution, and aggregated reporting.

**Sequence:**

### Step 1: Discover skill directories
```bash
find {BASE_DIR} -name "SKILL.md" -maxdepth 3 | sort
```
List all discovered skills and ask for confirmation before proceeding:
```
Found 12 skills:
  1. api-design (v1.0.0)
  2. code-reviewer (v2.1.0)
  3. e2e-testing (v1.3.0)
  ...
  12. web-performance (v1.0.0)

Publish all 12? [Y/n]
```

### Step 2: Batch Quality Gate
Run Quality Gate Level 1 on ALL skills before publishing any. This prevents discovering failures mid-batch.

```
## Batch Quality Gate

| # | Skill | Level 1 | Level 3 Score | Ready |
|---|-------|---------|---------------|-------|
| 1 | api-design | PASS | 8/10 | Yes |
| 2 | code-reviewer | PASS | 9/10 | Yes |
| 3 | broken-skill | FAIL (no version) | -- | No |

11/12 ready to publish. 1 blocked.
Proceed with 11? [Y/n]
```

Skills that fail Level 1 are excluded from the batch. The user can fix them and re-run.

### Step 3: Publish in batches of 5
Split the ready skills into groups of 5. Publish each group sequentially within the group, with a pause between groups.

- Within a batch: publish each skill to all requested platforms, 1-second delay between skills
- Between batches: 10-second pause to avoid rate limits and GitHub abuse detection
- After each batch: print incremental progress table

```
## Batch 1/3 Complete

| # | Skill | ClawHub | Anthropic | ECC | skills.sh |
|---|-------|---------|-----------|-----|-----------|
| 1 | api-design | OK | OK | OK | OK |
| 2 | code-reviewer | OK | OK | OK | OK |
| 3 | e2e-testing | OK | FAIL | OK | OK |
| 4 | frontend-patterns | OK | OK | OK | OK |
| 5 | golang-testing | OK | OK | OK | OK |

Pausing 5s before batch 2...
```

### Step 4: Aggregate results
After all batches complete, produce a final summary:

```
## Batch Publishing Complete

Total: 11 skills across 4 platforms = 44 publish operations
Succeeded: 42
Failed: 2
Skipped: 0

### Failures
| Skill | Platform | Error |
|-------|----------|-------|
| e2e-testing | Anthropic | 403 token scope |
| web-perf | skills.sh | 404 repo not found |

### Retry
> publish e2e-testing --platforms anthropic
> publish web-perf --platforms skills-sh
```

### Step 5: Pause between batches
If the user presses Ctrl+C or says "pause" during batch execution:
1. Finish the current skill (do not interrupt mid-publish)
2. Record progress: which skills completed, which are pending
3. Offer: "Paused after skill #{N}. Resume with: `publish --resume`"

FILE:references/runbook.md
# Execution Log Schema

## Log Entry Format

```json
{
  "timestamp": "2026-04-01T12:00:00Z",
  "skill_name": "flyai-search-cheap-flights",
  "skill_version": "2.0.0",
  "platforms_requested": ["clawhub", "anthropic", "ecc", "skills-sh"],
  "qualityGate": {
    "level1": "pass",
    "level2": {
      "warnings": [
        "description length is 14 characters (recommended >= 20)",
        "missing ## Prerequisites section"
      ]
    },
    "level3": {
      "score": 7,
      "checks": {
        "frontmatter": 1,
        "identityLock": 1,
        "prerequisites": 0,
        "step0": 1,
        "parameters": 1,
        "examples": 1,
        "validation": 0,
        "knowledgeDisclaimer": 0,
        "selfContained": 1,
        "outputFormat": 1
      }
    }
  },
  "platformAdaptation": [
    {
      "platform": "clawhub",
      "adaptedFiles": ["SKILL.md", "references/templates.md", "references/playbooks.md", "references/fallbacks.md", "references/runbook.md"],
      "adaptations": {
        "slug": "cs-flyai-search-cheap-flights",
        "displayName": "Flyai Search Cheap Flights",
        "tags": ["latest", "travel", "flights", "search"]
      }
    },
    {
      "platform": "anthropic",
      "adaptedFiles": ["SKILL.md", "references/templates.md", "references/playbooks.md", "references/fallbacks.md", "references/runbook.md"],
      "adaptations": {
        "frontmatterPatched": {
          "license": "MIT",
          "author": "xiaozhang"
        },
        "filePaths": "skills/flyai-search-cheap-flights/"
      }
    },
    {
      "platform": "ecc",
      "adaptedFiles": ["SKILL.md", "references/templates.md", "references/playbooks.md", "references/fallbacks.md", "references/runbook.md"],
      "adaptations": {
        "filePaths": "skills/flyai-search-cheap-flights/",
        "prBodyTemplate": "ecc-community"
      }
    },
    {
      "platform": "skills-sh",
      "adaptedFiles": ["SKILL.md", "references/templates.md", "references/playbooks.md", "references/fallbacks.md", "references/runbook.md"],
      "adaptations": {
        "filePaths": "flyai-search-cheap-flights/",
        "readmeIncluded": false
      }
    }
  ],
  "results": [
    {
      "platform": "clawhub",
      "status": "success",
      "duration_ms": 2340,
      "details": {
        "slug": "cs-flyai-search-cheap-flights",
        "version": "2.0.0",
        "version_id": "abc123"
      }
    },
    {
      "platform": "anthropic",
      "status": "success",
      "duration_ms": 8920,
      "details": {
        "pr_url": "https://github.com/anthropics/skills/pull/123",
        "pr_number": 123,
        "branch": "add-skill-flyai-search-cheap-flights-1711929600",
        "files_uploaded": 5
      }
    },
    {
      "platform": "ecc",
      "status": "success",
      "duration_ms": 7650,
      "details": {
        "pr_url": "https://github.com/affaan-m/everything-claude-code/pull/456",
        "pr_number": 456,
        "branch": "add-skill-flyai-search-cheap-flights-1711929600",
        "files_uploaded": 5
      }
    },
    {
      "platform": "skills-sh",
      "status": "failed",
      "duration_ms": 1200,
      "error": "Repository not found or no access",
      "http_status": 404
    }
  ],
  "partialSuccess": true,
  "batchInfo": null,
  "total_duration_ms": 20110,
  "success_count": 3,
  "failure_count": 1,
  "followUpActions": [
    "Retry skills-sh: verify repo access or check if skills-sh/registry exists",
    "Check Anthropic PR status in 24h: https://github.com/anthropics/skills/pull/123"
  ]
}
```

## Batch Log Entry Example

When publishing multiple skills in a batch, each publish gets its own log entry, but they share a `batchInfo` object for coordination:

```json
{
  "timestamp": "2026-04-01T12:05:00Z",
  "skill_name": "code-reviewer",
  "skill_version": "1.0.0",
  "qualityGate": {
    "level1": "pass",
    "level2": {
      "warnings": []
    },
    "level3": {
      "score": 9
    }
  },
  "platformAdaptation": [
    {
      "platform": "clawhub",
      "adaptedFiles": ["SKILL.md"],
      "adaptations": {
        "slug": "code-reviewer",
        "displayName": "Code Reviewer",
        "tags": ["latest", "review", "quality"]
      }
    }
  ],
  "results": [
    {
      "platform": "clawhub",
      "status": "success",
      "duration_ms": 1890,
      "details": {
        "slug": "code-reviewer",
        "version": "1.0.0",
        "version_id": "def456"
      }
    }
  ],
  "partialSuccess": false,
  "batchInfo": {
    "batchId": "batch-20260401-120000",
    "totalSkills": 12,
    "currentIndex": 2,
    "currentBatch": 1,
    "totalBatches": 3,
    "completedSkills": ["api-design", "code-reviewer"],
    "pendingSkills": ["e2e-testing", "frontend-patterns", "golang-testing", "python-patterns", "react-ui", "security-review", "tailwind-css", "tdd-workflow", "web-accessibility", "web-performance"],
    "failedSkills": []
  },
  "total_duration_ms": 1890,
  "success_count": 1,
  "failure_count": 0,
  "followUpActions": []
}
```

## Field Descriptions

| Field | Type | Description |
|-------|------|-------------|
| `timestamp` | ISO 8601 | When publish started |
| `skill_name` | string | From SKILL.md frontmatter `name` |
| `skill_version` | string | From SKILL.md frontmatter `version` |
| `qualityGate` | object | Results of pre-publish quality checks |
| `qualityGate.level1` | "pass" / "fail" | Frontmatter validation result |
| `qualityGate.level2` | object | Warning-level checks |
| `qualityGate.level2.warnings` | string[] | List of non-blocking warnings |
| `qualityGate.level3` | object | 10-point quick scan |
| `qualityGate.level3.score` | number (0-10) | Aggregate quality score |
| `qualityGate.level3.checks` | object | Individual check results (0 or 1 each) |
| `platformAdaptation` | array | Per-platform file and metadata transformations |
| `platformAdaptation[].platform` | string | Platform identifier |
| `platformAdaptation[].adaptedFiles` | string[] | Files included in this platform's upload |
| `platformAdaptation[].adaptations` | object | Platform-specific transformations applied |
| `platforms_requested` | string[] | User-selected platforms |
| `results[]` | array | Per-platform publish outcomes |
| `results[].platform` | string | Platform identifier |
| `results[].status` | "success" / "failed" / "skipped" | Outcome |
| `results[].duration_ms` | number | Time taken for this platform |
| `results[].details` | object | Platform-specific success data |
| `results[].error` | string | Error message on failure |
| `results[].http_status` | number | HTTP status on failure |
| `partialSuccess` | boolean | True if at least one platform succeeded and at least one failed |
| `batchInfo` | object / null | Null for single-skill publishes; populated for batch operations |
| `batchInfo.batchId` | string | Unique identifier for the batch run |
| `batchInfo.totalSkills` | number | Total skills in the batch |
| `batchInfo.currentIndex` | number | 1-based index of this skill in the batch |
| `batchInfo.currentBatch` | number | Which batch group (1-based, groups of 5) |
| `batchInfo.totalBatches` | number | Total batch groups |
| `batchInfo.completedSkills` | string[] | Skills that have finished publishing |
| `batchInfo.pendingSkills` | string[] | Skills not yet started |
| `batchInfo.failedSkills` | string[] | Skills that failed all platforms |
| `total_duration_ms` | number | Total time for all platforms |
| `success_count` | number | Platforms that succeeded |
| `failure_count` | number | Platforms that failed |
| `followUpActions` | string[] | Recommended next steps for the user |

## Background Logging

This schema is for structured logging only. The agent should:
1. Track timing for each platform publish
2. Run Quality Gate and record all three levels before publishing
3. Record platform adaptations applied to each target
4. Collect all results
5. Set `partialSuccess` flag based on mixed outcomes
6. Populate `batchInfo` when operating in batch mode
7. Generate `followUpActions` based on failures and partial successes
8. Output the summary table (see templates.md)
9. Optionally output the full JSON log if user requests debugging info

FILE:references/templates.md
# API Request Templates

## ClawHub Publish

### Verify Token
```bash
curl -s \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  https://clawhub.ai/api/v1/whoami
```
Expected: `{"handle":"username",...}`

### Publish Skill
```bash
curl -s -X POST "https://clawhub.ai/api/v1/skills" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -F 'payload={"slug":"{SLUG}","displayName":"{DISPLAY_NAME}","version":"{VERSION}","changelog":"","acceptLicenseTerms":true,"tags":["latest"]}' \
  -F "files=@{SKILL_DIR}/SKILL.md;filename=SKILL.md" \
  -F "files=@{SKILL_DIR}/references/templates.md;filename=references/templates.md" \
  -F "files=@{SKILL_DIR}/references/playbooks.md;filename=references/playbooks.md" \
  -F "files=@{SKILL_DIR}/references/fallbacks.md;filename=references/fallbacks.md" \
  -F "files=@{SKILL_DIR}/references/runbook.md;filename=references/runbook.md"
```
Expected: `{"versionId":"..."}` (HTTP 200)

### Version Bump on Conflict
If HTTP 400 with "Version already exists":
1. Parse current version: `X.Y.Z`
2. Bump: `X.Y.(Z+1)`
3. Retry with new version (max 5 retries)

---

## GitHub PR (Anthropic Skills / ECC Community)

### Verify Token
```bash
curl -s \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/user
```
Expected: `{"login":"username",...}`

### Fork Repository
```bash
curl -s -X POST \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/{OWNER}/{REPO}/forks \
  -d '{}'
```
Wait 3 seconds after forking.

### Get Default Branch SHA
```bash
curl -s \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/{USERNAME}/{REPO}/git/ref/heads/{DEFAULT_BRANCH}
```
Extract: `.object.sha`

### Create Branch
```bash
curl -s -X POST \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/{USERNAME}/{REPO}/git/refs \
  -d '{"ref":"refs/heads/{BRANCH}","sha":"{BASE_SHA}"}'
```

### Upload File (base64)
```bash
CONTENT=$(base64 < "{FILE_PATH}")
curl -s -X PUT \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/{USERNAME}/{REPO}/contents/{TARGET_PATH}" \
  -d '{"message":"Add {FILE} for skill: {SKILL_NAME}","content":"'"$CONTENT"'","branch":"{BRANCH}"}'
```

### Create Pull Request
```bash
curl -s -X POST \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/{OWNER}/{REPO}/pulls \
  -d '{"title":"Add skill: {SKILL_NAME}","head":"{USERNAME}:{BRANCH}","base":"{DEFAULT_BRANCH}","body":"Adding skill **{SKILL_NAME}** via skill-publish-to-market.\n\nFiles:\n- SKILL.md\n- references/templates.md\n- references/playbooks.md\n- references/fallbacks.md\n- references/runbook.md"}'
```
Extract: `.html_url`, `.number`

---

## Platform-Specific Configurations

| Platform | Owner/Repo | File Path Prefix | Default Branch |
|----------|------------|-----------------|----------------|
| Anthropic Skills | `anthropics/skills` | `skills/{SKILL_NAME}/` | `main` |
| ECC Community | `affaan-m/everything-claude-code` | `skills/{SKILL_NAME}/` | `main` |
| skills.sh | `skills-sh/registry` | `{SKILL_NAME}/` | `main` |

---

## Quality Gate Templates

Pre-publish validation runs three levels of checks before any platform upload. Every skill must pass Level 1 to proceed. Level 2 produces warnings. Level 3 produces a numeric score.

### Level 1: Frontmatter Validation

Regex to extract and validate YAML frontmatter:

```
^---\r?\n([\s\S]*?)\r?\n---
```

> Note: The `\r?` makes this compatible with both Unix (LF) and Windows (CRLF) line endings.

Required fields (case-sensitive match within the extracted block):
```
^name:\s+.+$
^description:\s+.+$
^version:\s+\d+\.\d+\.\d+$
```

Output format:
```
## Quality Gate: Level 1 (Frontmatter)

| Field       | Status | Value                |
|-------------|--------|----------------------|
| name        | PASS   | my-awesome-skill     |
| description | PASS   | Does something great |
| version     | PASS   | 1.2.0                |

Result: PASS (3/3 required fields present)
```

If any field is missing, result is HARD FAIL. Publishing cannot proceed.

### Level 2: Warning Checklist

Check for recommended (non-blocking) quality signals:

```
## Quality Gate: Level 2 (Warnings)

| Check                        | Status  | Note                                        |
|------------------------------|---------|---------------------------------------------|
| references/ directory exists | {CHECK} | {path found or "Missing: no reference files"}|
| description length >= 20     | {CHECK} | {char count} characters                     |
| description length <= 200    | {CHECK} | {char count} characters                     |
| Has ## Prerequisites section | {CHECK} |                                             |
| Has ## Examples section      | {CHECK} |                                             |
| Has ## Parameters section    | {CHECK} |                                             |

Warnings: {N}/6
```

Status values: `OK` or `WARN`. Warnings do not block publishing but are displayed to the user.

### Level 3: 10-Point Quick Scan

Derived from skill-scorer anti-pattern analysis. Each item scores 0 or 1. Total out of 10.

```
## Quality Gate: Level 3 (Quick Scan)

| #  | Check                        | Score | Detail                              |
|----|------------------------------|-------|-------------------------------------|
| 1  | Valid YAML frontmatter       | {0/1} | Parseable frontmatter block         |
| 2  | Identity lock present        | {0/1} | "You are..." or "Act as..." found   |
| 3  | Prerequisites listed         | {0/1} | ## Prerequisites section exists     |
| 4  | Step 0 (setup/validation)    | {0/1} | First step checks environment       |
| 5  | Parameters documented        | {0/1} | ## Parameters with typed entries     |
| 6  | Examples provided            | {0/1} | ## Examples with concrete usage      |
| 7  | Validation / error handling  | {0/1} | Error cases or edge cases addressed  |
| 8  | Knowledge disclaimer         | {0/1} | Limitations or scope stated          |
| 9  | Self-contained instructions  | {0/1} | No dangling external-only references |
| 10 | Output format specified      | {0/1} | Expected output shape documented     |

Score: {N}/10
```

---

## Platform Adaptation Templates

When publishing to different platforms, files and metadata may need transformation. Apply these rules before uploading.

### ClawHub Adaptation

**Slug generation:**
1. Take skill directory name (e.g., `my-awesome-skill`)
2. Lowercase, replace spaces and underscores with hyphens: `[^a-z0-9-]` -> `-`
3. Collapse consecutive hyphens: `--+` -> `-`
4. Strip leading/trailing hyphens
5. If user provides a prefix (e.g., `cs-`), prepend: `cs-my-awesome-skill`

**Display name from slug:**
- Split on hyphens, capitalize each word: `my-awesome-skill` -> `My Awesome Skill`

**Tags extraction:**
1. First, check frontmatter for `tags:` field (YAML list)
2. If no tags in frontmatter, extract keywords from `description:` (nouns over 4 chars)
3. Always include `"latest"` as the first tag
4. Maximum 5 tags total

### Anthropic Skills Adaptation

**Frontmatter requirements:**
- `license`: must be present; default to `MIT` if missing
- `author`: must be present; use GitHub username from token verification if missing
- `tags`: must be a YAML list; generate from description if missing

**File path mapping:**
```
{SKILL_DIR}/SKILL.md           -> skills/{slug}/SKILL.md
{SKILL_DIR}/references/*.md    -> skills/{slug}/references/*.md
```

### ECC Community Adaptation

**File path mapping:**
```
{SKILL_DIR}/SKILL.md           -> skills/{slug}/SKILL.md
{SKILL_DIR}/references/*.md    -> skills/{slug}/references/*.md
```

**PR body template:**
```markdown
## New Skill: {SKILL_NAME}

**Description:** {description from frontmatter}
**Version:** {version from frontmatter}

### Files
- `skills/{slug}/SKILL.md`
- `skills/{slug}/references/templates.md`
- `skills/{slug}/references/playbooks.md`
- `skills/{slug}/references/fallbacks.md`
- `skills/{slug}/references/runbook.md`

### Quality Gate
- Frontmatter: PASS
- Quick Scan Score: {N}/10

---
Submitted via skill-publish-to-market
```

### skills.sh Adaptation

**File path mapping:**
```
{SKILL_DIR}/SKILL.md           -> {slug}/SKILL.md
{SKILL_DIR}/references/*.md    -> {slug}/references/*.md
{SKILL_DIR}/README.md          -> {slug}/README.md  (if present)
```

**README.md inclusion:** If `{SKILL_DIR}/README.md` exists, include it in the upload. skills.sh uses README.md as the landing page for the skill registry entry.

---

## Output Template

```
## Publishing Results: {SKILL_NAME} v{VERSION}

| Platform | Status | Details |
|----------|--------|---------|
| ClawHub | {STATUS} | {DETAILS} |
| Anthropic Skills | {STATUS} | {DETAILS} |
| ECC Community | {STATUS} | {DETAILS} |
| skills.sh | {STATUS} | {DETAILS} |

Published via skill-publish-to-market
```

Status values: Success / Failed / Skipped
Details: PR URL, slug@version, or error message

---

## Partial Success Report Template

When some platforms succeed and others fail, use this combined report:

```
## Publishing Results: {SKILL_NAME} v{VERSION}

### Succeeded ({SUCCESS_COUNT}/{TOTAL_COUNT})

| Platform | Details |
|----------|---------|
| {PLATFORM} | {slug@version or PR URL} |

### Failed ({FAILURE_COUNT}/{TOTAL_COUNT})

| Platform | Error | Retryable |
|----------|-------|-----------|
| {PLATFORM} | {error message} | {Yes/No} |

### Recommended Actions
- {action 1, e.g., "Retry `anthropic` -- token scopes may need `repo`"}
- {action 2}

To retry failed platforms only:
> publish {SKILL_NAME} --platforms {failed_platform_1},{failed_platform_2}
```

---

## Follow-up Command Templates

After publishing, users may want to check status or retry. These are the curl implementations for follow-up actions.

### Status Check: ClawHub
```bash
curl -s \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  "https://clawhub.ai/api/v1/skills/{SLUG}"
```
Returns: version info, download count, publish date.

### Status Check: GitHub PR
```bash
curl -s \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/{OWNER}/{REPO}/pulls/{PR_NUMBER}"
```
Extract: `.state` (open/closed/merged), `.mergeable`, `.merged_at`

### Retry Failed Platform
Re-run the publish sequence for a single platform using the same tokens and skill directory. The retry command is identical to the original publish curl for that platform.

### Publish (New Version)
Same as initial publish, but with an incremented version. Bump `version:` in SKILL.md frontmatter before re-running.

---

## Batch Progress Template

When publishing multiple skills, show incremental progress:

```
## Batch Publishing Progress

| # | Skill | ClawHub | Anthropic | ECC | skills.sh |
|---|-------|---------|-----------|-----|-----------|
| 1 | {name} | OK | OK | OK | OK |
| 2 | {name} | OK | FAIL | OK | -- |
| 3 | {name} | ... | ... | ... | ... |

Progress: {completed}/{total} skills
Elapsed: {time}s
```

Individual cell values: `OK`, `FAIL`, `SKIP`, `--` (pending), `...` (in progress)

---
name: flyai-commit-lint
description: Enforce conventional commit messages with semantic validation, scope checking, and automated fix suggestions for git workflows.
version: 1.0.0
author: dingtom336-gif
license: MIT
tags:
  - git
  - commit
  - linting
  - workflow
  - automation
allowedTools:
  - Bash
  - Read
  - Grep
---

# FlyAI Commit Lint

Enforce conventional commit messages across your team with semantic validation, scope verification, and automated fix suggestions.

## When to use

Activate this skill when:
- A user runs git commit and the message does not follow conventional commit format
- A user asks to review or fix commit messages in a branch
- Pre-commit hooks need commit message validation
- CI pipelines require commit format enforcement

## Commit Format

All commits must follow the pattern: type(scope): subject

### Allowed Types

| Type | Description |
|------|-------------|
| feat | A new feature |
| fix | A bug fix |
| docs | Documentation changes |
| style | Formatting, missing semicolons, etc. |
| refactor | Code change that neither fixes a bug nor adds a feature |
| perf | Performance improvement |
| test | Adding or updating tests |
| chore | Maintenance tasks |
| ci | CI/CD configuration changes |
| build | Build system or dependency changes |

### Scope Rules

- Scope is optional but recommended
- Must be lowercase kebab-case
- Should match a module, component, or directory name in the project
- Examples: auth, api, ui, database, ci

### Subject Rules

- Use imperative mood: "add feature" not "added feature"
- No period at the end
- Maximum 72 characters
- Start with lowercase

## Validation Process

1. Parse the commit message into type, scope, subject, body, and footer
2. Validate type against the allowed list
3. Check scope format if present
4. Verify subject follows all rules
5. Check total first line length does not exceed 72 characters
6. If body is present, ensure blank line separator exists

## Auto-Fix Suggestions

When a commit message fails validation, suggest fixes:

- Wrong type: suggest the closest matching type
- Uppercase subject: auto-lowercase the first character
- Period at end: remove trailing period
- Past tense: suggest imperative form (added -> add, fixed -> fix)
- Missing type: infer from changed files (test files -> test, docs -> docs)

## Integration

Works with:
- Git hooks (pre-commit, commit-msg)
- GitHub Actions CI checks
- Local development workflow
- Branch history cleanup before merge

## Examples

Good:
- feat(auth): add OAuth2 login flow
- fix(api): handle null response from upstream
- docs: update API reference for v2 endpoints
- refactor(database): extract connection pooling logic

Bad:
- Added new feature (missing type)
- feat: Add OAuth2. (uppercase, period)
- fix(API): Fixed the bug (uppercase scope, past tense)

---
name: viral-video-replicator
description: "视频逆向复刻 — 分析参考视频(FFmpeg帧提取+Vision LLM) + 生成复刻Seedance 2.0 Prompt + 4种素材替换模式。支持单个和批量。Use when: '复刻这个视频', '分析爆款视频', 'replicate this video', '视频逆向', '反编译视频', '批量分析视频'. Do NOT use for creating from scratch — use fashion-video-creator instead."
version: "1.1.0"
compatibility: "Claude Code, Claude.ai (with local FFmpeg), and all SKILL.md-compatible agents"
dependencies:
  - ffmpeg
  - ffprobe
---

# Skill: viral-video-replicator

## Overview

Reverse-engineer reference videos (e.g., competitor viral content) into replicable Seedance 2.0 prompts. The pipeline: FFmpeg frame extraction -> contact sheet grids -> audio extraction + ASR transcription -> Vision LLM structured analysis -> Seedance prompt assembly with optional material replacement (face/body/clothing). Supports single and batch modes.

## When to Activate

User query contains any of:
- "视频复刻", "视频逆向", "反编译视频", "复刻爆款"
- "分析这个视频", "replicate this video", "video analysis"
- "批量分析", "批量复刻"
- "这个视频怎么拍的", "帮我分析一下这个爆款", "我想拍一个类似的视频"
- "reverse engineer this video", "analyze this fashion video"

Do NOT activate for:
- Creating fashion videos from scratch (no reference video) -> use `fashion-video-creator`
- "帮我做个穿搭视频", "生成模特图" -> use `fashion-video-creator`
- Pure video editing / trimming -> not applicable
- Non-fashion video analysis -> not applicable

## Prerequisites

**Local tools (REQUIRED):**
```bash
# macOS
brew install ffmpeg

# Linux
apt install ffmpeg

# Verify
ffmpeg -version && ffprobe -version
```

**Cloud APIs (collected via clarification):**
```
REQUIRED: ARK_API_KEY + ARK_VISION_MODEL (Vision LLM for frame analysis)
CONDITIONAL: ASR_ACCESS_TOKEN (if video has dialogue)
CONDITIONAL: TOS credentials (if ASR is needed — audio transfers through TOS)
```

## Clarification Flow

### Phase 1: API Key Acquisition

Ask IN ORDER. Use plain language — explain WHY each service is needed.

**Q1: Vision Analysis (REQUIRED)**
> "分析视频内容需要一个能'看懂图片'的 AI 模型。
> 它会看视频的截图，识别出人物长相、服装细节、场景布局、动作时间轴。
> 你有火山方舟的账号和 API Key 吗？还需要视觉模型的ID。"

If no API key -> **STOP.** Guide user to 火山方舟. Do NOT proceed.

**Q2: Speech Transcription (CONDITIONAL)**
> "参考视频里的人有说话吗？
> 如果有对话，需要用语音转文字来提取台词 — 这样复刻出的视频才能有完整的对白内容。
> 没有对话的纯画面视频可以跳过这步。"

If yes -> ask for ASR_ACCESS_TOKEN.

**Q3: Audio Storage (CONDITIONAL — only if Q2 = yes)**
> "语音转文字需要通过云存储传输音频文件。
> 需要火山引擎对象存储(TOS)的 4 个信息：Access Key, Secret Key, Bucket, Region。"

If user has ASR but no TOS -> warn: "没有 TOS 则 ASR 无法工作，等同于没有语音转录。"

### Phase 2: Mandatory Recommendations

MUST show. Each item has WHY explanation:

```
============================================================
API Configuration — Mandatory Recommendations
============================================================

[REQUIRED] Vision model: doubao-seed-1-6-vision-250815 or newer
  WHY: Older models cannot distinguish clothing fabric textures
  (acetate vs chiffon), stitching details (overlocked vs raw edge),
  or fit nuances (slim vs A-line). Analysis quality drops ~60%.

[REQUIRED] If video has dialogue: configure BOTH ASR + TOS
  WHY: Without ASR, all spoken content is lost. The generated prompt
  will only contain visual descriptions. Video fidelity drops from
  ~90% to ~50% because dialogue drives 40%+ of viewer engagement.
  TOS is the audio transfer pipeline — no TOS means no ASR.

[REQUIRED] Video resolution: 720p or higher
  WHY: Frames are extracted at 360x640 thumbnails. Source below 480p
  means thumbnails are upscaled garbage — clothing patterns and
  textures become unrecognizable blobs.

[RECOMMENDED] Exact mode for same-category replacement
  WHY: "exact" does nested structured analysis (10 fields with typed
  subobjects) — precision matters when replacing one dress with another.
  "rewrite" does flat analysis (10 string fields) — better for
  extracting viral logic across different product categories.
============================================================
```

### Phase 3: Mode Selection

> "你要分析几个视频？单个还是批量？"

**Q5: Replicate Mode** (per video if batch)
> "你想怎么复刻？
> - **精确复刻**: 逐帧分析每个细节，尽可能1:1还原
> - **提取改写**: 提取爆款节奏和逻辑，用新方式重新演绎"

**Q6: Material Replacement** (per video if batch)
> "要替换视频中的哪些元素？
> - 不换（纯复刻）
> - 换人脸/身材（上传模特参考图）
> - 换衣服（上传商品图）
> - 都换（上传模特图 + 商品图）"

### Batch-Specific Recommendations

```
============================================================
Batch Mode — Additional Recommendations
============================================================

[REQUIRED] ALL videos should be 720p+
  WHY: One low-res video doesn't just fail for itself — it wastes
  API costs on a Vision LLM call that returns unusable analysis.

[RECOMMENDED] Pre-sort by replicate mode
  WHY: exact mode takes 2-3 min/video (nested analysis), rewrite
  takes 1-2 min/video (flat analysis). Grouping avoids context switches.

[WARNING] Each video runs the FULL pipeline independently.
  N videos = approximately N * 2-3 minutes. Plan accordingly.
============================================================
```

## Four Replacement Modes

| Mode | What User Uploads | @image Tags in Prompt | What Gets Replaced |
|------|------------------|----------------------|-------------------|
| clone | Nothing | None (pure text) | Nothing — exact replication |
| face_swap | Face/body reference | @image1 = face ref | Person replaced, clothing preserved |
| outfit_swap | Garment product image | @image1 = garment | Clothing replaced, person preserved |
| full_swap | Garment + face reference | @image1 = garment, @image2 = face ref | Both replaced |

Mode auto-determination:
```
has_person_ref AND has_garment_ref -> full_swap
has_garment_ref only -> outfit_swap
has_person_ref only -> face_swap
neither -> clone
```

## Core Workflow

### Step 0: Environment Check (mandatory, never skip)

```bash
ffmpeg -version && ffprobe -version
```

- Returns version -> proceed to Step 1
- `command not found` -> guide install (brew/apt/choco). Still fails after install ->
  **Soft fallback:** Ask user: "FFmpeg 不可用，你能手动提供视频截图和音频文件吗？"
  If user provides frames manually -> skip FFmpeg steps, proceed from Step 4 (Vision analysis) with user-provided images.
  **Quality warning (MUST show to user):** "手动截图模式下分析质量会显著降低：无精确时间戳标注、无均匀3fps采样、帧数可能不足导致动作时间轴不准确。建议安装 FFmpeg 以获得最佳效果。"
  If user cannot provide frames -> **STOP.** FFmpeg is required for automated extraction.

### Step 0b: Verify API Key (before reaching Step 4)

Validate ARK_API_KEY early to avoid wasting FFmpeg processing time on an invalid key:

**If bash/Python available:**
```python
resp = httpx.get(f"{ARK_API_BASE}/api/v3/models",
                 headers={"Authorization": f"Bearer {ARK_API_KEY}"}, timeout=10)
```
- 200 -> proceed
- 401/403 -> **STOP.** Key invalid. Fix before continuing.

**If no code execution:** Trust user-provided key, validate on first Vision API call.

### Single Mode

```
Step 1: Collect API keys + mode + replacement materials
Step 2: Extract frame grids (3fps) + extract audio — PARALLEL via asyncio.gather()
        (Both are FFmpeg subprocesses launched concurrently in Python, not LLM-level parallelism)
        Read references/frame-extraction.md for FFmpeg specs
Step 3: Upload audio to TOS -> ASR transcription
        Read references/asr-pipeline.md for protocol
Step 4: Vision LLM analysis (grids + transcript -> structured JSON)
        Read references/vision-analysis.md for exact vs rewrite schemas
Step 5: Determine replacement mode from uploaded materials
Step 6: Assemble Seedance 2.0 prompt
        Read references/reverse-prompt.md for 4-mode assembly
Step 7: Generate mode-specific SOP
Step 8: Validate output (see below)
Step 9: Return: prompt + analysis + transcript + SOP + replacement summary
```

### Batch Mode

```
Step 0: Verify FFmpeg
Step 1: Collect API keys + video count + per-video configs
Step 2: For each video (sequential):
  a. Extract frame grids + audio (parallel)
  b. TOS upload -> ASR transcription
  c. Vision LLM analysis
  d. Determine replacement mode
  e. Assemble prompt
  f. Generate SOP
  g. Validate this video's output
  h. Mark: completed / failed
Step 3: Return all results with progress summary

Progress: queued -> processing -> completed/failed
Partial success: batch completes even if some videos fail.
```

### Output Validation (mandatory, never skip)

Before delivering results, verify ALL:

- [ ] Analysis JSON is valid and contains all required fields?
- [ ] Prompt correctly uses @image tags matching the replacement mode?
- [ ] If clone mode: prompt has NO @image references (pure text)?
- [ ] If outfit_swap/full_swap: prompt includes "Do not alter clothing pattern, color, texture or style"?
- [ ] If has_speech: dialogue content is present in prompt (not empty)?
- [ ] SOP upload instructions match the number of images for this mode?
- [ ] Replacement summary correctly lists what was preserved vs replaced?

**Any NO -> fix before delivering. Do NOT send unvalidated output.**

## Error Handling

| Failure | Detection | Action |
|---------|-----------|--------|
| FFmpeg not installed | `command not found` | **STOP.** Provide install command. Do NOT proceed. |
| No API key | ARK_API_KEY empty | **STOP.** Guide user to 火山方舟. Do NOT proceed. |
| Vision model error | 4xx/5xx from API | Report error with model ID used. Suggest checking model availability. |
| Vision returns invalid JSON | JSON parse fails | Retry once with same grids. Still fails -> report raw response for debugging. |
| Frame extraction fails | FFmpeg non-zero exit | Check video format. Try re-encoding. Report if still fails. |
| No audio track | extract_audio returns None | Skip ASR. Proceed with visual-only analysis. Note in output: "No audio detected." |
| TOS upload fails | Upload exception after 2 retries | Skip ASR. Proceed visual-only. Warn: "Audio transcription unavailable — dialogue will be missing." |
| ASR timeout | No result after 120s | Skip transcript. Proceed visual-only. Warn: "Speech transcription timed out." |
| ASR silent audio | Status 20000003 | Normal — video has no speech. Proceed with visual-only. |
| Video too large | >200MB | Reject immediately. Ask user to compress or trim. |
| Batch video fails | Exception during pipeline | Mark failed with error. Continue remaining. Report partial results. |

### Degraded Modes (graceful degradation chain)

| Failure Point | Degraded Mode | What User Still Gets | Quality Impact |
|---------------|---------------|---------------------|---------------|
| ASR fails (TOS/timeout) | Visual-only analysis | Prompt with visual descriptions, no dialogue | ~50% fidelity — all spoken content lost |
| Vision exact mode fails | Auto-retry with rewrite mode | Flat analysis (less precise) | ~70% fidelity — loses nested structure (clothing/scene subfields) |
| Vision rewrite also fails | Return raw materials | Frame grids + transcript for manual analysis | ~20% — no automated analysis, user must write prompt manually |
| Seedance prompt assembly fails | Return analysis only | Analysis JSON + transcript | ~30% — user has data but no ready-to-use prompt |
| FFmpeg unavailable (user provides screenshots) | Manual frame mode | Analysis from user-provided images | ~40% — no timestamps, uneven sampling, incomplete frame coverage |

Always prefer delivering partial results over delivering nothing. Every degraded output **MUST** clearly state: (1) what is missing, (2) why, and (3) the estimated quality impact.

See [references/fallbacks.md](references/fallbacks.md) for detailed recovery procedures per failure case.

## Usage Example

**Input:** "帮我复刻这个爆款视频，换成我的衣服" + uploaded video (15s, 720p) + uploaded garment image

**Resolved:** mode=exact, replacement=outfit_swap (garment_ref provided, no face_ref)

**Output 1 — Structured Analysis:**
```json
{
  "person": {
    "gender": "female", "age_range": "22-26",
    "face": "鹅蛋脸，大眼睛，双眼皮",
    "skin_tone": "白皙", "hair": "黑色长直发，中分，自然垂落",
    "build": "纤细高挑", "makeup": "淡妆，裸色唇彩"
  },
  "clothing": {
    "type": "V领碎花连衣裙", "color": "奶油白底+粉色碎花",
    "material_look": "轻薄飘逸雪纺", "neckline": "V领",
    "fit": "A字收腰", "length": "及膝",
    "details": "腰部抽绳系带，裙摆荷叶边"
  },
  "scene": {"location": "现代公寓客厅", "lighting_source": "右侧落地窗自然光"},
  "actions": "0-2s: 正面微笑打招呼；2-5s: 右手拉起裙摆展示面料；5-8s: 小幅转身展示裙摆飘动；8-12s: 右手翻开裙子内侧展示车线；12-15s: 右手捏腰部展示松紧",
  "dialogue": "姐妹们你们快看...（右手拉起裙摆）这个面料是醋酸缎面的...滑滑的凉凉的..."
}
```

**Output 2 — Seedance Prompt (outfit_swap):**
```
一位鹅蛋脸、白皙肤色、黑色长直发中分自然垂落、纤细高挑身材、淡妆的年轻女性，穿着@图片1中的服装。在现代公寓客厅中，右侧落地窗自然光。她的动作：0-2s: 正面微笑打招呼；2-5s: 右手拉起衣角展示面料...对着镜头说：「姐妹们你们快看...这个面料...滑滑的凉凉的...你们猜多少钱？不到两百！超显腿长，闭眼入。」语气自然亲切，像在跟闺蜜视频通话。Do not alter clothing pattern, color, texture or style. 手持vlog镜头感，竖屏9:16。
```

**Output 3 — Transcript:** "姐妹们你们快看...这个面料是醋酸缎面的..."

**Output 4 — SOP:** outfit_swap mode, 1 image upload (@图片1=garment)

**Output 5 — Replacement Summary:** garment_replaced=true, original_preserved=[face, body, scene, actions, dialogue, camera]

## Domain Knowledge Role Declaration

> The reference files contain FFmpeg specs, ASR protocols, Vision prompts, and prompt assembly templates.
> Their role is to **assist pipeline execution** — providing exact API formats, analysis schemas, and assembly rules.
> They do NOT replace the execution workflow. Never output reference content directly as the final answer.
> Always execute: extract frames -> transcribe -> analyze -> assemble -> validate -> deliver.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/frame-extraction.md](references/frame-extraction.md) | FFmpeg filter chain, grid stitching, audio extraction specs | Step 2: extracting frames and audio |
| [references/asr-pipeline.md](references/asr-pipeline.md) | TOS upload protocol, Seed-ASR-2.0 submit/poll API | Step 3: transcribing audio |
| [references/vision-analysis.md](references/vision-analysis.md) | Vision LLM prompts for exact and rewrite modes, output schemas | Step 4: analyzing video |
| [references/reverse-prompt.md](references/reverse-prompt.md) | 4-mode prompt assembly, clothing generalization map, SOP templates | Step 6-7: building prompt and SOP |
| [references/fallbacks.md](references/fallbacks.md) | 8 failure cases with recovery procedures and degradation chain | On any error during Steps 2-8 |

FILE:README.md
# viral-video-replicator

爆款视频复刻 — 逆向分析参考视频，生成可复刻的 Seedance 2.0 提示词

## 概述

从已有的参考视频（如竞品爆款、热门带货短视频）中逆向提取所有参数，生成可直接使用的 Seedance 2.0 复刻提示词：

1. **帧提取**：FFmpeg 3fps 采样 → 带时间戳的联系表网格图
2. **语音转录**：Seed-ASR-2.0 提取视频中的对话/旁白
3. **视觉分析**：Vision LLM 结构化分析（人物/服装/场景/动作/镜头/音频）
4. **Prompt 生成**：组装 Seedance 2.0 复刻提示词，支持 4 种素材替换模式
5. **操作手册**：即梦平台的逐步操作指引

支持单个和批量模式。每个视频独立选择复刻模式和替换素材。

## 四种替换模式

| 模式 | 上传素材 | 效果 |
|------|---------|------|
| 纯复刻 (clone) | 无 | 100% 文字描述还原，不引用任何图片 |
| 换人脸 (face_swap) | 模特参考图 | 替换人物，保留原服装 |
| 换衣服 (outfit_swap) | 衣服商品图 | 替换服装，保留原人物 |
| 全换 (full_swap) | 商品图 + 模特图 | 同时替换人物和服装 |

## 快速开始

### 安装

```bash
# Claude Code 用户
claude install-skill https://github.com/dingtom336-gif/outfit-video/tree/main/skills/viral-video-replicator
```

### 前置条件

- **本地工具**：FFmpeg + ffprobe（`brew install ffmpeg`）
- **云端 API**：火山方舟 API Key + 视觉模型（doubao-seed-1-6-vision-250815）
- **可选**：Seed-ASR-2.0 访问令牌 + TOS 对象存储密钥（视频有对话时需要）

### 使用

对 Claude 说：
- "帮我复刻这个爆款视频"
- "分析一下这个视频是怎么拍的"
- "把这个视频的衣服换成我的商品图"
- "批量分析这 3 个竞品视频"

## 降级模式

当部分服务不可用时，技能不会直接停止，而是降级运行并明确告知质量损失：

| 故障点 | 降级方式 | 质量影响 |
|--------|---------|---------|
| ASR 失败 | 仅视觉分析 | ~50% — 丢失全部对话内容 |
| Vision 精确模式失败 | 自动切换改写模式 | ~70% — 分析精度降低 |
| Vision 全部失败 | 返回原始帧图+转录 | ~20% — 需手动分析 |
| FFmpeg 不可用 | 用户手动提供截图 | ~40% — 无时间戳和均匀采样 |

## 文件结构

```
viral-video-replicator/
├── README.md                          # 本文件
├── SKILL.md                           # 核心技能逻辑
└── references/
    ├── frame-extraction.md            # FFmpeg 帧提取规范
    ├── asr-pipeline.md                # TOS 上传 + Seed-ASR-2.0 转录协议
    ├── vision-analysis.md             # Vision LLM 分析 schema（精确/改写两种模式）
    ├── reverse-prompt.md              # 4 种替换模式的 Prompt 组装规则
    └── fallbacks.md                   # 8 种故障的恢复流程
```

## 兼容性

Claude Code, Claude.ai（需本地 FFmpeg）, 以及所有兼容 SKILL.md 的 Agent。

## 关联技能

- **[fashion-video-creator](/fashion-video-creator/)** — 没有参考视频？用它从零创建穿搭视频素材

## 许可证

MIT

---

# viral-video-replicator

Viral Video Replicator — Reverse-engineer reference videos into replicable Seedance 2.0 prompts

## Overview

Extract all parameters from existing reference videos (e.g., competitor viral content, trending fashion shorts) and generate ready-to-use Seedance 2.0 replication prompts:

1. **Frame Extraction**: FFmpeg 3fps sampling → timestamped contact sheet grids
2. **Speech Transcription**: Seed-ASR-2.0 extracts dialogue/voiceover
3. **Visual Analysis**: Vision LLM structured analysis (person/clothing/scene/actions/camera/audio)
4. **Prompt Generation**: Assemble Seedance 2.0 replication prompt with 4 material replacement modes
5. **Operator SOP**: Step-by-step guide for the Jimeng (即梦) platform

Supports single and batch modes. Each video can independently choose its replication mode and replacement materials.

## Four Replacement Modes

| Mode | Upload | Effect |
|------|--------|--------|
| Clone | Nothing | 100% text-based replication, no image references |
| Face Swap | Model reference image | Replace person, keep original clothing |
| Outfit Swap | Garment product image | Replace clothing, keep original person |
| Full Swap | Garment + model images | Replace both person and clothing |

## Quick Start

### Install

```bash
# Claude Code users
claude install-skill https://github.com/dingtom336-gif/outfit-video/tree/main/skills/viral-video-replicator
```

### Prerequisites

- **Local tools**: FFmpeg + ffprobe (`brew install ffmpeg`)
- **Cloud APIs**: Volcano Engine API Key + Vision model (doubao-seed-1-6-vision-250815)
- **Optional**: Seed-ASR-2.0 access token + TOS storage credentials (needed when video has dialogue)

### Usage

Say to Claude:
- "Replicate this viral video"
- "Analyze how this video was made"
- "Replace the clothing in this video with my product image"
- "Batch analyze these 3 competitor videos"

## Degraded Modes

When some services are unavailable, the skill degrades gracefully instead of stopping, with clear quality impact warnings:

| Failure Point | Degraded Mode | Quality Impact |
|---------------|---------------|---------------|
| ASR fails | Visual-only analysis | ~50% — all dialogue content lost |
| Vision exact mode fails | Auto-switch to rewrite mode | ~70% — reduced analysis precision |
| Vision fully fails | Return raw frames + transcript | ~20% — manual analysis required |
| FFmpeg unavailable | User provides screenshots manually | ~40% — no timestamps or uniform sampling |

## File Structure

```
viral-video-replicator/
├── README.md                          # This file
├── SKILL.md                           # Core skill logic
└── references/
    ├── frame-extraction.md            # FFmpeg frame extraction specs
    ├── asr-pipeline.md                # TOS upload + Seed-ASR-2.0 transcription protocol
    ├── vision-analysis.md             # Vision LLM analysis schema (exact + rewrite modes)
    ├── reverse-prompt.md              # 4-mode prompt assembly rules
    └── fallbacks.md                   # 8 failure recovery procedures
```

## Compatibility

Claude Code, Claude.ai (with local FFmpeg), and all SKILL.md-compatible agents.

## Related Skills

- **[fashion-video-creator](/fashion-video-creator/)** — No reference video? Use this to create fashion video assets from scratch

## License

MIT

FILE:references/asr-pipeline.md
# ASR Transcription Pipeline

> **Role:** Defines TOS upload protocol and Seed-ASR-2.0 submit/poll API for speech-to-text.
> Load at: Step 3 (transcribing audio). Skip entirely if video has no speech.
> It does NOT replace execution — always run the actual ASR pipeline, never fabricate transcripts.

## TOS Audio Upload

### SDK
- Uses `tos` Python SDK (TosClientV2)
- Install: `pip install tos`

### Connection
```python
client = TosClientV2(
  ak=TOS_ACCESS_KEY,
  sk=TOS_SECRET_KEY,
  endpoint=f"tos-{TOS_REGION}.volces.com",
  region=TOS_REGION,
)
```

### Upload
- Key: `outfit-video/asr/{uuid}.wav`
- Content-Type: audio/wav
- Retry: up to 2 times with 1s delay
- Runs in thread pool (put_object is blocking)

### Presigned URL
- Method: GET
- Expires: 3600 seconds (1 hour)
- Returns signed URL for ASR access

## Seed-ASR-2.0 Transcription

### Base URL
`https://openspeech.bytedance.com/api/v3/auc/bigmodel`

### Submit Request
```
POST /submit
Headers:
  Content-Type: application/json
  x-api-key: {ASR_ACCESS_TOKEN}
  X-Api-Resource-Id: volc.seedasr.auc
  X-Api-Request-Id: {uuid}
  X-Api-Sequence: -1
Body:
  user.uid: "outfit-video"
  audio.url: {presigned_tos_url}
  audio.format: "wav"
  request:
    model_name: "bigmodel"
    enable_itn: true
    enable_punc: true
    enable_ddc: true
    show_utterances: true
    enable_speaker_info: true
    enable_emotion_detection: true
    enable_gender_detection: true
```

### Poll Request
```
POST /query
Headers: (same as submit, WITHOUT X-Api-Sequence)
Body: {}
```

### Status Codes (X-Api-Status-Code header)
- 20000000: completed -> extract result.text
- 20000001: processing, keep polling
- 20000002: processing, keep polling
- 20000003: silent audio, no transcript

### Polling Parameters
- Max wait: 120 seconds
- Poll interval: 3 seconds
- Network retry: exponential backoff, max 3 retries
- Backoff formula: `interval * 2^(retry-1)`

FILE:references/fallbacks.md
# Fallbacks — viral-video-replicator

> **Role:** Defines recovery procedures for every failure case in the video analysis pipeline.
> Load at: On any error during Steps 2-8. Each case has trigger condition, recovery steps, and user message.
> It does NOT replace execution — these are error recovery paths, not alternative data sources.

## Case 0: FFmpeg Not Installed

**Trigger:** `ffmpeg -version` returns `command not found`.

```
Recovery:
1. Output install command for detected OS:
   macOS: brew install ffmpeg
   Linux: apt install ffmpeg
   Windows: choco install ffmpeg
2. Ask user to run install and retry.
3. If still fails -> STOP. Tell user: "FFmpeg is required. Please install manually."
4. Do NOT proceed without FFmpeg. Do NOT fabricate frame analysis.
```

## Case 1: No API Key

**Trigger:** ARK_API_KEY is empty, missing, or returns 401/403.

```
Recovery:
1. STOP immediately.
2. Guide user: "请在火山方舟控制台获取 API Key: https://console.volcengine.com/ark"
3. Do NOT proceed. Do NOT substitute with training data.
```

## Case 2: Vision LLM Fails (Exact Mode)

**Trigger:** Vision API returns 4xx/5xx or invalid JSON in exact mode.

```
Recovery:
1. Retry once with same grids and prompt.
2. If still fails -> auto-downgrade to REWRITE mode (flat analysis).
   Warn: "Exact analysis failed. Using simplified analysis mode — results will be less precise."
3. If rewrite also fails -> return raw materials:
   - Frame grid images (base64)
   - Transcript (if available)
   Warn: "Automated analysis failed. Returning raw frame grids and transcript for manual analysis."
4. Never fabricate analysis data.
```

## Case 3: ASR Transcription Fails

**Trigger:** ASR returns error status, times out (>120s), or network error after 3 retries.

```
Recovery:
1. Skip transcript entirely.
2. Proceed with visual-only analysis.
3. Mark output: "Audio transcription unavailable. Generated prompt contains visual descriptions only — dialogue content is missing."
4. In the Vision LLM prompt, use the "no transcript" variant (see vision-analysis.md).
```

## Case 4: TOS Upload Fails

**Trigger:** TOS SDK throws exception after 2 retries, or credentials invalid.

```
Recovery:
1. TOS failure = ASR failure (audio cannot be transferred).
2. Apply Case 3 recovery (skip ASR, visual-only).
3. Additional warn: "Cloud storage upload failed — speech transcription skipped."
```

## Case 5: Video Too Large

**Trigger:** Video file exceeds 200MB.

```
Recovery:
1. Reject immediately (do NOT attempt processing).
2. Tell user: "Video exceeds 200MB limit. Please compress (e.g., ffmpeg -i input.mp4 -crf 28 output.mp4) or trim to under 200MB."
```

## Case 6: No Audio Track

**Trigger:** extract_audio() returns None or <5000 bytes.

```
Recovery:
1. This is NORMAL, not an error. Many fashion videos are music-only or silent.
2. Skip ASR pipeline entirely.
3. Proceed with visual-only analysis.
4. Note in output: "No speech detected in video. Analysis is visual-only."
```

## Case 7: Frame Extraction Fails

**Trigger:** FFmpeg returns non-zero exit code during frame extraction.

```
Recovery:
1. Check video format — try re-encoding first:
   ffmpeg -i input.mp4 -c:v libx264 -crf 23 re-encoded.mp4
2. Retry frame extraction on re-encoded video.
3. If still fails -> report error with FFmpeg stderr output for debugging.
4. Do NOT proceed without frames — they are required for Vision analysis.
```

## Case 8: Prompt Assembly Fails

**Trigger:** Exception during build_reverse_prompt() or mode determination.

```
Recovery:
1. Return the analysis JSON + transcript as standalone outputs.
2. Warn: "Prompt assembly failed. Returning raw analysis — you can manually compose the Seedance prompt from these results."
3. Include the 4-mode prompt templates from reverse-prompt.md as a reference for manual composition.
```

## Universal Fallback Principle

Every error path must end with ONE of:
- A clear error message explaining what failed and how to fix it
- A degraded output with explicit warning about what is missing
- A STOP with install/setup guidance

**NEVER:** silently swallow errors, fabricate data, or deliver empty results without explanation.

FILE:references/frame-extraction.md
# FFmpeg Frame Extraction

> **Role:** Defines FFmpeg commands and parameters for video frame extraction and audio extraction.
> Load at: Step 2 (extracting frames and audio).
> It does NOT replace execution — these are command specs to be executed, not cached results.

## check_ffmpeg()

Verifies ffmpeg and ffprobe availability. Returns dict with version info.

## extract_frame_grids()

### Parameters
- video_path: str
- fps: 3.0 (frames per second)
- grid_cols: 4
- grid_rows: 3
- max_grids: 3
- thumb_w: 360
- thumb_h: 640

### Pipeline
1. Get video duration via ffprobe
2. FFmpeg extraction with filter chain:
   ```
   fps=3,scale=360:640:force_original_aspect_ratio=decrease:flags=lanczos,
   pad=360:640:(ow-iw)/2:(oh-ih)/2:color=black
   ```
3. Output: JPEG frames at quality 5, VFR mode
4. Cap total frames: 4 * 3 * 3 = 36 max

### Grid Stitching
- PIL Image.new(RGB, 1440x1920, black)
- Paste each frame at (col * 360, row * 640)
- Draw timestamp label: yellow text on black rect at (x+6, y+6)
- Save as JPEG quality=85, encode base64

### Output
- list[str]: base64-encoded JPEG grid images
- float: video duration in seconds
- int: total frame count

### Example
10s video at 3fps = ~30 frames = 3 grids of 12 frames each

## extract_audio()

### Pipeline
1. FFmpeg: `-vn -acodec pcm_s16le -ar 16000 -ac 1`
2. Output: 16kHz mono WAV bytes
3. Returns None if no audio or < 5000 bytes (silence)

FILE:references/reverse-prompt.md
# Reverse Prompt Assembly

> **Role:** Defines the 4-mode prompt assembly logic for converting Vision analysis into Seedance 2.0 prompts.
> Load at: Step 6-7 (building prompt and SOP). Uses the analysis JSON from Step 4 as input.
> It does NOT replace execution — these are assembly rules, not prebuilt prompts.

## Helper Functions

### _get_gender_info(analysis)
Extract gender, gender_word (男性/女性), pronoun (他/她) from analysis.

### _build_person_desc(person)
Assemble: age_range + face + skin_tone + hair + build + makeup, joined by ，

### _build_clothing_desc(clothing)
Assemble: color + material_look + type, then fit, sleeve, neckline, length, pattern, details, accessories

### _build_scene_desc(scene)
Assemble: location + background_objects + floor + wall + lighting_source + color_temperature + overall_tone

### _build_camera_desc(camera)
Assemble: movement_type + orientation + timeline. Default: "手持vlog镜头感，竖屏9:16"

### _build_audio_desc(audio)
Assemble: speech info + background + music

## Clothing Generalization Map (for outfit/full swap)

Used to replace clothing-specific words with generic equivalents:

| Specific | Generic |
|----------|---------|
| 裙摆 | 衣角 |
| 裙子 | 衣服 |
| 裙装 | 服装 |
| 连衣裙 | 衣服 |
| 半身裙 | 下装 |
| 短裙 | 下装 |
| 裤脚 | 衣角 |
| 裤腿 | 下装 |
| 醋酸缎面 | 面料 |
| 雪纺 | 面料 |
| 丝绸 | 面料 |
| 蕾丝 | 面料 |
| 牛仔 | 面料 |
| 针织 | 面料 |
| 碎花 | 图案 |
| 条纹 | 图案 |
| 格纹 | 图案 |
| A字 | 版型 |
| 修身 | 版型 |
| 宽松 | 版型 |
| 伞摆 | 下摆 |
| 鱼尾 | 下摆 |

## Four Prompt Builders

### 1. clone — Pure text, no @image refs
```
一位{person_desc}的年轻{gender_word}，穿着{clothing_desc}。
{scene_desc}。
{pronoun}的动作：{actions}。
对着镜头说：「{dialogue}」{speech_style}。
镜头：{camera_desc}。
音频：{audio_desc}。
```

### 2. face_swap — @图片1=face ref, keep original clothing
```
一位面容和身材参考@图片1的年轻{gender_word}{hair/makeup}，穿着{clothing_desc}。
{style_transfer if stylized}
{scene}, {actions}, {dialogue}, {camera}, {audio}
```

### 3. outfit_swap — @图片1=garment, keep original person
```
一位{person_desc}的年轻{gender_word}，穿着@图片1中的服装。
{scene}, {generalized_actions}, {generalized_dialogue}
Do not alter clothing pattern, color, texture or style.
{camera}, {audio}
```

### 4. full_swap — @图片1=garment + @图片2=face ref
```
一位{model_ref}年轻{gender_word}穿着@图片1中的服装，{scene}。
{style_transfer if stylized}
{generalized_actions}, {generalized_dialogue}
Do not alter clothing pattern, color, texture or style.
{camera}, {audio}
```

## Mode Determination

```python
has_person = has_face_ref or has_body_ref
if has_garment and has_person: "full_swap"
elif has_garment: "outfit_swap"
elif has_person: "face_swap"
else: "clone"
```

## SOP Generation

Mode-specific upload instructions:
- clone: 0 images, text-only generation
- face_swap: 1 image (@图片1=人脸参考)
- outfit_swap: 1 image (@图片1=衣服商品图)
- full_swap: 2 images (@图片1=衣服, @图片2=人脸参考)

## Replacement Summary

Tracks what was replaced vs preserved:
```python
{
  mode: "full_swap",
  face_replaced: true,
  body_replaced: false,
  garment_replaced: true,
  original_preserved: ["body", "scene", "actions", "dialogue", "camera"]
}
```

FILE:references/vision-analysis.md
# Vision LLM Analysis

> **Role:** Defines Vision LLM system/user prompts and output schemas for video analysis (exact + rewrite modes).
> Load at: Step 4 (analyzing video frames). The prompts here are sent to the Vision API, not used as direct answers.
> It does NOT replace execution — always call the Vision API with frame grids, never fabricate analysis from training data.

## Two Analysis Modes

### 1. Exact Mode (reverse_video.py) — Nested structured analysis

**System Prompt:**
> 你是视频逆向分析专家。你的任务是从视频关键帧中提取能够 100% 复制该视频的所有参数。你的输出将被直接用于 Seedance 2.0 视频生成提示词。精确度是唯一标准——不要概括、不要美化、不要推断"应该是什么"，只描述"实际看到了什么"。

**10-field output schema:**
1. person: {gender, age_range, face, skin_tone, hair, build, makeup}
2. clothing: {type, color, pattern, material_look, neckline, sleeve, length, fit, details, accessories}
3. scene: {location, background_objects, floor, wall, lighting_source, color_temperature, overall_tone}
4. actions: timeline string (每1-2秒一个节点, must specify left/right hand)
5. dialogue: transcript with embedded action markers, preserve filler words
6. camera: {movement_type, orientation, timeline}
7. audio: {has_speech, speech_style, background_sounds, music, overall_audio_mix}
8. video_type: string
9. duration_seconds: {actual, recommended}
10. people_count: int

### 2. Rewrite Mode (video_analyzer.py) — Flat analysis for viral logic

**System Prompt:**
> 你是 Seedance 2.0 提示词逆向工程专家。根据视频关键帧和音频转录（如有），推理出能生成类似视频的 Seedance 2.0 提示词参数。

**10-field flat output:**
1. gender: male/female
2. scene: 2-3 sentences
3. clothing: 2-3 sentences
4. actions: timeline with台词时间对齐, 固定右手
5. dialogue: transcript with action markers
6. camera: movement + composition + framing changes
7. dialogue_style: one sentence description
8. video_type: string
9. has_speech: bool
10. duration_seconds: 5 or 10

## Vision API Call

```
POST {ARK_API_BASE}/api/v3/chat/completions
Headers:
  Authorization: Bearer {ARK_API_KEY}
  Content-Type: application/json
Body:
  model: {ARK_VISION_MODEL}
  messages:
    - role: system, content: system_prompt
    - role: user, content: [text_prompt, image_url(grid1), image_url(grid2), ...]
  temperature: 0.3
  max_tokens: 4096
Timeout: 120s
```

Image format: `data:image/jpeg;base64,{grid_base64}`

## JSON Parsing

Strip markdown code fences if present:
```python
if stripped.startswith("```"):
  stripped = stripped.split("\n", 1)[1].rsplit("```", 1)[0]
```

---
name: fashion-video-creator
description: "穿搭视频创作 — 生成虚拟模特图(Seedream 4.5/5.0) + Seedance 2.0 视频Prompt + 操作手册(SOP)。支持单条和批量模式。Use when: '帮我做穿搭视频', '生成模特图', 'generate outfit video', '批量生成穿搭prompt', '穿搭创作', '虚拟模特'. Do NOT use for video analysis/reverse engineering — use viral-video-replicator instead."
version: "1.1.0"
compatibility: "Claude Code, Claude.ai, and all SKILL.md-compatible agents"
---

# Skill: fashion-video-creator

## Overview

Generate complete assets for fashion e-commerce videos from scratch: a virtual model image (Seedream text-to-image) + a Seedance 2.0 video prompt with dialogue, actions, and scene + an operator SOP for the Jimeng platform. Supports single and batch modes.

## When to Activate

User query contains any of:
- "穿搭视频", "outfit video", "生成模特", "虚拟模特"
- "seedance prompt", "穿搭创作", "带货视频", "带货短视频"
- "帮我做个穿搭视频", "批量生成穿搭", "batch prompt"
- "帮我拍个带货视频", "我有件衣服想做个展示视频", "做个穿搭短视频"
- "generate fashion video", "create outfit content"

Do NOT activate for:
- Analyzing / reverse-engineering existing videos -> use `viral-video-replicator`
- "这个视频怎么拍的", "帮我复刻这个视频" -> use `viral-video-replicator`
- Pure image generation without video prompt -> direct Seedream API call
- Non-fashion video generation -> not applicable

## Prerequisites

This skill requires a Volcano Engine (火山方舟) account with Seedream model access.

```
Required: ARK_API_KEY + Seedream model/endpoint ID
Optional: None (all other logic is local)
```

## Clarification Flow

### Phase 1: API Key Acquisition

Ask these questions IN ORDER. Use plain language — the user may not be technical.

**Q1: Image Generation Service**
> "你需要先有一个能生成图片的 AI 服务账号。目前这个工具使用的是火山方舟平台的 Seedream 模型。
> 你有火山方舟的账号吗？如果有，请提供你的 API Key（在火山方舟控制台 -> API Key 管理中可以找到）。"

If user has no account -> STOP. Guide them to register at 火山方舟. Do NOT proceed without API key.

**Q2: Model Version**
> "火山方舟上有两个版本的图片生成模型：
> - **Seedream 5.0**（推荐）：理解能力更强，生成的人像更自然，每张约 0.22 元
> - **Seedream 4.5**：可以更精细地控制细节，每张约 0.32 元
>
> 你开通了哪个？需要提供模型ID或接入点ID。"

### Phase 2: Mandatory Recommendations

MUST show before proceeding. These are not optional tips — violating them degrades output quality:

```
============================================================
API Configuration — Mandatory Recommendations
============================================================

[REQUIRED] Seedream 5.0 endpoint preferred
  WHY: 5.0 uses internal Chain-of-Thought reasoning, making natural
  language prompts significantly more effective. 4.5 relies on keyword
  stacking which loses semantics in complex body descriptions.
  If only 4.5: use model ID doubao-seedream-4-5-251128 or newer.

[REQUIRED] Realism scale 40-60
  WHY: Below 30 the output looks cartoonish (Pixar-style), unsuitable
  for product videos that need believable human models. Above 80 triggers
  uncanny valley artifacts and skin texture glitches.

[WARNING] Using older models or non-recommended endpoints will produce
noticeably worse portrait realism and clothing detail accuracy.
============================================================
```

### Phase 3: Mode Selection

> "你要生成几条视频？单条还是批量？"

### Phase 4: Creative Parameter Collection

**Collection strategy — ask in 2 rounds, never more than 4 questions per round:**

**Round 1 (required — must have before executing):**
1. Model gender (female/male) — default: female
2. Garment type (dress/top/pants/jacket/suit/casual) — NO default, must ask. WHY: "default" type produces generic dialogue without product-specific selling points. **Defensive fallback:** If user declines to specify after 2 attempts, fall back to "default" with warning: "Using generic dialogue — conversion effectiveness will be lower than type-specific scripts."
3. Scene (11 presets or custom text) — default: modern_apartment

**Round 2 (enhanced — use defaults if not stated):**
4. Model appearance: preset (9 templates) / body params / custom desc — default: asian_female_slim
5. Realism (0-100) — default: 40
6. Style: realism / pixar / anime_realistic — default: realism
7. Dialogue style: natural / professional / enthusiastic — default: natural
8. Camera: vlog / pro / static — default: vlog
9. Target audience: auto / female / male — default: auto
10. Duration (5-40s) — default: 10
11. Language: zh / en — default: zh
12. Task label (batch only)

**Batch shortcut:** If all tasks share config, ask once and apply to all. Only collect per-task differences.

### Batch-Specific Recommendations

When batch mode selected, ADDITIONALLY show:

```
============================================================
Batch Mode — Additional Recommendations
============================================================

[REQUIRED] Specify exact garment type per task — do NOT use "default"
  WHY: Each garment type has 500+ chars of specialized dialogue with
  product-specific hand gestures (e.g., dress: pull hem to show fabric;
  pants: flip waistband to show grip strip). "default" loses all this.

[RECOMMENDED] Same gender per batch
  WHY: Mixing genders creates inconsistent dialogue tone — female uses
  filler words and emotional reactions, male is direct and factual.

[REQUIRED] Duration 10-15 seconds
  WHY: Under 5s cannot complete a product showcase. Over 15s triggers
  multi-segment auto-chaining which requires manual "extend" operations.
============================================================
```

## Core Workflow

### Step 0: Verify API Key (mandatory, never skip)

Platform-adaptive verification:

**If bash/Python available (Claude Code, terminal):**
```python
import httpx
resp = httpx.get(f"{ARK_API_BASE}/api/v3/models",
                 headers={"Authorization": f"Bearer {ARK_API_KEY}"}, timeout=10)
# 200 -> proceed. 401/403 -> key invalid. Timeout -> network issue.
```

**If no code execution (Claude.ai web, chat-only):**
Trust the user-provided key and proceed. Mark internally: `api_verified: false`.
If Step 3 (image generation) fails with 401 -> surface the error then.

- Key valid -> proceed to Step 1
- Key invalid (401/403) -> report error, ask user to verify. Do NOT proceed.
- No code execution -> proceed with unverified key, validate on first API call.

### Single Mode

```
Step 1: Collect parameters (2 rounds max)
Step 2: Build model prompt (version-aware: 4.5 keyword / 5.0 natural language)
Step 3: Call Seedream API -> generate model image (720x1280, 9:16)
Step 4: Build Seedance prompt -> compose dialogue + actions + scene + camera
        Read references/dialogue-library.md for garment-specific scripts
        Read references/prompt-assembly.md for assembly rules
Step 5: Generate SOP
Step 6: If duration > 15s -> build chained multi-segment extend plan
Step 7: Validate output (see below)
```

### Batch Mode

```
Step 0: Verify API key
Step 1: Collect batch size + per-task configs (2 rounds)
Step 2: Validate all configs (garment type != "default"?)
Step 3: For each task (sequential):
  a. Build model prompt
  b. Call Seedream API (if image needed)
  c. Compose dialogue (opening + core + closing) from dialogue-library.md
  d. Compose actions (garment-specific choreography)
  e. Assemble Seedance prompt
  f. If duration > 15s: build chained segments
  g. Generate SOP
  h. Mark task: completed / failed
Step 4: Validate all outputs
Step 5: Return results with progress summary

Progress: queued -> processing -> completed/failed
Partial success: batch completes even if some tasks fail.
```

### Output Validation (mandatory, never skip)

Before delivering results, verify ALL:

- [ ] Model image is 9:16 portrait with full body visible (head to feet)?
- [ ] Prompt contains @image1 (garment) and @image2 (model ref)?
- [ ] Dialogue matches the selected garment type (not generic "default")?
- [ ] SOP specifies correct image upload order (image1=garment FIRST)?
- [ ] If chained: every segment has continuation prompt + dialogue preview?
- [ ] Brand constraint present: "Do not alter clothing pattern, color, texture or style"?

**Any NO -> fix before delivering. Do NOT send unvalidated output.**

## Error Handling

| Failure | Detection | Action |
|---------|-----------|--------|
| No API key | ARK_API_KEY empty or missing | **STOP.** Guide user to 火山方舟 console. Do NOT proceed. |
| Invalid API key | 401/403 from API | Report error. Ask user to verify key. Do NOT retry with guessed keys. |
| Seedream timeout | No response in 300s | Retry once with same prompt. Still fails -> report with the prompt used so user can try manually. |
| No image in response | API returns empty data | Simplify prompt (remove extras), retry. Still empty -> report error. |
| Batch task fails | Exception during prompt assembly | Mark task as failed with error message. Continue remaining tasks. Report partial results at end. |
| Invalid garment type | User provides unknown type | Map to closest valid type or ask for clarification. Valid: dress/top/pants/jacket/suit/casual/default. |

### Degraded Mode: Prompt-Only (when image generation fails)

If Seedream API is unreachable or fails after retry, do NOT block the entire workflow.
**Skip image generation, still deliver prompt + SOP.** Mark output clearly:

```
[Note] Model image generation unavailable (API error). Prompt and SOP generated successfully.
Use your own model photo as @image2 when operating on the Jimeng platform.
```

This ensures the user gets the valuable prompt + SOP even without the AI-generated model image.

## Usage Example

**Input:** "帮我做一个女性穿搭视频，裙子类型，现代公寓场景"

**Resolved params:** gender=female, garment=dress, scene=modern_apartment, realism=40, style=realism, dialogue=natural, camera=vlog, audience=auto->female, duration=10, lang=zh

**Output 1 — Model Image:** 720x1280 PNG (asian_female_slim preset, realism=40)

**Output 2 — Seedance Prompt:**
```
一位面容和身材参考@图片2的年轻女性穿着@图片1中的服装，在简约现代的白色公寓客厅中，自然光从落地窗照入。她面朝镜头表情生动自然地展示服装，右手拉起裙摆展示面料（始终用右手），右手翻开裙摆内侧展示车线做工，小幅转身让裙摆飘动，右手捏腰部展示松紧设计，对着镜头说：「姐妹们你们快看...哇，不是，我真的没想到这条裙子上身效果这么好。你看这个面料，是那种...嗯...醋酸缎面的...（右手轻轻拉起裙摆展示）滑滑的凉凉的，而且有一定的厚度，不是那种廉价的薄纱感。然后你看这个车线...（右手翻开裙子内侧给镜头看）全部是包边走线的，没有毛边，做工真的很扎实。裙摆是A字的微微伞摆，你看我转一下...（转了一圈）你看它飘起来那个弧度，而且腰线这里有一个隐藏的松紧设计...（右手捏了捏腰部）不会勒但又收腰。你们猜多少钱？不到两百！超显腿长，闭眼入。」语气自然亲切，像在跟闺蜜视频通话。说话有停顿、有喘息、偶尔磕巴自我纠正，真实感强。Do not alter clothing pattern, color, texture or style. 手持vlog镜头感，竖屏9:16构图。音频要求：全程只有模特一个人的清晰人声，不出现第二个人的声音或对白。背景有符合场景的自然环境音，音量不超过人声的10%。视觉要求：全程保持中景到中近景，不要切到手部或脚部的特写镜头，避免手指变形问题。模特展示服装细节时始终使用右手操作，避免左右手切换导致的镜像翻转。全程画面中只有模特一人，不出现其他人物。
```

**Output 3 — Operator SOP:** Step-by-step for 即梦 platform (upload order, settings, quality checklist)

## Domain Knowledge Role Declaration

> The reference files contain dialogue scripts, model presets, API specs, and prompt templates.
> Their role is to **assist prompt assembly** — providing the raw materials that get composed into Seedance prompts.
> They do NOT replace the execution workflow. Never output reference content directly as the final answer.
> Always assemble through the workflow: collect params -> build prompt -> validate -> deliver.

## References

| File | Purpose | When to read |
|------|---------|-------------|
| [references/model-presets.md](references/model-presets.md) | 9 model presets, body params, 17-level realism anchors, scene/camera/style presets | Step 2: building model prompt |
| [references/seedream-api.md](references/seedream-api.md) | Seedream 4.5/5.0 API endpoint, request format, cost, crop logic | Step 3: calling API |
| [references/prompt-assembly.md](references/prompt-assembly.md) | Prompt composition order, multi-segment chaining constants, SOP templates | Step 4-6: assembling prompt and SOP |
| [references/dialogue-library.md](references/dialogue-library.md) | Complete dialogue scripts: 7 garment types x 2 genders x 2 languages (28 scripts total), openings, closings, actions | Step 4: composing dialogue content |

FILE:README.md
# fashion-video-creator

穿搭视频创作 — 从零生成带货视频的完整素材

## 概述

一站式生成穿搭带货视频所需的全部素材：
- **虚拟模特图**：通过 Seedream 4.5/5.0 文生图生成 720x1280 的全身模特照
- **Seedance 2.0 视频提示词**：包含对话脚本、手势动作、场景描述、镜头风格
- **操作手册(SOP)**：即梦平台的逐步操作指引，从上传素材到生成视频

支持单条和批量模式。批量模式下每条视频可独立配置服装类型、场景、风格等参数。

## 核心能力

| 能力 | 说明 |
|------|------|
| 9 种模特预设 | 亚洲/欧美/黑人/拉丁裔，纤细/丰满/健美等体型 |
| 精细体型参数 | 身材/胸围/肩宽/腰/臀/腿/肤色/发型，每项独立调节 |
| 17 级写实度 | 0(皮克斯卡通) → 40(半写实推荐) → 100(RAW照片) |
| 7 种服装话术 | 裙装/上衣/裤装/外套/西装/休闲/通用，每种有专属对话和手势 |
| 11 个场景预设 | 公寓/卧室/街拍/商场/停车场/咖啡馆/摄影棚等 |
| 多段自动接链 | 视频 >15 秒时自动拆分为多段 Seedance 延长接龙 |
| 双语支持 | 中文/英文对话脚本 |

## 快速开始

### 安装

```bash
# Claude Code 用户
claude install-skill https://github.com/dingtom336-gif/outfit-video/tree/main/skills/fashion-video-creator
```

### 前置条件

- 火山方舟账号 + API Key
- Seedream 5.0 端点（推荐）或 4.5 模型ID

### 使用

对 Claude 说：
- "帮我做一个穿搭视频，裙子类型"
- "批量生成 5 条带货视频的 Prompt"
- "生成一个男性模特的西装展示视频"

## 文件结构

```
fashion-video-creator/
├── README.md                           # 本文件
├── SKILL.md                            # 核心技能逻辑
└── references/
    ├── model-presets.md                # 模特预设 + 体型参数 + 写实度锚点
    ├── seedream-api.md                 # Seedream API 调用规范
    ├── prompt-assembly.md              # Prompt 组装规则 + 多段接链 + SOP 模板
    └── dialogue-library.md             # 完整对话库：7 类型 x 2 性别 x 2 语言
```

## 兼容性

Claude Code, Claude.ai, 以及所有兼容 SKILL.md 的 Agent。

## 关联技能

- **[viral-video-replicator](/viral-video-replicator/)** — 已有参考视频？用它来逆向分析并生成复刻 Prompt

## 许可证

MIT

---

# fashion-video-creator

Fashion Video Creator — Generate complete e-commerce video assets from scratch

## Overview

One-stop generation of all assets needed for fashion e-commerce videos:
- **Virtual Model Image**: Generate 720x1280 full-body model photos via Seedream 4.5/5.0 text-to-image
- **Seedance 2.0 Video Prompt**: Complete with dialogue scripts, hand gestures, scene descriptions, and camera styles
- **Operator SOP**: Step-by-step guide for the Jimeng (即梦) platform, from uploading assets to generating video

Supports single and batch modes. In batch mode, each video task can be independently configured with different garment types, scenes, and styles.

## Core Capabilities

| Capability | Details |
|------------|---------|
| 9 Model Presets | Asian/European/Black/Latina, slim/curvy/athletic body types |
| Fine-grained Body Params | Build/bust/shoulders/waist/hips/legs/skin/hair, each independently adjustable |
| 17-level Realism | 0 (Pixar cartoon) → 40 (semi-realistic, recommended) → 100 (RAW photo) |
| 7 Garment Dialogue Scripts | Dress/top/pants/jacket/suit/casual/default, each with specialized dialogue and gestures |
| 11 Scene Presets | Apartment/bedroom/street/mall/parking/cafe/studio and more |
| Auto Multi-segment Chaining | Videos >15s auto-split into Seedance extend-chain segments |
| Bilingual | Chinese and English dialogue scripts |

## Quick Start

### Install

```bash
# Claude Code users
claude install-skill https://github.com/dingtom336-gif/outfit-video/tree/main/skills/fashion-video-creator
```

### Prerequisites

- Volcano Engine (火山方舟) account + API Key
- Seedream 5.0 endpoint (recommended) or 4.5 model ID

### Usage

Say to Claude:
- "Create a fashion video for a dress"
- "Batch generate 5 outfit video prompts"
- "Generate a male model suit showcase video"

## File Structure

```
fashion-video-creator/
├── README.md                           # This file
├── SKILL.md                            # Core skill logic
└── references/
    ├── model-presets.md                # Model presets + body params + realism anchors
    ├── seedream-api.md                 # Seedream API call specifications
    ├── prompt-assembly.md              # Prompt assembly rules + multi-segment chaining + SOP templates
    └── dialogue-library.md             # Complete dialogue library: 7 types x 2 genders x 2 languages
```

## Compatibility

Claude Code, Claude.ai, and all SKILL.md-compatible agents.

## Related Skills

- **[viral-video-replicator](/viral-video-replicator/)** — Have a reference video? Use this to reverse-engineer and replicate it

## License

MIT

FILE:references/dialogue-library.md
# Dialogue Library — Complete Reference

> This file provides raw dialogue materials for Seedance prompt assembly.
> Role: assist prompt composition by supplying garment-specific scripts.
> It does NOT replace the assembly workflow. Never output these dialogues directly — always compose through the workflow in SKILL.md.

## Dialogue Composition Formula

```
Full dialogue = OPENING + DIALOGUE_CORE + SELLING_CLOSING
```

Target audience auto-resolution:
- dress/bikini -> female audience
- All others -> same as model gender
- Can be overridden by user

---

## 1. Openings — by (model_gender, target_audience)

| (Gender, Audience) | zh | en |
|---------------------|----|----|
| (female, female) | 姐妹们你们快看... | Oh my god you guys need to see this... |
| (female, male) | 男生们看过来...这件我帮你们试了， | Hey guys, I tried this on for you, |
| (male, female) | 姐妹们，男生视角说一句... | Ladies, honest take from a guy... |
| (male, male) | 兄弟们，这件不吹不黑... | Bros, no BS on this one... |

---

## 2. Dialogue Core — 7 garment types x 2 genders x 2 languages

Female tone: expressive, filler words (嗯/就是/哇), emotional reactions.
Male tone: direct, fewer fillers, factual, confident.

### dress / female / zh
> 哇，不是，我真的没想到这条裙子上身效果这么好。你看这个面料，是那种...嗯...醋酸缎面的...（右手轻轻拉起裙摆展示）滑滑的凉凉的，而且有一定的厚度，不是那种廉价的薄纱感。然后你看这个车线...（右手翻开裙子内侧给镜头看）全部是包边走线的，没有毛边，做工真的很扎实。裙摆是A字的微微伞摆，你看我转一下...（转了一圈）你看它飘起来那个弧度，而且腰线这里有一个隐藏的松紧设计...（右手捏了捏腰部）不会勒但又收腰。

### dress / female / en
> I seriously didn't expect this dress to look this good on. The fabric is... (pulls up hem) it's this acetate satin, has actual weight, not cheap at all. And the stitching inside... (flips hem) fully finished seams, no raw edges. The skirt is this subtle A-line flare, watch when I spin... (spins) See how it flows? And the waistband has hidden elastic... (pinches waist) cinches without digging in.

### dress / male / zh
> 说实话这条裙子比我预期好很多。你们看面料...（右手拉起裙摆展示）醋酸缎面的，有厚度有质感，不是那种一看就便宜的料子。做工...（右手翻开内侧给镜头看）全是包边走线，没线头，确实扎实。裙摆A字微伞摆，转一下你们看...（转了一圈）这个弧度很好看。腰线有隐藏松紧...（右手捏了捏腰部）收腰但不勒，设计合理。

### dress / male / en
> Honestly this dress is way better than I expected. Fabric... (pulls up hem) acetate satin, has weight and texture, not cheap. Construction... (flips inside) fully finished seams, no loose threads. A-line flare, watch... (spins) nice arc. Hidden elastic waistband... (pinches waist) cinches without squeezing.

### top / female / zh
> 你看这件上衣，版型真的绝了。肩线...（右手沿着肩缝划过去）是落肩但不是烂大街的那种，刚好在肩头往下一厘米，就...嗯...显得肩膀很窄很精致。面料...（右手拉起下摆展示）260克重磅棉，洗十次都不变形。领口罗纹...（右手轻轻拉了拉领口边）弹性很好，不会越穿越松垮。嗯...腰这里有点收的，但又不太紧...（侧身展示腰线）侧面这个弧度，该收的收，该放的放。

### top / female / en
> Look at this top, the cut is insane. Shoulder seam... (traces along it) drop shoulder, one centimeter below the bone, makes shoulders look narrow and clean. Fabric... (lifts hem) 260gsm heavyweight cotton, won't warp after ten washes. Ribbed collar... (flicks neckline) stretchy, won't sag. Slightly tapered waist... (turns sideways) cinched where it matters.

### top / male / zh
> 这件上衣版型确实不错。肩线...（右手沿肩缝划过去）落肩一厘米，不夸张，穿着自然。面料...（右手拉起下摆展示）260克重磅棉，厚实，洗了不变形。领口罗纹...（右手拉了拉领口）弹性好，不会松垮。腰部微收...（侧身展示）侧面轮廓干净，不松不紧。

### top / male / en
> This top's got a solid cut. Shoulder seam... (traces it) one centimeter drop, natural, not overdone. 260gsm heavyweight cotton... (lifts hem) thick, holds shape after washing. Ribbed collar... (tugs it) stays put. Slight taper at the waist... (turns sideways) clean profile.

### pants / female / zh
> 好...我终于找到了一条不用改裤脚的裤子！你看腰头...（右手翻出腰头内侧展示）双层的，里面还有防滑硅胶条，蹲下去再站起来也不滑。裤型...（退后两步正面展示）直筒微锥的，关键是侧缝线...（右手从腰沿着裤缝往下划）往后偏了一点，视觉上让腿看起来更直更长。面料...（右手抓起裤腿揉了揉再松开）松手就回弹，有弹力的西装面料，坐一天不出褶子。九分长度，裤脚收边干净。

### pants / female / en
> Finally... pants I don't need to hem! Waistband... (flips inside) double-layered with silicone grip, stays put. Silhouette... (steps back) straight with slight taper, side seam shifted back... (traces from waist down) makes legs look straighter. Fabric... (scrunches pant leg, releases) bounces right back, stretch suiting, no wrinkles after sitting all day. Ankle length, clean hem.

### pants / male / zh
> 这条裤子几个重点。腰头...（右手翻出内侧展示）双层的，有防滑硅胶条，蹲下站起来不滑。裤型...（退后两步展示）直筒微锥，侧缝线...（右手从腰沿裤缝往下划）往后偏了一点，视觉上腿更直。面料...（右手抓起裤腿揉一下松开）松手回弹，有弹力西装面料，坐一天不起皱。九分长度，收边干净利落。

### pants / male / en
> Key points on these pants. Waistband... (flips inside) double-layered, silicone grip strip. Straight taper... (steps back) side seam shifted back, visually lengthening. Fabric... (scrunches and releases) snaps back, stretch suiting, wrinkle-free. Ankle length, clean hem.

### jacket / female / zh
> 天哪...穿上之后照镜子就...哇，气场直接出来了。面料...（右手蹭了蹭袖子）挺括的华达呢，磨砂感但不扎人，很有分量，拿手上就知道不便宜。肩线...（右手拍了拍肩膀）两毫米微垫肩，不夸张，刚好撑起来不塌。内衬...（拉开外套给镜头看）缎面的，滑进去很爽。扣子...（右手拨弄前襟纽扣）真正牛角扣，不是塑料。

### jacket / female / en
> Oh my god... instant power the moment I put it on. Fabric... (rubs sleeve) structured gabardine, has real weight. Shoulder... (pats shoulder) two millimeters of padding, just enough structure. Lining... (opens jacket) satin, slides right on. Buttons... (fiddles with button) real horn, not plastic.

### jacket / male / zh
> 这件外套穿上就知道不便宜。面料...（右手蹭了蹭袖子）华达呢，挺括有分量，磨砂质感但不扎。肩线...（右手拍肩膀）两毫米微垫肩，撑得起来但不夸张。内衬...（拉开外套展示）缎面，穿脱顺滑。扣子...（右手拨弄纽扣）牛角扣，不是塑料。做工细节到位。

### jacket / male / en
> You can tell this jacket's quality the second you put it on. Gabardine... (rubs sleeve) structured, has weight, matte finish. Shoulder... (pats it) minimal padding, holds shape without overdoing it. Satin lining... (opens jacket) smooth. Horn buttons... (touches button) not plastic. Details are there.

### suit / female / zh
> 这套...嗯...我自己打十分。先说上衣...领子...（右手拉着西装领子）戗驳领，角度锐利，显得人很精神。胸袋...（右手划过胸口口袋）斜插的，比直的显瘦。裤子和上衣同一块面料...（右手把上衣下摆贴着裤腰对比）色差完全一致。转一圈...（转身展示背面）后背没多余褶皱，单开衩，更正式更有质感。

### suit / female / en
> Giving this suit a solid ten. Blazer collar... (tugs lapel) peak lapel, sharp angle, looks polished. Breast pocket... (traces it) angled, more slimming. Same bolt of fabric... (holds hem against waistband) perfect match. Let me spin... (turns) clean back, single vent, refined.

### suit / male / zh
> 这套直接给满分。上衣...（右手拉西装领子）戗驳领，角度锐利，精气神马上就有了。胸袋...（右手划过口袋）斜插，视觉显瘦。裤子上衣同料裁的...（右手对比上下面料）色差为零。转一下...（转身）后背干净利落，单开衩，够正式。

### suit / male / en
> Full marks on this suit. Peak lapel... (tugs collar) sharp angle, instant presence. Angled breast pocket... (traces it) slimming. Same fabric top to bottom... (compares) zero color difference. Back is clean... (turns) single vent, formal.

### casual / female / zh
> 今天就一个超日常的穿搭，出门买咖啡遛弯那种。但这件T...（右手拉起衣角展示）不是普通白T，克重...拿手上沉甸甸的，领口是小圆领，开口不大...（右手轻拉领口）不会洗几次就变大。下面裤子...面料...（右手揉了揉裤腿）棉麻混纺，有自然的肌理感，但不扎腿，贴皮肤很舒服。

### casual / female / en
> Super casual today, grab-coffee-and-go look. But this tee... (lifts hem) heavyweight, you can feel it. Small crew neck... (traces collar) won't stretch out. Pants... (rubs pant leg) cotton-linen blend, textured but comfortable.

### casual / male / zh
> 今天走个日常路线。这件T...（右手拉起衣角展示）不是普通白T，拿手上就知道有分量，重磅的。领口...（右手拉了拉领口）小圆领，洗了不变形。裤子...（右手揉裤腿）棉麻混纺，有肌理但不扎，穿着舒服。

### casual / male / en
> Keeping it simple today. This tee... (lifts hem) heavyweight, you feel the quality. Crew neck... (tugs collar) holds its shape. Pants... (rubs leg) cotton-linen, textured but soft.

### default / female / zh
> 嗯...就是之前刷到好多人推荐的那件，我终于买了。面料...（右手拉起衣角展示）你看这个纹理，有肌理感，不是那种滑面化纤，像高支棉的柔软但有骨架感。做工...（右手翻开内侧展示缝线）走线很密很工整，收边是折叠锁边的。版型...（退后一步正面展示）上身轮廓...该贴的贴该松的松，修饰身形但完全不勒。嗯...你看侧面...（侧身展示）腰线位置特别好。

### default / female / en
> I finally got the thing everyone's been recommending. Fabric... (pulls up hem) has texture, not slippery polyester, soft but structured. Construction... (flips inside) dense stitching, folded lock-stitch. Fit... (steps back) drapes perfectly, fitted where it should be. Side view... (turns) waistline sits just right.

### default / male / zh
> 之前一直被推荐这件，终于上手了。面料...（右手拉起衣角展示）有肌理感，不是化纤滑面，类似高支棉的质感。做工...（右手翻开内侧展示）走线密实，折叠锁边，不会穿两次就散。版型...（退后一步展示）上身轮廓干净，该贴的贴该松的松。侧面...（侧身）腰线位置对，不拖沓。

### default / male / en
> Been hearing about this one, finally got it. Fabric... (lifts hem) textured, not synthetic-slick, feels like premium cotton. Construction... (flips inside) tight stitching, folded seams, built to last. Fit... (steps back) clean silhouette. Side view... (turns) waistline sits right, no dragging.

---

## 3. Selling Closings — by (target_audience, garment_type)

### Female audience

| Garment | zh | en |
|---------|----|----|
| dress | 你们猜多少钱？不到两百！超显腿长，闭眼入。 | Guess the price? Under thirty! Makes legs look forever. No-brainer. |
| top | 随便配条牛仔裤、配裙子都行，显肩窄显脸小，闭眼入。 | Pairs with jeans, skirts, anything. Makes shoulders look narrow. Get it. |
| pants | 165配小白鞋刚刚好，显腿长显瘦，真的推荐。 | Perfect with sneakers, slimming and elongating. Highly recommend. |
| jacket | 穿上气场全开，价格还很合理，冲。 | Instant power vibes, and the price is fair. Go for it. |
| suit | 最关键显瘦！我今天吃了火锅出来完全看不出来。 | Most importantly, it's slimming. I just ate a huge meal, can you tell? No. |
| casual | effortless chic，五分钟出门但不邋遢，推荐。 | Effortless chic, five minutes, out the door, still put-together. |
| default | 价格也不贵，真的闭眼入级别了，必须分享给你们。 | Price is right too. Absolute no-brainer. You need this. |

### Male audience

| Garment | zh | en |
|---------|----|----|
| dress | 这个质感在这个价位真的没话说，值得入手。 | Quality at this price point is legit. Worth it. |
| top | 不挑身材不挑场合，耐洗耐穿，闭眼入兄弟们。 | Works on any build, any occasion. Durable. Just get it. |
| pants | 坐一天不起皱，一条能穿好几年，质价比到位。 | Wrinkle-free all day, lasts for years. Worth every penny. |
| jacket | 有型有质感，这个价位确实没毛病。 | Stylish, quality build, fair price. No complaints. |
| suit | 做工扎实，撑得住任何场面，值得入。 | Solid build, holds up in any setting. Worth the investment. |
| casual | 省心不费脑子，穿上出门就完事。 | Zero effort, throw it on, done. That simple. |
| default | 实穿百搭，质价比到位，闭眼入。 | Practical, versatile, solid value. Get it. |

---

## 4. Garment Actions

All actions use RIGHT HAND only. WHY: Seedance has mirror-flip issues; fixing to right hand avoids left/right inconsistency.

| Type | Actions |
|------|---------|
| dress | 右手拉起裙摆展示面料（始终用右手），右手翻开裙摆内侧展示车线做工，小幅转身让裙摆飘动，右手捏腰部展示松紧设计 |
| top | 右手沿肩缝划过展示肩线位置，右手拉起下摆展示面料厚度，右手轻拉领口展示弹性（始终用右手操作），侧身展示腰线弧度 |
| pants | 右手翻出腰头内侧展示防滑条（始终用右手操作），退后两步展示全身裤型，右手沿侧缝线从腰往下划展示裁剪，右手抓起裤腿揉一下再松开展示回弹性 |
| jacket | 右手蹭袖子展示面料质感（始终用右手操作），右手拍肩膀展示垫肩，拉开外套展示缎面内衬，右手拨弄前襟纽扣展示牛角扣 |
| suit | 右手拉西装领子展示戗驳领（始终用右手操作），右手划过胸口口袋展示斜插设计，右手把上衣下摆贴着裤腰对比色差，转身展示背面裁剪和开衩细节 |
| casual | 右手拉起衣角展示面料厚度（始终用右手操作），右手轻拉领口展示开口大小，右手揉裤腿展示棉麻面料质感 |
| default | 右手拉起衣角展示面料（始终用右手操作），右手翻开衣服内侧给镜头看缝线做工，退后一步正面展示整体版型，侧身展示腰线位置 |

## 5. Action Demeanor

| Gender | Demeanor |
|--------|----------|
| female | 面朝镜头表情生动自然地展示服装 |
| male | 面朝镜头自信从容地展示服装 |

## 6. Dialogue Style Instructions (gender-aware)

| Style | Female | Male |
|-------|--------|------|
| natural | 语气自然亲切，像在跟闺蜜视频通话。说话有停顿、有喘息、偶尔磕巴自我纠正，真实感强。 | 语气自然随和，像在跟朋友聊天推荐好物。说话直接但不生硬，偶尔停顿思考，真实感强。 |
| professional | 语气专业自信，像品牌代言人。吐字清晰，节奏稳定。 | 语气专业沉稳，像品牌代言人。吐字清晰，从容有力。 |
| enthusiastic | 语气兴奋热情，像发现了宝藏。语速偏快，情绪感染力强。 | 语气热情有感染力，像发现好东西迫不及待分享。语速适中但有力。 |

FILE:references/model-presets.md
# Model Presets & Realism System

> **Role:** Provides model appearance templates, body parameter mappings, and realism anchor tables for building Seedream prompts.
> Load at: Step 2 (building model prompt). Full realism anchor tables only needed when user requests custom realism level outside 40-60 range.
> It does NOT replace execution. Use these as input to the prompt-building step, never as standalone output.

## Realism Anchors — Seedream 4.5 (English keyword stacking)

| Value | Prompt Suffix |
|-------|---------------|
| 0 | stylized 3D character, clean cartoon render, smooth porcelain skin, simplified hair volume, flat studio lighting, Pixar-quality detail |
| 10 | stylized digital portrait, anime-influenced proportions, smooth airbrushed skin, clean hair silhouette, soft even CG lighting, high detail render |
| 20 | digital art portrait, trending on Artstation, soft matte skin with minimal texture, neat styled hair, soft diffused render lighting, 4K detail |
| 30 | semi-realistic digital portrait, fashion lookbook render style, skin has soft matte finish with faint pore hints, natural hair flow, soft studio lighting, 8K detail |
| 37 | semi-realistic fashion portrait, subtle digital art polish, smooth fair skin with very faint pore hints, hair with natural volume and soft movement, soft diffused studio lighting, 8K detail |
| 40 | semi-realistic fashion portrait, subtle digital art enhancement, natural skin tone with visible pore texture, hair with natural volume and movement, soft natural lighting, 8K detail |
| 42 | semi-realistic fashion portrait, minimal digital enhancement, natural skin with soft pore texture and faint unevenness, hair with natural volume and slight flyaways, soft natural lighting, 8K detail |
| 44 | semi-realistic portrait with natural quality, very subtle digital smoothing, natural skin with clear pore texture and soft tonal variation, hair with natural movement and fine strands visible, natural soft lighting, 8K detail |
| 45 | semi-realistic to realistic portrait, borderline digital and natural, natural skin with visible pores and slight tonal unevenness, hair with natural flow and individual strands, soft natural window-adjacent lighting, 8K detail |
| 46 | near-realistic portrait, faint digital art quality, natural skin with pores and very subtle imperfections, hair with individual strand detail and natural volume, natural diffused lighting, 8K detail |
| 48 | near-realistic digital portrait, approaching photographic quality, natural skin with pores and faint blemishes, hair with individual strand detail and slight flyaways, natural ambient lighting, 8K detail |
| 50 | hyper-realistic digital portrait, slight painterly quality, natural skin with pores and subtle imperfections, hair with individual strand detail, natural window lighting, 8K detail |
| 60 | hyper-realistic portrait, minimal stylization, detailed skin texture with pores and micro-wrinkles, realistic hair with flyaway strands, natural ambient lighting, 8K photo quality |
| 70 | realistic portrait photography style, shot with 85mm lens, natural skin with visible pores and subtle blemishes, real hair texture with flyaways, soft natural light from window, 8K detail |
| 80 | ultra realistic portrait photography, shot on Sony A7R V 85mm f/1.4, detailed skin with pores freckles and natural imperfections, real hair strands with flyaways, catchlight in eyes, photo-quality 8K |
| 90 | photorealistic portrait, indistinguishable from real photo, every pore and skin fold visible, natural subsurface scattering, real messy hair with split ends, DSLR bokeh, RAW photo quality 8K |
| 100 | RAW photograph of a real person, zero stylization, all skin imperfections visible, natural unretouched skin, real hair with natural messiness, shot on Hasselblad, unedited 8K RAW |

## Realism Anchors — Seedream 5.0 (Chinese natural language)

| Value | Prompt Suffix |
|-------|---------------|
| 0 | 请生成一个明显的3D卡通角色，风格类似皮克斯动画电影。皮肤完全光滑没有任何毛孔，眼睛大而夸张，五官简化。头发是简洁的卡通体积感造型。整体是一眼就能看出的CG渲染风格。 |
| 10 | 请生成一个带有动漫影响的数字插画风格人物。皮肤平滑如喷绘，眼睛偏大，五官精致但明显是画出来的。头发是整齐的造型轮廓，整体是高质量的数字艺术风格。 |
| 20 | 请生成一个数字艺术风格的人物肖像，类似Artstation上的热门作品。皮肤是柔和的哑光质感，几乎看不到毛孔，头发整齐有型。打光柔和均匀，整体是精致的数字绘画效果。 |
| 30 | 请生成一个半写实的数字人物，风格介于时尚杂志的数字插画和真人之间。皮肤有柔和的哑光质感，隐约能看到一点毛孔的暗示。头发自然飘动但仍有明显的数字渲染感。这不是真人照片，而是高端的数字时尚渲染。 |
| 40 | 请生成一个半写实的时尚人物，看起来像高端时尚杂志的数字封面。皮肤质感自然，能看到毛孔纹理但整体仍有轻微的数字艺术修饰感。头发自然飘动有光泽。这个人物应该好看但一眼能看出不是未经处理的真人照片。请不要生成看起来像真实照片的面孔。 |
| 50 | 请生成一个接近真实但保留微妙数字艺术感的人物肖像。皮肤有自然的毛孔和轻微的色调不均匀，但整体比真实照片更干净一些。头发有自然的飘动和单根发丝的细节。光影效果类似自然窗光，整体介于数字艺术和摄影之间。 |
| 60 | 请生成一个高度写实的人物肖像，只保留极少的风格化痕迹。皮肤纹理细腻，毛孔和微小的皱纹都可见。头发真实自然，有碎发和飞丝。光影效果像自然环境光。 |
| 70 | 请生成一个看起来像专业摄影师用85mm人像镜头拍摄的真人照片。皮肤完全真实，毛孔、轻微的瑕疵都自然呈现。头发真实自然，有碎发飞丝。窗边柔和的自然光。 |
| 80 | 请生成一张高端人像摄影作品，看起来像用索尼A7R V配85mm f/1.4镜头拍摄的。皮肤极度真实，毛孔、雀斑、自然的皮肤不完美都清晰可见。头发有真实的发丝质感和自然的凌乱感。眼睛有自然的反光点。 |
| 90 | 请生成一张无法与真实照片区分的人物肖像。每一个毛孔、皮肤褶皱都清晰可见，有自然的皮下散射效果。头发真实凌乱，有分叉和自然的蓬松。背景有真实的景深虚化效果。 |
| 100 | 请生成一张看起来像哈苏相机拍摄的完全未修饰的RAW人像照片。零风格化处理，所有皮肤瑕疵完全可见，完全未经美颜的真实皮肤。头发自然凌乱未经整理。这应该看起来完全就是一张真实的照片。 |

## Realism Interpolation

`build_realism_suffix(realism)`: Picks the nearest anchor by absolute distance. No blending — uses the single closest anchor.

## Style Presets

### Seedream 4.5

| Style | Prompt Prefix |
|-------|---------------|
| pixar | Pixar-quality 3D rendered character, clean smooth skin with subtle subsurface scattering, stylized but recognizable facial features, large expressive eyes, slightly exaggerated proportions, beautiful CG hair with volume, professional studio lighting, cinematic depth of field, 8K render quality |
| anime_realistic | anime-influenced realistic portrait, smooth flawless skin, large detailed eyes, small refined nose and lips, styled flowing hair, soft cel-shading with realistic lighting, fashion illustration quality, 8K detail |

### Seedream 5.0

| Style | Prompt Prefix |
|-------|---------------|
| pixar | 请生成一个皮克斯动画电影质量的3D渲染角色。皮肤光滑干净，有微妙的次表面散射光泽。五官风格化但仍可辨认，眼睛大而富有表现力。身材比例可以略微夸张。头发是漂亮的CG造型，蓬松有光泽。专业的影棚打光，有电影感的景深效果。 |
| anime_realistic | 请生成一个融合了动漫风格和真实感的人物肖像。皮肤光滑细腻没有瑕疵，眼睛大而精致，鼻子和嘴唇小巧精致。头发飘逸有动态感。光影效果柔和，介于赛璐珞动画和真实光照之间。整体是高品质的时尚插画风格。 |

## Model Preset Templates (9 presets)

| Key | Label | Gender | v4.5 Description | v5.0 Description |
|-----|-------|--------|-------------------|-------------------|
| asian_female_slim | 亚洲女性/纤细 | female | A beautiful young Asian woman, age 25, slim and tall figure, long straight black hair, natural makeup, warm skin tone | 一位25岁左右的亚洲年轻女性，身材纤细高挑，黑色长直发，妆容自然，肤色温暖健康 |
| asian_female_curvy | 亚洲女性/微丰满 | female | A beautiful young Asian woman, age 26, curvy figure with natural proportions, shoulder-length black hair, natural makeup, warm skin tone | 一位26岁左右的亚洲年轻女性，身材微丰满但比例自然协调，齐肩黑发，妆容自然，肤色温暖 |
| european_female_slim | 欧美女性/纤细 | female | A beautiful young European woman, age 24, slim athletic figure, blonde wavy hair, light skin, natural makeup | 一位24岁左右的欧美年轻女性，身材纤细有运动感，金色波浪卷发，白皙肤色，妆容自然 |
| european_female_curvy | 欧美女性/丰满 | female | A beautiful young European woman, age 25, curvy hourglass figure, brown wavy hair, light skin, natural makeup | 一位25岁左右的欧美年轻女性，身材丰满有沙漏型曲线，棕色波浪卷发，白皙肤色，妆容自然 |
| dark_skin_female_slim | 黑人女性/纤细 | female | A beautiful young Black woman, age 26, tall and slim figure, curly natural hair, dark skin, natural makeup | 一位26岁左右的黑人年轻女性，身材高挑纤细，自然卷曲的黑色短发，深色肤色，妆容自然 |
| dark_skin_female_athletic | 黑人女性/健美 | female | A beautiful young Black woman, age 25, athletic fit figure, short natural hair, dark skin, natural makeup | 一位25岁左右的黑人年轻女性，身材健美紧实，自然短发，深色肤色，妆容自然 |
| latina_female | 拉丁裔女性 | female | A beautiful young Latina woman, age 24, medium figure, long dark brown wavy hair, warm olive skin tone, natural makeup | 一位24岁左右的拉丁裔年轻女性，身材匀称，深棕色波浪长发，温暖的橄榄色肤色，妆容自然 |
| asian_male_slim | 亚洲男性/瘦高 | male | A handsome young Asian man, age 26, slim tall figure, short black hair, clean-shaven | 一位26岁左右的亚洲年轻男性，身材瘦高，黑色短发，面容干净没有胡须 |
| european_male_athletic | 欧美男性/健壮 | male | A handsome young European man, age 27, athletic muscular build, short brown hair, light stubble | 一位27岁左右的欧美年轻男性，身材健壮有肌肉线条，棕色短发，留有轻微的胡茬 |

## Body Parameters — Female

### build
| Key | v4.5 | v5.0 |
|-----|------|------|
| slim | slim and tall figure | 身材纤细高挑 |
| medium | medium build with balanced proportions | 身材匀称比例协调 |
| curvy | curvy figure with natural proportions | 身材微丰满但比例自然 |
| athletic | athletic fit figure | 身材健美紧实 |
| hourglass | hourglass figure with slim waist | 沙漏型身材，腰细臀丰 |

### bust
| Key | v4.5 | v5.0 |
|-----|------|------|
| A | small A-cup bust | 胸部较小，A罩杯 |
| B | natural B-cup bust | 胸部自然，B罩杯 |
| C | C-cup bust with natural proportions | 胸部丰满，C罩杯，比例自然 |
| D | D-cup bust with natural proportions | 胸部丰满，约D罩杯，比例自然协调 |
| E | large E-cup bust, voluptuous | 胸部非常丰满，E罩杯 |
| F | very large F-cup bust, full and voluptuous | 胸部极丰满，F罩杯 |
| G | extremely large G-cup bust, very full | 胸部超大，G罩杯 |

### hair (female)
| Key | v4.5 | v5.0 |
|-----|------|------|
| long_straight_black | long straight black hair | 黑色长直发 |
| long_wavy_black | long wavy black brown hair | 黑棕色波浪长发 |
| shoulder_black | shoulder-length black hair | 齐肩黑发 |
| long_wavy_brown | long brown wavy hair | 棕色波浪长发 |
| blonde_wavy | blonde wavy hair | 金色波浪卷发 |
| short_black | short black hair | 黑色短发 |
| curly_natural | curly natural hair | 自然卷曲短发 |

## Body Parameters — Male

### build
| Key | v4.5 | v5.0 |
|-----|------|------|
| lean | lean slim figure | 身材精瘦 |
| medium | medium build with balanced proportions | 身材匀称比例协调 |
| athletic | athletic muscular build | 身材健壮有肌肉线条 |
| stocky | stocky broad build | 身材魁梧宽厚 |
| bulky | large muscular bulky build | 身材壮硕肌肉发达 |

### chest
| Key | v4.5 | v5.0 |
|-----|------|------|
| flat | flat chest | 胸部平坦 |
| defined | defined pectoral muscles | 胸肌有型 |
| muscular | muscular well-developed chest | 胸肌发达 |
| broad | broad thick chest | 胸膛厚实宽阔 |

### facial_hair
| Key | v4.5 | v5.0 |
|-----|------|------|
| none | clean-shaven | 面容干净没有胡须 |
| stubble | light stubble | 留有轻微的胡茬 |
| short | short trimmed beard | 修剪整齐的短胡 |
| full | full thick beard | 浓密的络腮胡 |
| mustache | mustache | 八字胡 |

### hair (male)
| Key | v4.5 | v5.0 |
|-----|------|------|
| short_black | short black hair | 黑色短发 |
| buzz_cut | buzz cut hair | 寸头 |
| side_part | side-parted styled hair | 侧分发型 |
| slicked_back | slicked back hair | 背头 |
| curly | curly hair | 卷发 |
| long | long hair | 长发 |

## Shared Body Parameters (Both Genders)

### shoulders
narrow / medium / wide (male also: very_wide)

### waist
narrow / medium / wide

### hips
narrow / medium / wide

### legs
long / medium / toned

### skin
fair / warm / tan / dark / olive

## Default Body Profiles

**Female**: build=slim, bust=C, shoulders=medium, waist=narrow, hips=medium, legs=long, skin=warm, hair=long_straight_black

**Male**: build=athletic, chest=defined, shoulders=wide, waist=medium, hips=narrow, legs=medium, skin=warm, facial_hair=none, hair=short_black

## Base Prompt Construction

### v4.5 (_build_base_v45)
```
standing in a natural relaxed pose facing the camera,
full body portrait framed with margin above head and below feet,
camera at waist height shooting upward slightly,
entire body visible from head to feet on the floor, feet not cropped,
{clothing}, {foot_desc},
white studio background, soft even lighting, {realism_suffix}
```

### v5.0 (_build_base_v50)
```
这个人物{clothing}，{foot_desc}，以自然放松的姿势正面站立，面朝镜头。
全身照，画面上方留出头顶空间，下方留出脚底空间，从头顶到脚部完整入镜，脚部不被裁切。
相机在腰部高度略微仰拍。白色简洁的摄影棚背景，柔和均匀的灯光。
{realism_suffix}
```

## Scene Presets

| Key | Description |
|-----|-------------|
| modern_apartment | 在简约现代的白色公寓客厅中，自然光从落地窗照入 |
| bedroom | 在温馨的卧室中，柔和的暖光氛围 |
| street | 在城市街道上，阳光明媚的户外环境 |
| mall | 在明亮的商场走廊中，时尚购物环境 |
| parking | 在地下停车场中，冷色调灯光 |
| cafe | 在精致的咖啡馆中，暖色调装饰 |
| studio | 在专业摄影棚中，纯白背景，柔和打光 |
| garden | 在绿意盎然的花园中，自然光线 |
| hallway | 在现代公寓走廊中，简洁明亮 |
| mirror | 对着卧室全身镜，镜像自拍视角 |
| rooftop | 在城市天台上，傍晚金色光线 |

## Camera Styles

| Key | Prompt |
|-----|--------|
| vlog | 手持vlog镜头感，竖屏9:16构图 |
| pro | 专业摄影棚级别运镜，稳定流畅，竖屏9:16构图 |
| static | 固定机位，模特走入画面，竖屏9:16构图 |

## Dialogue Styles (Gender-Aware)

| Style | Female | Male |
|-------|--------|------|
| natural | 语气自然亲切，像在跟闺蜜视频通话。说话有停顿、有喘息、偶尔磕巴自我纠正，真实感强。 | 语气自然随和，像在跟朋友聊天推荐好物。说话直接但不生硬，偶尔停顿思考，真实感强。 |
| professional | 语气专业自信，像品牌代言人。吐字清晰，节奏稳定。 | 语气专业沉稳，像品牌代言人。吐字清晰，从容有力。 |
| enthusiastic | 语气兴奋热情，像发现了宝藏。语速偏快，情绪感染力强。 | 语气热情有感染力，像发现好东西迫不及待分享。语速适中但有力。 |

FILE:references/prompt-assembly.md
# Seedance Prompt Assembly Rules

> **Role:** Defines the composition ORDER and FORMAT for assembling Seedance 2.0 prompts from dialogue/action/scene components.
> Dialogue content (scripts, openings, closings, actions): see [dialogue-library.md](dialogue-library.md).
> Load at: Step 4-6 (assembling prompt and SOP).

## Prompt Assembly Order

```
一位{model_ref}年轻{gender_word}穿着 @图片1 中的服装，{scene_desc}。
{style_transfer (if stylized ref)}
{pronoun}{action}，
对着镜头说：「{opening}{dialogue_core}{selling_closing}」
{dialogue_style_instruction}
Do not alter clothing pattern, color, texture or style.
{camera}。
音频要求：全程只有模特一个人的清晰人声，不出现第二个人的声音或对白。
背景有符合场景的自然环境音（如户外有车声鸟鸣、室内有空调低鸣），音量不超过人声的10%。
视觉要求：全程保持中景到中近景，不要切到手部或脚部的特写镜头，避免手指变形问题。
模特展示服装细节时始终使用右手操作，避免左右手切换导致的镜像翻转。
全程画面中只有模特一人，不出现其他人物。
```

## Variable Resolution

| Variable | Source | Example |
|----------|--------|---------|
| `{model_ref}` | If has_model_ref: "面容和身材参考@图片2的"; if stylized: "身材比例和姿态参考@图片2（忽略动画风格）的" | 面容和身材参考@图片2的 |
| `{gender_word}` | "女性" or "男性" | 女性 |
| `{scene_desc}` | SCENE_PRESETS[key] or custom text | 在简约现代的白色公寓客厅中，自然光从落地窗照入 |
| `{pronoun}` | "她" or "他" | 她 |
| `{action}` | From dialogue-library.md: ACTION_DEMEANOR + GARMENT_ACTIONS | 面朝镜头表情生动自然地展示服装，右手拉起裙摆展示面料... |
| `{opening}` | From dialogue-library.md: OPENINGS[(gender, audience)][lang] | 姐妹们你们快看... |
| `{dialogue_core}` | From dialogue-library.md: DIALOGUE_CORE[garment][gender][lang] | 哇，不是，我真的没想到... |
| `{selling_closing}` | From dialogue-library.md: SELLING_CLOSINGS[(audience, garment)][lang] | 超显腿长，闭眼入。 |
| `{dialogue_style_instruction}` | From dialogue-library.md: STYLE_INSTRUCTIONS[style][gender] | 语气自然亲切... |
| `{camera}` | CAMERA_PROMPTS[style] | 手持vlog镜头感，竖屏9:16构图 |

## Custom Dialogue Handling

When user provides custom dialogue (overrides DIALOGUE_CORE):
1. Still wrap with OPENING + custom text + SELLING_CLOSING
2. Append fusion instruction: "（以上为核心台词要点，请以自然口语化的方式说出，加入适当停顿、语气词和过渡，不要原封不动念稿。）"
3. Actions switch to adaptive mode (sync with content, not pre-choreographed)

## Multi-Segment Chaining (duration > 15s)

### Constants
- CHARS_PER_SECOND = 4 (Chinese speaking rate)
- TARGET_SEGMENT_CHARS = 55 (~13.5s)
- MIN_SEGMENT_CHARS = 30 (~7.5s)
- MAX_SEGMENT_CHARS = 65 (~16s)

### Split Algorithm
1. If total spoken chars <= 65: single segment
2. Split at sentence boundaries (。！？…)
3. Accumulate until > 65 chars, then flush
4. If last segment < 30 chars: merge with previous

### Segment Structure
- **Segment 0** (is_base=true): full prompt with scene + @image refs + dialogue part 1
- **Segments 1+** (is_base=false): extend prompt only:

```
继续上一段的内容，保持相同的人物、服装、场景和说话风格。
模特接着说：「{segment_dialogue}」
{dialogue_style_instruction}
动作与台词内容同步配合，始终使用右手操作。
保持中景到中近景，不切手部特写。
全程只有模特一个人的声音，环境音延续上一段。
```

### Duration Calculation
```
scale = total_duration / sum(segment.estimated_seconds)
per_segment = max(5, min(15, round(estimated_seconds * scale)))
```

## SOP Template (Single Segment)

```markdown
# Seedance 视频生成操作指南
## 素材文件
- 衣服商品图（图片1）：{garment_path}
- 模特参考图（图片2）：{model_path}
## 操作步骤
1. 打开即梦 https://jimeng.jianying.com
2. 点击「视频生成 Seedance 2.0」
3. 点击 + 按钮，依次上传 2 张图片（顺序重要：图片1=衣服, 图片2=模特）
4. 粘贴 prompt
5. 确认「输出声音」已开启
6. 设置：模式=参考生成, 分辨率={resolution}, 时长={duration}秒, 数量=4条
7. 生成 -> 从4条中挑选最佳 -> 下载
## 质量检查
- [ ] 衣服颜色/面料/版型与商品图一致
- [ ] 对白清晰可听、语调自然
- [ ] 嘴型与语音基本同步
- [ ] 动作自然有真人感
- [ ] 面部稳定表情生动
```

## SOP Template (Multi-Segment Chain)

```markdown
# Seedance 分段接龙操作指南
## 总览：共 {n} 段，总时长约 {total}秒
## 第 1 段：初始生成
1-5. 同单段 SOP
6. 不要下载！留在平台准备延长
## 第 2+ 段：延长生成
1. 点击上一段结果的「延长」按钮
2. 粘贴延长 prompt
3. 设置时长 -> 生成 -> 挑选
4. 最后一段下载完整视频
## 质量检查
- [ ] 衣服全程一致
- [ ] 面部全程一致（无漂移）
- [ ] 段间对白自然衔接
- [ ] 总时长接近预期
```

FILE:references/seedream-api.md
# Seedream API Call Specifications

> **Role:** Defines the exact HTTP request format for Seedream 4.5/5.0 image generation API.
> Load at: Step 3 (calling Seedream API). Not needed if user only wants prompt without image generation.
> It does NOT replace execution. These are API specs, not prebuilt responses.

## Endpoint

```
POST {ARK_API_BASE}/api/v3/images/generations
```

Default base: `https://ark.cn-beijing.volces.com`

## Headers

```
Authorization: Bearer {ARK_API_KEY}
Content-Type: application/json
```

## Version Differences

### Seedream 5.0

```json
{
  "model": "{endpoint_id}",
  "prompt": "Chinese natural language description...",
  "size": "2K",
  "response_format": "url",
  "watermark": false,
  "sequential_image_generation": "disabled",
  "stream": false,
  "seed": -1
}
```

- Output: 2048x2048 square image (URL response)
- Negative prompt: IGNORED (5.0 uses internal Chain-of-Thought)
- Guidance scale: IGNORED
- Prompt style: Natural Chinese language, describe desired outcome
- Cost: ~0.22 CNY per image

### Seedream 4.5

```json
{
  "model": "{model_id}",
  "prompt": "English keyword-stacking style...",
  "size": "{width}x{height}",
  "response_format": "b64_json",
  "watermark": false,
  "seed": -1,
  "negative_prompt": "blurry, extra fingers, distorted hands, watermark, text overlay, cropped feet, cut off at ankles, partial body",
  "guidance_scale": 0
}
```

- Output: specified resolution (base64 response)
- Minimum pixel count: 2560 * 1440 = 3,686,400 pixels
- If below minimum, auto-scale up: `scale = (MIN_PIXELS / total) ^ 0.5`, round to multiple of 8
- For 720x1280 target: generates at ~1440x2560, then center-crops
- Prompt style: English keyword stacking with technical terms
- Cost: ~0.32 CNY per image
- guidance_scale: avoid passing by default (causes skin artifacts)

## Default Negative Prompt (4.5 only)

```
blurry, extra fingers, distorted hands, watermark, text overlay, cropped feet, cut off at ankles, partial body
```

WARNING: Heavy negative prompts (especially "plastic skin", "real person face") cause patchy shadow artifacts on skin. Keep minimal.

## Post-Processing: Crop to Ratio

After receiving the raw image:
1. Check if raw aspect ratio matches target (720:1280 = 9:16)
2. If mismatch > 0.01: center-crop to target ratio
   - If raw is wider: crop horizontal center
   - If raw is taller: crop vertical center
3. NO downscaling — keep highest resolution for Seedance upload

Output resolutions:
- 4.5: ~1440x2560 (for 9:16 target)
- 5.0: ~1152x2048 (cropped from 2048x2048 square)

## Timeout

300 seconds (5 minutes)

## Error Handling

- Missing ARK_API_KEY: RuntimeError
- HTTP error: raise with status code
- No image data in response: RuntimeError
- All errors wrapped as: `RuntimeError(f"Seedream generation failed: {e}")`