Skip to main content
Getting Started

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.

A self-service setup guide for AI agents. After completing the steps in this document, the Knowledge Studio Skill will be installed, credentials configured, and ready to use—simply restart your agent client to enable knowledge base retrieval and Q&A within conversations.

Prerequisites

All three requirements below must be satisfied before the Skill can function properly:
  1. Node.js ≥18 — Download and install
  2. 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.
  3. DashScope API Key — Create one on the API Key page. Format: sk-xxx. Note: Keys starting with sk-sp-xxx are 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 Codeclaude-code
Qoderqoder
Qwen Codeqwen-code
Cursorcursor
Codexcodex
Gemini CLIgemini-cli
GitHub Copilotgithub-copilot
OpenClawopenclaw
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:
  1. dashscope.api_key from the current profile in Alibaba Cloud CLI config file (~/.aliyun/config.json)
  2. Environment variable DASHSCOPE_API_KEY
  3. 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.
API 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

The 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

SymptomCauseResolution
401 InvalidApiKeyAPI Key missing or invalidVerify DASHSCOPE_API_KEY or dashscope.api_key in ~/.aliyun/config.json
403 Forbidden / Service not activatedKnowledge Base service not enabledGo to the Knowledge Base page in the console and click Enable Now
Agent fails to recognize the SkillNot restarted / incorrect directory / missing SKILL.mdRestart the client and verify existence of .<agent>/skills/alibabacloud-bailian-rag-knowledgebase/SKILL.md
npx skills add failsNode version too low / network issueConfirm Node ≥18 and retry

Additional Resources

Getting Started
Playground
Data Ingestion
Knowledge Service
Cookbook
Integration
Settings, Billing & Limits
Changelog