felo-livedoc

name	felo-livedoc
description	Manage Felo LiveDocs (knowledge bases) and their resources. Use when users want to create, manage, or query knowledge bases, upload documents, add URLs, or perform semantic retrieval over a knowledge base. Explicit commands: /felo-livedoc.

Felo LiveDoc Skill

When to Use

Trigger this skill when users want to:

• Create/manage knowledge bases: Create, list, update, or delete LiveDocs
• Add resources: Upload documents, add URLs, or create text documents in a LiveDoc
• Semantic retrieval: Search across knowledge base resources using natural language queries
• Route resources: Find relevant resource IDs by query for targeted retrieval
• Resource management: List, view, or delete resources within a LiveDoc
• README management: Get, create, update, append, or delete a LiveDoc's README
• Task management: Create, update, delete tasks; add comments; view change history

Trigger words:

• English: knowledge base, livedoc, live doc, upload document, add URL, semantic search, retrieve, knowledge retrieval, route resources, readme, task, task management, comment
• 简体中文: 知识库, 文档库, 上传文档, 添加链接, 语义检索, 知识检索, 任务, 任务管理, 评论

Explicit commands: /felo-livedoc, "livedoc", "felo livedoc"

Do NOT use for:

• General web search (use felo-search)
• PPT generation (use felo-slides)
• SuperAgent conversations (use felo-superAgent)

Setup

1. Get Your API Key

1. Visit 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

Set the FELO_API_KEY environment variable:

Linux/macOS:

export FELO_API_KEY="your-api-key-here"

Windows (PowerShell):

$env:FELO_API_KEY="your-api-key-here"

How to Execute

When this skill is triggered, execute the livedoc script using the Bash tool:

LiveDoc Management

Create a LiveDoc:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs create --name "KB Name" --description "Description"

List LiveDocs:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs list
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs list --keyword "search term"

Update a LiveDoc:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs update SHORT_ID --name "New Name" --description "New Desc"

Delete a LiveDoc:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs delete SHORT_ID

Resource Management

Add a text document:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs add-doc SHORT_ID --title "Doc Title" --content "Document content here"

Add URLs (max 10, comma-separated):

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs add-urls SHORT_ID --urls "https://example.com,https://example.org"

Each URL can also be passed as a url:title pair using the --url-titles option, or by providing a JSON array. The API accepts both plain strings and {"url": "...", "title": "..."} objects — the script passes them through as-is when using --json mode. To add URLs with custom titles, use the JSON flag and construct the body manually, or rely on the auto-title from the page.

Upload a file:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs upload SHORT_ID --file ./document.pdf
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs upload SHORT_ID --file ./document.pdf --convert

List resources:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs resources SHORT_ID

Get a single resource:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs resource SHORT_ID RESOURCE_ID

Delete a resource:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs remove-resource SHORT_ID RESOURCE_ID

Update a resource (title/snippet/thumbnail):

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs update-resource SHORT_ID RESOURCE_ID --title "New Title"
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs update-resource SHORT_ID RESOURCE_ID --snippet "New summary" --thumbnail "https://example.com/thumb.png"

Update resource content (ai_doc type only — also auto-updates snippet from first 2000 bytes):

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs update-resource-content SHORT_ID RESOURCE_ID --content "New content here"

Semantic Retrieval

Route relevant resources by query:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs route SHORT_ID --query "your search query"
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs route SHORT_ID --query "your search query" --max-resources 5

Search across all resources (auto-routes):

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs retrieve SHORT_ID --query "your search query"

Search within specific resources:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs retrieve SHORT_ID --query "your search query" --resource-ids "id1,id2,id3"

Resource File & Content

Download resource source file (get presigned URL):

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs download SHORT_ID RESOURCE_ID
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs download SHORT_ID RESOURCE_ID --expires-in 7200

Get extracted text content of a resource:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs content SHORT_ID RESOURCE_ID

PPT page deep retrieval:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs ppt-retrieve SHORT_ID --resource-id RESOURCE_ID --page-number 3 --query "pricing information"
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs ppt-retrieve SHORT_ID --resource-id RESOURCE_ID --page-number 3 --query "pricing information" --max-chunk 5

README Management

Get README:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs get-readme SHORT_ID

