Quick Setup for AI Agents
For AI agents. After reading this guide, you can independently complete the installation, credential configuration, and availability verification of the Knowledge Studio Skill. Once installed and restarted, your agent can retrieve and answer questions from your knowledge base during conversations.
Prerequisites
All three requirements below must be satisfied before the Skill can function properly:
- Node.js ≥18 — Download and install
- Bailian Knowledge Base service enabled — Visit the Knowledge Base page, click Enable Now, and wait 1–2 minutes for activation. Without activation, API calls return
403 Forbidden. - DashScope API Key — Create one on the API Key page. Format:
sk-xxx. Note: Keys starting withsk-sp-xxxare Coding Plan Keys and are not supported for knowledge base services.
Install the Skill
Run the following command in your terminal (replace --agent with your specific agent):
npx skills add aliyun/alibabacloud-aiops-skills \
--skill alibabacloud-bailian-rag-knowledgebase \
--agent claude-code \
-y --full-depth
Supported agents:
| Agent | --agent value |
|---|---|
| Claude Code | claude-code |
| Qoder | qoder |
| Qwen Code | qwen-code |
| Cursor | cursor |
| Codex | codex |
| Gemini CLI | gemini-cli |
| GitHub Copilot | github-copilot |
| OpenClaw | openclaw |
Installation scope: By default, installs into the current project. Add -g for global installation (available across all projects).
Configure the API Key (Critical Step)
The Skill's retrieval script invokes the DashScope API using Authorization: Bearer, requiring a valid API Key. The script automatically retrieves the key in the following priority order:
dashscope.api_keyfrom the current profile in Alibaba Cloud CLI config file (~/.aliyun/config.json)- Environment variable
DASHSCOPE_API_KEY - Auto-created by Alibaba Cloud CLI if available
Option A: Environment Variable (Simplest)
Add the following line to your shell configuration file (~/.zshrc or ~/.bashrc), or set it temporarily in the current session:
export DASHSCOPE_API_KEY=sk-xxxxxxxx
Option B: Auto-create via Alibaba Cloud CLI (No manual key management required)
Ideal if you prefer not to handle keys manually. The Skill auto-creates and writes the key upon its first invocation after installation:
# 1. Install Alibaba Cloud CLI (macOS example)
brew install aliyun-cli
# 2. Install ModelStudio plugin
aliyun plugin install --names aliyun-cli-modelstudio --enable-pre
# 3. Configure credentials (AccessKey/SecretKey or RAM role)
aliyun configure
RAM users require the AliyunBailianFullAccess system policy, or a custom policy granting permissions for modelstudio:ListWorkspaces, modelstudio:CreateApiKey, and modelstudio:DeleteApiKey.
WarningAPI keys are sensitive credentials. Agents must never output them in plain text, hardcode them, or embed them directly in scripts. Credentials should be configured solely by the user via shell environment variables or Alibaba Cloud CLI. The agent only needs to verify that credentials are ready—the Skill script reads them automatically without exposing or handling the key value.
Verify Installation
# Confirm Skill is installed
npx skills ls # For current project
npx skills ls -g # Globally
Alternatively, check whether the file exists: .<agent>/skills/alibabacloud-bailian-rag-knowledgebase/SKILL.md (e.g., .claude/skills/...).
Restart Your Agent Client
ImportantThe Skill only loads after restarting your agent client. Since agents cannot restart themselves, please instruct users to manually restart Claude Code / Cursor / Qoder, etc.
How to Use After Setup
After restarting, simply ask natural-language questions in chat—the agent automatically invokes the Skill:
- "List all knowledge bases under my account."
- "Search the 'Product Documentation' knowledge base: What authentication methods are supported?"
The Skill first lists available knowledge bases (returning id and name), then retrieves relevant chunks matching your question and synthesizes answers, citing sources at the end (knowledge base name; document name; section name).
Troubleshooting
| Symptom | Cause | Resolution |
|---|---|---|
401 InvalidApiKey | API Key missing or invalid | Verify DASHSCOPE_API_KEY or dashscope.api_key in ~/.aliyun/config.json |
403 Forbidden / Service not activated | Knowledge Base service not enabled | Go to the Knowledge Base page in the console and click Enable Now |
| Agent fails to recognize the Skill | Not restarted / incorrect directory / missing SKILL.md | Restart the client and verify existence of .<agent>/skills/alibabacloud-bailian-rag-knowledgebase/SKILL.md |
npx skills add fails | Node version too low / network issue | Confirm Node ≥18 and retry |
Additional Resources
- Interactive installation commands are available on the console's Service Channels page
- Alibaba Cloud Skills User Guide