Skip to main content

Quick Setup for Agents

For AI agents. After reading this, an agent can autonomously install the Knowledge Studio Skill, configure credentials, and verify it works — restart and the KB is queryable in conversation.

Autonomous setup guide for AI agents. Completing this document installs the Knowledge Studio Skill, readies credentials, and — after a client restart — enables Knowledge Base retrieval and Q&A directly in conversation.

Prerequisites

All three are required before the Skill can actually call the API:
  1. Node.js ≥18 — download
  2. Bailian Knowledge Base service activated — open the Knowledge Base page, click "Activate Now", wait 1–2 minutes. Without it, calls return 403 Forbidden
  3. DashScope API Key — create on the API Key page, format sk-xxx. Note: sk-sp-xxx is a Coding Plan Key and is not supported for Knowledge Base services

Install the Skill

Run in a terminal (replace --agent with yours): 
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
Scope: current project by default; add -g for global (all projects).

Configure the API Key (critical)

The Skill's retrieval scripts call the DashScope API with Authorization: Bearer, so an API Key is mandatory. Scripts auto-fetch it in this priority:
  1. Alibaba Cloud CLI config ~/.aliyun/config.json, current profile's dashscope.api_key
  2. Environment variable DASHSCOPE_API_KEY
  3. Auto-created when Alibaba Cloud CLI is available
Option A: Environment variable (simplest) Have the user add it to their shell config (~/.zshrc / ~/.bashrc), or set for the current session: 
export DASHSCOPE_API_KEY=sk-xxxxxxxx
Option B: Auto-create via Alibaba Cloud CLI (no manual key handling) Best when you'd rather not touch keys. The Skill creates and stores one on first call: 
# 1. Install Alibaba Cloud CLI (macOS example)
brew install aliyun-cli
# 2. Install the ModelStudio plugin
aliyun plugin install --names aliyun-cli-modelstudio --enable-pre
# 3. Configure credentials (AK/SK or RAM role)
aliyun configure
The RAM user needs the AliyunBailianFullAccess system policy, or a custom policy with modelstudio:ListWorkspaces, modelstudio:CreateApiKey, modelstudio:DeleteApiKey.
API Keys are sensitive. The Agent must never print, hardcode, or script them. Configuration is done by the user via shell or Alibaba Cloud CLI; the Agent only confirms readiness. Skill scripts read the key automatically — the Agent never handles the value.

Verify the install

# Confirm the Skill is installed
npx skills ls          # project scope
npx skills ls -g       # global
Or check the file exists: .<agent>/skills/alibabacloud-bailian-rag-knowledgebase/SKILL.md (e.g. .claude/skills/...).

Restart the agent client

The Skill only loads after a client restart. The Agent cannot restart itself — prompt the user to manually restart Claude Code / Cursor / Qoder.

Using it after restart

After restart, just ask in natural language — the Agent invokes the Skill automatically:
  • "List my knowledge bases"
  • "Search the 'Product Documentation' KB: what auth methods are supported?"
The Skill lists KBs (returns id and name), retrieves relevant chunks for the question, and composes an answer with sources appended (KB name; document name; section).

Troubleshooting

SymptomCauseFix
401 InvalidApiKeyKey missing or invalidCheck DASHSCOPE_API_KEY or dashscope.api_key in ~/.aliyun/config.json
403 Forbidden / Service not activatedKB service not activatedOpen the KB page, click "Activate Now"
Agent doesn't see the Skillnot restarted / wrong dir / missing SKILL.mdRestart client; check .<agent>/skills/alibabacloud-bailian-rag-knowledgebase/SKILL.md
npx skills add failsold Node / networkconfirm Node ≥18, retry

More info

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