felo-superAgent

Files (7)

• LICENSE
• README.md
• SKILL.md
• clawhub.json
• githubclaw.json
• run_style_library.mjs · scripts/
• run_superagent.mjs · scripts/

SKILL.md (first lines)

# Felo SuperAgent Skill

## Constraints (MUST READ FIRST)

These rules are mandatory. Violating any of them will produce incorrect behavior.

0. **NEVER treat image/product descriptions as prompt-writing or prompt-optimization tasks.** If the user's message contains a visual description — regardless of phrasing such as "我的提示詞為", "my prompt is", "生成一張", "generate a photo of", "create a product image" — you MUST call the felo-superAgent API immediately to generate the actual image. Do NOT:
   - Rewrite, refine, or "improve" the description as a text output
   - Suggest keywords or aspect ratios as your final response
   - Write a better prompt to result.md instead of calling the API
   - Describe what you would do instead of doing it

   The ONLY correct response to an image/product generation request is to **execute the skill** (run `run_superagent.mjs` with `--skill-id ecommerce-product-image` or `logo-and-branding`) and **output the resulting image URLs**. If you find yourself writing text about the image instead of calling the API, stop and call the API.

1. **ALWAYS use `--json` flag.** The script MUST run in JSON mode (`--json`). In Claude Code's Bash tool, stdout is always captured — it never streams directly to the user. JSON mode returns the full answer in a structured response that Claude can then output as text. State IDs are extracted from the JSON response fields `thread_short_id` and `live_doc_short_id`.

2. **ALWAYS output the answer and all tool results.** After the script finishes: (a) print `data.answer` verbatim as your response text — do NOT summarize or paraphrase; (b) render every entry in `data.image_urls` as a Markdown inline image `![title](url)` immediately after the answer — NEVER skip image URLs; (c) list any entries in `data.discoveries`, `data.documents`, `data.ppts`, `data.htmls`.