Create or replace README:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs update-readme SHORT_ID --content "# My KB\n\nThis is the README."

Append to README:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs append-readme SHORT_ID --content "\n\n## New Section\n\nAdditional content."

Delete README:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs delete-readme SHORT_ID

Task Management

List tasks (with optional filters):

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs tasks SHORT_ID
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs tasks SHORT_ID --status 0
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs tasks SHORT_ID --labels "docs,priority-high"

Create a task:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs create-task SHORT_ID --title "Write docs" --status 0 --sort 0
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs create-task SHORT_ID --title "Write docs" --status 0 --sort 0 --description "API docs" --labels "docs"
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs create-task SHORT_ID --title "Write docs" --operated-by "claude-code"

Task status values: 0=TODO, 1=IN_PROGRESS, 2=DONE

Update a task (partial update):

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs update-task SHORT_ID TASK_ID --status 1
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs update-task SHORT_ID TASK_ID --title "New title" --labels "docs,done"
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs update-task SHORT_ID TASK_ID --status 2 --operated-by "claude-code"

Delete a task:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs delete-task SHORT_ID TASK_ID

List task records (comments + change history):

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs task-records SHORT_ID TASK_ID
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs task-records SHORT_ID TASK_ID --record-type comment

Add a comment to a task:

node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs add-task-comment SHORT_ID TASK_ID --content "This is a comment."
node ~/.agents/skills/felo-livedoc/scripts/run_livedoc.mjs add-task-comment SHORT_ID TASK_ID --content "This is a comment." --operated-by "claude-code"

Options

All commands support:

• --json or -j — output raw JSON response
• --timeout <ms> or -t <ms> — request timeout in milliseconds (default: 60000)

Parse and Format Response

The API returns JSON with this structure:

{
  "status": "ok",
  "message": "success",
  "data": { ... }
}

LiveDoc object:

• short_id — unique identifier (use this for all operations)
• name — LiveDoc name
• description — LiveDoc description
• is_shared — true if this LiveDoc was shared with you (not owned by you)
• created_at / modified_at — timestamps

Resource object:

• id — resource identifier
• title — resource title
• resource_type — type (web, ai_doc, file, etc.)
• status — processing status
• snippet — content preview

Retrieve result:

• id — resource ID
• title — resource title
• content — matched content
• score — relevance score (0-1)

Error Handling

Common Error Codes

• INVALID_API_KEY — API Key is invalid or revoked
• LIVEDOC_NOT_FOUND — LiveDoc does not exist
• LIVEDOC_RESOURCE_NOT_FOUND — Resource does not exist
• LIVEDOC_CREATE_FAILED — Failed to create LiveDoc
• LIVEDOC_RESOURCE_UPLOAD_FAILED — File upload failed
• LIVEDOC_RESOURCE_ADD_URLS_FAILED — URL addition failed
• LIVEDOC_RESOURCE_RETRIEVE_FAILED — Semantic retrieval failed
• LIVEDOC_README_GET_FAILED — Failed to get README
• LIVEDOC_README_UPDATE_FAILED — Failed to create or update README
• LIVEDOC_README_DELETE_FAILED — Failed to delete README
• LIVEDOC_TASK_LIST_FAILED — Failed to list tasks
• LIVEDOC_TASK_CREATE_FAILED — Failed to create task
• LIVEDOC_TASK_UPDATE_FAILED — Failed to update task
• LIVEDOC_TASK_DELETE_FAILED — Failed to delete task
• LIVEDOC_TASK_NOT_FOUND — Task does not exist
• LIVEDOC_TASK_RECORD_LIST_FAILED — Failed to list task records
• LIVEDOC_TASK_COMMENT_CREATE_FAILED — Failed to add comment

Missing API Key

If FELO_API_KEY is not set, display this message:

ERROR: FELO_API_KEY not set. Get your API key from https://felo.ai (Settings → API Keys).
Set it with: export FELO_API_KEY="your-key"

Important Notes

• Always use the short_id returned from create/list to reference a LiveDoc
• URL resources are limited to 10 per request
• Use --convert with upload to convert files to searchable documents
• Semantic retrieval returns results sorted by relevance score
• Execute immediately using the Bash tool — don't just describe what you would do