📄 How do I use the Skills feature?

In the current system, Skills are an Agent skill package integration method built on top of Guid AI's open capabilities. They are suitable for directly calling the platform's image generation, video generation, and audio generation capabilities inside Agent conversation environments such as Claude, Cursor, and Codex, without manually writing HTTP API requests.

The current official skill package name is: guid-ai-skills

Note: If you want to integrate capabilities into your own website, backend system, app, or automation process, use the V1 Open API (/v1/*) first. If you want to integrate with a client that supports MCP, you can also choose the MCP service (/mcp). Skills are more suitable for scenarios where you want to use multimodal capabilities directly inside Agent conversations.

1. What Can Skills Do?

Skills in the current system mainly cover the following capabilities:

Capability Category	Supported	Description
Model list query	✅	View currently available models
Text-to-image	✅	Start image generation directly in an Agent conversation
Standard video generation	✅	Supports task creation, polling until completion, and result download
guidai multimodal video	✅	Supports video generation scenarios with multiple modes
Voice query / text-to-speech	✅	Call TTS in a conversation
Text conversation API	❌	Skills do not provide Chat / Completions / Responses. The conversation itself is provided by the Agent

In one sentence: Skills help the Agent call the platform's image, video, and audio capabilities, but they do not replace the chat model itself.

2. Which Scenarios Are Suitable for Skills?

We recommend using Skills in the following scenarios:

You usually work in Agents such as Claude, Cursor, or Codex, and want to generate images, videos, or speech directly through natural language.
You do not want to study integration details such as API parameters, signatures, polling, and file downloads yourself.
You want to use content generation capabilities as part of an Agent workflow.

If you have the following needs, Skills are not recommended as the first choice:

Backend system integration, batch calls, or business API development: use the V1 Open API
Integration with MCP-capable clients using a standard protocol: use the MCP service
Calling text conversation capabilities: use the Agent itself directly, or call /v1/chat/completions

3. Skills Usage Flow

Step 1: Prepare an API Key

First create an available API Key in the platform backend. The format is usually:

sk-xxxxxxxx

After creation, save it securely. Skills will use this key later to call platform capabilities.

Step 2: Obtain and Install the Skill Package

The skill package name used by the current system is:

guid-ai-skills

Installation method:

Obtain the guid-ai-skills.zip package.
Extract it into the Skills directory of the Agent you use.
After extraction, the directory should contain at least the SKILL.md file.

Example directory structure:

guid-ai-skills/
├─ SKILL.md
├─ .env
└─ ...

Common notes:

Platform	Installation Notes
Claude-like Agents	Place it in the Skills directory supported by that client
Cursor	Place it in a project-level or user-level Skills directory, depending on the client version
Codex-like Agents	Place it in the corresponding Skills / agent skills directory
Other Agents	Refer to each platform's documentation for Skills installation

Skills directory locations vary between clients. If you cannot find the directory, check the official instructions for the corresponding Agent first.

Step 3: Configure Environment Variables

Fill in the following configuration in guid-ai-skills/.env, or configure them as system environment variables:

GUIDAI_BASE_URL=https://guidai.lychessclub.work
GUIDAI_API_KEY=sk-xxx

Field descriptions:

Variable Name	Required	Description
`GUIDAI_BASE_URL`	Yes	Guid AI gateway address. Do not include path suffixes such as `/v1`
`GUIDAI_API_KEY`	Yes	The API Key you created on the platform

After configuration is complete, we recommend closing and reopening the Agent to ensure the skill package loads the latest environment variables.

Step 4: Use Directly in Conversation

After installation and configuration are complete, you can directly describe your requirement in an Agent conversation. The Agent will automatically call the corresponding capability according to the workflow defined in SKILL.md.

For example, you can directly enter:

List the currently available image models for me
Generate an illustration of a sunset beach with a cinematic feel, 16:9
Generate an 8-second video based on this reference image
Convert this copy into a female voice audio

If configured correctly, the Agent will automatically complete model query, task submission, polling, or result retrieval, without requiring you to manually assemble API requests.

4. How Should You Choose Between Skills, API, and MCP?

Method	Suitable For	Description
`Skills`	Agent users such as Claude, Cursor, and Codex	Suitable for directly calling image, video, and audio capabilities in chat conversations
`V1 Open API`	Developers, backends, and third-party systems	Suitable for system integration, batch calls, and API development
`MCP`	Clients that support the MCP protocol	Suitable for integration through the standard tool protocol

Simple decision guide:

Want to generate images, videos, or speech in one sentence inside an Agent: use Skills
Want to write code to integrate with the platform yourself: use the V1 Open API
Want to use the MCP standard protocol: use MCP

5. Common Troubleshooting

Issue	Possible Cause	Solution
Skills are not visible after installation	The skill package directory is wrong, or the client has not reloaded	Check whether it has been extracted to the correct Skills directory and restart the Agent
Authentication fails during calls	`GUIDAI_API_KEY` is missing, incorrect, or expired	Recheck the API Key in `.env` and confirm the key status is normal
Wrong call address / cannot connect	`GUIDAI_BASE_URL` is configured incorrectly	Make sure the gateway root address is filled in without extra paths
Models can be queried but content cannot be generated	The current key has restricted permissions, insufficient quota, or the model is unavailable	Check token quota, model binding restrictions, and upstream model status
Want to use Skills for text conversation	Skills themselves do not cover text conversation APIs	For text Q&A, use the Agent directly or call `/v1/chat/completions`
Are Skills and MCP the same thing?	No	Skills are a skill package method, while MCP is a standard protocol integration method

6. Recommended Usage Suggestions

We recommend creating a separate API Key for Skills to make usage tracking and permission isolation easier.
If you often do multimodal creation inside Agents, use Skills first because the integration threshold is the lowest.
If you later need to connect the same capabilities to a business system, switch to the /v1/* Open API after becoming familiar with the capabilities.
If your team already has an MCP tool system, you can further evaluate whether to integrate through /mcp.