3. **`--live-doc-id` is optional for the first call.** `run_superagent.mjs` works without `--live-doc-id` — the API will auto-assign a LiveDoc and return its `live_doc_short_id` in the JSON response. On the FIRST call in a session (no live_doc_id known yet), you MAY omit `--live-doc-id`. After the first call, always reuse the returned `live_doc_short_id` (see Constraint #4 and Step 2).

4. **Reuse `live_doc_id` from ANY source.** If you already have a `live_doc_id` from any previous operation in this session — whether from a prior SuperAgent call's JSON response (`data.live_doc_short_id`), user-provided input, or any other skill — use it directly. Do NOT try to fetch LiveDoc list via felo-livedoc (it may not be installed). Only omit `--live-doc-id` when you truly have no ID from any source. (Note: `live_doc_id` corresponds to the API field `live_doc_short_id` and the `[state]` output key `live_doc_short_id`.)

5. **One LiveDoc per session.** All conversations within a session MUST use the same `--live-doc-id`. Do NOT create a new LiveDoc unless the user explicitly asks to "open a new canvas" / "start a new LiveDoc" / "create a new workspace".

6. **Default behavior is follow-up, not new conversation.** After the first question, every subsequent user message is a follow-up. You MUST pass `--thread-id` from the previous response. Only omit `--thread-id` (to start a new thread on the same LiveDoc) when:
   - The user explicitly says "new topic" / "change subject" / "start over"
   - The user's intent requires a specific `--skill-id` (e.g., tweet writing, logo design, product image) and the current thread was not created with that skill — because `--skill-id` only takes effect in new conversations

7. **Always persist state.** After every call, extract `thread_short_id` and `live_doc_id` from the stderr `[state]` line (where `live_doc_id` is output as `live_doc_short_id`). Use them in the next call. Losing these IDs breaks conversation continuity.

8. **Skill ID selection (New Conversations Only).** When creating a new conversation (no `--thread-id`), analyze the user's intent and determine if it matches one of the supported skill IDs:

   **Available skill IDs:**
   - `twitter-writer` — For composing, drafting, or posting tweets/X posts
   - `logo-and-branding` — For creating logos, brand designs, or visual identity
   - `ecommerce-product-image` — For generating product images for e-commerce use

   **Selection logic:**
   - If the user explicitly requests a specific skill-id, use their specified value
   - If the user's intent clearly matches one of the above, pass `--skill-id` with that value
   - If none of the above match, do NOT pass `--skill-id` (general conversation mode)
   - `--skill-id` is only effective when creating a new conversation. It is ignored in follow-up mode (`--thread-id`).

9. **Brand style selection for skill-based new conversations.** When starting a NEW conversation that uses a skill ID (`twitter-writer`, `logo-and-branding`, `ecommerce-product-image`), you MUST fetch the style library and let the user choose a style BEFORE calling `run_superagent.mjs`. The chosen style is passed via `--ext '{"brand_style_requirement":"<style_string>"}'`. See Step 4.5 for the full procedure.

   - The style string is the exact text block output by `run_style_library.mjs` for that entry. Fields vary by category:
     - **TWITTER**: `Style name` + `Style labels` (language-aware) + `Style DNA` + `Cover file ID` (omitted if null)
     - **IMAGE**: `Style name` + `Style labels` + `Style DNA` or `Cover file ID` depending on what is present
   - Use the category that matches the skill: `TWITTER` for `twitter-writer`, `IMAGE` for `logo-and-branding` and `ecommerce-product-image`.
   - Always pass `--accept-language` to `run_style_library.mjs` so labels are returned in the user's language.
   - If the user has already specified a style (by name or by pasting the style block), skip the fetch and use their choice directly.
   - If the style library returns no entries, proceed without `--ext`.
   - `--ext` is only valid for new conversations. Never pass it in follow-up mode (`--thread-id`).

10. **Never create a new LiveDoc casually.** Reuse the existing one. The only exception is an explicit user request for a new canvas/workspace.

## When to Use

Trigger this skill when users want:

- **SuperAgent conversation:** AI conversation with Felo SuperAgent, with real-time streaming output
- **Continuous conversation:** Multi-turn Q&A on a persistent LiveDoc canvas
- **Logo & branding:** Create logos or brand designs (auto-selects `logo-and-branding` skill)
- **E-commerce images:** Generate product images for e-commerce use (auto-selects `ecommerce-product-image` skill). **This includes any request where the user provides a visual description and wants an AI-generated product photo** — e.g., "生成一張…產品照片", "generate a photo of a leather wallet", "幫我生成一張商品圖"
- **Image generation from description:** Any request where the user describes a scene, product, or visual concept and expects an actual AI-generated image as output — NOT a text description or prompt refinement
- **Tool-augmented answers:** Responses that may include image generation, document creation, PPT generation, or Twitter/X search
- **Streaming responses:** Real-time answer generation with Server-Sent Events (SSE)

**⚠️ IMPORTANT — Do NOT misinterpret image requests as prompt-writing tasks.** If the user provides a visual description and asks to "生成"/"generate"/"create" an image or photo, ALWAYS call the felo-superAgent API with `--skill-id ecommerce-product-image`. Do NOT respond with refined text prompts or suggestions — execute the skill and output the generated image URLs.

**Trigger words:**

- English: superagent, super agent, stream chat, streaming conversation, livedoc conversation, continuous chat, follow-up question, create a logo, brand design, product image, e-commerce image, generate image, generate photo, product photo, product shot
- 繁體中文：超級助手、串流對話、連續對話、追問、設計 logo、品牌設計、電商圖片、商品圖片、商品照片、產品照片、產品圖片、生成圖片、生成照片、生圖、AI 生圖、AI 作圖、製作圖片、電商產品圖
- 简体中文：超级助手、流式对话、连续对话、追问、设计 logo、品牌设计、电商图片、商品图片、商品照片、产品照片、产品图片、生成图片、生成照片、生图、AI 生图
- Japanese (romaji): suupaa eejento, sutoriimingu kaiwa, keizoku kaiwa, rogo sakusei, shouhin gazou, gazou seisei, shouhin shashin

**Explicit commands:** `/felo-superagent`, "use felo superagent", "felo superagent"

**Do NOT use for:**

- Tweet/X post writing of any kind (use `felo-twitter-writer` instead)
- Simple one-off Q&A or real-time information queries (prefer `felo-search`)
- Web page content fetching only (use `felo-web-fetch`)
- PPT/slide generation only (use `felo-slides`)
- LiveDoc knowledge base management only (use `felo-livedoc`)
- Twitter/X search only (use `felo-x-search`)

## Setup

### 1. Get Your API Key

1. Visit [felo.ai](https://felo.ai) and log in (or register)
2. Click your avatar in the top right corner → Settings
3. Navigate to the "API Keys" tab
4. Click "Create New Key" to generate a new API Key
5. Copy and save your API Key securely

### 2. Configure API Key

The scripts (`run_superagent.mjs`, `run_style_library.mjs`) read the API key **only from the `FELO_API_KEY` environment variable**. The `felo config set` CLI command writes to `~/.felo/config.json` which these scripts do NOT read — environment variable is the only supported method.

**Linux/macOS:**
```bash
export FELO_API_KEY="your-api-key-here"
```

For permanent configuration, add to your shell profile (`~/.bashrc` or `~/.zshrc`):
```bash
echo 'export FELO_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc
```

**Windows (PowerShell):**
```powershell
$env:FELO_API_KEY="your-api-key-here"
```

**Windows (CMD):**

From duotify/GitHubClawToolkit, MIT.

More from duotify/GitHubClawToolkit