Intelligent DevOps Execution via Yunxiao Tools

This skill translates natural-language DevOps requests into Alibaba Cloud Yunxiao API calls. It supports three invocation channels: Alibaba Cloud CLI (

aliyun devops

), MCP Server, and mcporter CLI. It covers 8 Yunxiao products (~388 CLI commands, ~165 MCP tools).

1. Overview

Core flow: Intent classification → Ambiguity resolution → Product mapping → Reference reading → Tool execution → Result verification
Scope: CI/CD, code management, project collaboration, sprints/work items, artifacts, testing, application delivery

For the full product and tool catalog (MCP tools and CLI commands by product), see references/tool-catalog.md.

2. Prerequisites

[MUST] Execution order is mandatory. Steps in this section form a sequential decision tree. You MUST execute them in the numbered order below. Do NOT check Node.js, MCP, or mcporter availability until the CLI path (Steps 1–4) has been fully attempted and failed. Do NOT run any checks in parallel across subsections 2.1 and 2.2.

Token Security Rules (applies to ALL channels):
NEVER ask users to paste plaintext tokens in conversation or command line
NEVER read/print token values using
echo
or similar commands
ONLY verify token existence via check (see steps below for channel-specific env var names)

If token is not configured, STOP and guide user to Yunxiao Personal Access Token. Required scopes: Organization Management (R/W), Project Collaboration (R/W), Code Management (R/W), Pipeline (R/W), Packages (R/W), Application Delivery (R/W), Test Management (R/W).

2.1 CLI Channel Setup (Primary — MUST complete first)

The Alibaba Cloud CLI (
aliyun devops
) is the primary invocation channel. MCP Server and mcporter are fallbacks only. Full configuration guide: references/aliyun-cli-setup.md.

Step 1: CLI availability check

bash

aliyun devops --help >/dev/null 2>&1 && echo "cli ready" || echo "cli not available"

Available → Go to Step 3
Not available → Go to Step 2 (attempt installation)

Step 2: [MUST] Attempt CLI installation

[MUST] If CLI is not found in Step 1, you MUST attempt installation before considering any fallback channel. Skipping this step is prohibited. Full installation guide: references/aliyun-cli-install.md.

Detect OS and install:
- macOS (Homebrew available):
  bash
```
brew install aliyun-cli
```
- macOS / Linux (no Homebrew):
  bash
```
/bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"
```
- Windows (PowerShell): Guide user to download and run the PowerShell install script. See references/aliyun-cli-install.md.
Verify installation and re-check:
bash
```
aliyun version
aliyun devops --help >/dev/null 2>&1 && echo "cli ready" || echo "cli not available"
```
- Available → Go to Step 3
- Still not available → Go to Section 2.2 Fallback

Step 3: Authentication and site type detection

Cloud DevOps (Yunxiao) uses Personal Access Token for authentication, not AK/SK profiles.

3a. Check token:

bash

[ -n "$ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN" ] && echo "token configured" || echo "token missing"

If token is missing, guide user to configure based on their site type:

Central site (default) — token + organization ID:

bash

export ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN=<your-personal-access-token>
export ALIBABA_CLOUD_YUNXIAO_ORGANIZATION_ID=<your-organization-id>

Region site — token + region API base URL:

bash

export ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN=<your-personal-access-token>
export ALIBABA_CLOUD_YUNXIAO_API_BASE_URL=<your-region-api-base-url>

[MUST] Never ask the user for an API base URL on the central site — it defaults to
openapi-rdc.aliyuncs.com
(for both the CLI and the MCP Server). The base URL is a region-site-only setting.

Recommend adding these to the user's shell profile (

~/.bashrc

~/.zshrc

, etc.) for persistence.

3b. Detect site type:

After token is confirmed, detect the site type:

bash

[ -n "$ALIBABA_CLOUD_YUNXIAO_API_BASE_URL" ] && echo "region site" || echo "central site (default)"
[ -n "$ALIBABA_CLOUD_YUNXIAO_ORGANIZATION_ID" ] && echo "org id configured" || echo "org id missing"

```
ALIBABA_CLOUD_YUNXIAO_API_BASE_URL
```
set → Region site: subsequent CLI calls do NOT use
```
--organization-id
```
; the API base URL is read from the environment variable automatically
Not set → Central site (default): subsequent CLI calls use
```
--organization-id
```
; if the org id is missing, guide user to set
```
ALIBABA_CLOUD_YUNXIAO_ORGANIZATION_ID
```
(it can be looked up via
```
aliyun devops base-get-user-by-token
```
)

[MUST] Remember the detected site type. All subsequent CLI calls in this session must use the corresponding parameter pattern. CLI parameters use kebab-case (e.g.,
--organization-id
), not camelCase (
--organizationId
).

Step 4: [MUST] Disable the interactive plugin-install prompt

The

devops

commands live in the

aliyun-cli-devops

plugin, which is not bundled with a fresh CLI install. The first

aliyun devops <business-command>

therefore prompts

Do you want to install it? [Y/n]:

and blocks until the command times out. Run this once per session, before any business command:

bash

aliyun configure set --auto-plugin-install true

Skipping this step wastes the whole timeout budget of your first business call.

CLI ready — If Steps 1–4 all pass, CLI channel is ready. Skip Section 2.2 entirely and proceed to Section 3.

2.2 Fallback Channel Setup (ONLY when CLI is unavailable)

[GATE] You may ONLY enter this section if both conditions are true:

Step 1 (CLI check) returned "cli not available"

Step 2 (CLI installation attempt) was executed and failed

If you have not attempted Step 2, go back and execute it now. Do NOT proceed here.

2.2.1 Node.js/Docker Runtime Check

This skill invokes

alibabacloud-devops-mcp-server@0.3.38

via

npx

docker

. Verify:

bash

node --version   # Node.js 18+ recommended
npx --version

Recommended: Pre-install dependencies (avoid runtime downloads)
bash
npm install -g alibabacloud-devops-mcp-server@0.3.38 mcporter@0.11.1 --registry=https://registry.npmmirror.com

2.2.2 Yunxiao Personal Access Token (for MCP/mcporter)

MCP/mcporter uses

YUNXIAO_ACCESS_TOKEN

(different from CLI's

ALIBABA_CLOUD_YUNXIAO_ACCESS_TOKEN

bash

[ -n "$YUNXIAO_ACCESS_TOKEN" ] && echo "token configured" || echo "token missing"

If missing, guide user to obtain a token and inject as env var (see Token Security Rules at the top of Section 2).

2.2.3 MCP Server Setup

See references/mcp-setup.md for three connection modes (Stdio / Docker / SSE). Recommended — Stdio:

json

{
  "mcpServers": {
    "yunxiao": {
      "command": "npx",
      "args": ["-y", "alibabacloud-devops-mcp-server@0.3.38"],
      "env": {
        "YUNXIAO_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Central site needs the token only —
YUNXIAO_API_BASE_URL
defaults to
https://openapi-rdc.aliyuncs.com
. Add it to
env
only for a region site.

3. Authorization Failure Handling

[MUST] When any tool call returns an authentication/authorization error:

Consult references/token-scopes.md for the required token scope

Guide user to add the scope in Yunxiao console under "Personal Access Token"

Pause execution, wait for user confirmation before proceeding

Common error codes:

Error	Action
401 Authentication failed	Check if token is valid/expired; prompt re-generation
403 Insufficient permissions	Check token scopes (see token-scopes.md and references/ram-policies.md)
404 Resource not found	Use `search_` / `list_` to verify resource IDs
400 Parameter error	Check field schema against MCP Schema
500 Server error	Retry up to 3 times with backoff

4. Parameter Confirmation

IMPORTANT — Before executing any tool call, all user-defined parameters (organizationId, projectId, repositoryId, pipelineId, branch names, work item subject, sprint dates, app/env names, etc.) must be confirmed with the user. Never call based on defaults or guesses.

Common required parameters by product:

Product	Universal required	Typical scenario parameters
All	`organizationId`	-
Codeup	`repositoryId`	`sourceBranch` / `targetBranch` / `filePath`
Flow	`pipelineId`	`branch` / `runId` / `jobId`
Projex	`projectId`	`workitemTypeId` / `sprintId` / `subject`
Testhub	`projectId`	`testcaseId` / `testPlanId`
AppStack	`appName`	`envName` / `changeOrderId`

5. Core Execution Flow

User request → [Step 1] Intent classification → [Step 2] Ambiguity handling → [Step 3] Product mapping
             → [Step 4] Read product references → [Step 5] Execute tool calls → Return results

Step 1: Intent Classification

Core principle: Identify the core verb, not the noun.

Action	Typical verbs	Tool prefix
Create	create, add, initialize, set up	`create_*`
Query	view, get, list, search, find	`get_` / `list_` / `search_*`
Update	update, modify, change, edit	`update_*`
Delete	delete, remove, clean up	`delete_` (requires confirmation*)
Trigger	run, execute, trigger, start, deploy	`create_pipeline_run` / `execute_*`
Configure	configure, set up, bind, associate	`update_` / `create_`

Decision tree and examples: references/intent-classification.md.

Step 2: Ambiguity Handling

Core principle: If the instruction is vague or involves multi-product keywords, never guess — ask.

Ambiguity type	Detection condition	Strategy
Product	Multi-product keywords present	Ask which product
Action	Action unclear	Ask for operation type
Object	Missing identifiers	Ask for resource name or ID
Parameter	Missing key parameters	Ask for missing values
Scope	Org/project not specified	Ask for org/project

Step 3: Product Mapping

Full mapping: references/product-mapping.md.

Keywords	Product	MCP toolset	CLI prefix
Pipeline, build, deploy, CI/CD	Flow	pipeline-management	flow-
Code, repo, branch, commit, MR, review	Codeup	code-management	codeup-
Artifact, package, Maven, NPM, Docker image	Packages	packages-management	packages-
Requirement, work item, sprint, bug, task	Projex	project-management	projex-
Test case, test plan, test report	Testhub	test-management	test-hub-
Application, orchestration, change order, release	AppStack	application-delivery	app-stack-
Organization, member, department, role	-	organization-management	base-
Current user info	-	base	base-

Ambiguity decision points:

"CI/CD full flow" → Build-only → Flow; app lifecycle → AppStack; both → ask
"Repository" → Code repo → Codeup; artifact repo → Packages; unclear → ask

Step 4: Read Product References

After determining the target product, must consult the Yunxiao documentation index at references/product-reference.md.

Step 5: Execute Tool Calls

Three invocation channels (functionally equivalent):

Method	Scenario	Prerequisites
Alibaba Cloud CLI ( `aliyun devops` )	Shell environment available	`aliyun` installed with token configured
Platform-native MCP	IDE/platform with MCP Server	`use_mcp_tool` available
Terminal CLI (mcporter)	Pure terminal, no MCP Server	Node.js 18+ installed

Channel selection: Choose based on availability — CLI configured → CLI; MCP integrated → MCP; Shell + Node.js only → mcporter.

Region Site Routing (mandatory): When the user specifies a Yunxiao instance address or token differing from current MCP config:

MUST prompt user to update MCP Server config (
```
YUNXIAO_API_BASE_URL
```
/
```
YUNXIAO_ACCESS_TOKEN
```
)
MUST NOT bypass MCP Server via mcporter — mcporter is only for when MCP Server is absent
URL with Region keywords (e.g.,
```
cn-shanghai
```
) → Region edition;
```
openapi-rdc.aliyuncs.com
```
or unspecified → Central (default, no base URL config needed)

Method A: Alibaba Cloud CLI

bash

aliyun devops <command> --<param1> <value1> \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-devops/${SESSION_ID}"

All
aliyun devops
commands must include
--user-agent
with the session-scoped UA value (see Section 7: Observability). When using environment variables for authentication, no additional auth parameters are needed. When using command-line parameters, append
--yunxiao-access-token
and
--organization-id
(central) or
--api-base-url
(region) to each command.

For command discovery by product prefix, use

scripts/discover-commands.sh

or see references/tool-catalog.md.

Method B: Platform-native MCP

use_mcp_tool(
  server_name: "yunxiao",
  tool_name: "<tool>",
  arguments: { "<key>": "<value>" }
)

Method C: mcporter CLI

bash

npx -y mcporter@0.11.1 call --no-coerce --stdio "npx -y alibabacloud-devops-mcp-server@0.3.38" <tool_name> [key:"value" ...]

MUST always use
--no-coerce
to prevent auto type conversion of string enums.

Parameter rules: Use

key:"value"

format, space-separated. Do not pass JSON strings. Omit parameters for no-argument tools. Use

scripts/mcporter-call.sh

for convenience.

Get available tools:

bash

npx -y mcporter@0.11.1 list --stdio "npx -y alibabacloud-devops-mcp-server@0.3.38" --schema

[MUST] Tool selection must be based on dynamic discovery: Select from registered tool list, never fabricate tool names. Use
mcporter list
or references/tool-catalog.md.

[MUST] Never fabricate results: All tool calls must be actually executed with real return values.

Pre-execution checklist (mandatory):

Obtain

organizationId

via

aliyun devops base-get-user-by-token

(MCP:

get_current_organization_info

)

[Mandatory] Verify target resource exists via
```
list_*
```
/
```
search_*
```
/
```
get_*
```
— even if ID is provided
All required parameters confirmed with user (Section 4)
Delete operations require confirmation
[Mandatory] Dynamic schema validation before first call to any unfamiliar tool:
- Method B: Check platform tool registry
- Method C:
```
npx -y mcporter@0.11.1 list --stdio "npx -y alibabacloud-devops-mcp-server@0.3.38" --schema 2>&1 | grep -A 30 'function <tool_name>'
```
- If schema returns a different tool name, use the schema's version
- For Testhub: call
```
test-hub-get-testcase-field-config
```
  (MCP:
```
get_testcase_field_config
```
  ) first — it reports which fields are required (
```
assignedTo
```
  is) and yields the per-library option IDs that
```
customFieldValues
```
  must carry (e.g.
```
{"tc.priority": "<P1 option id>"}
```
  ; sending the label
```
"P1"
```
  fails with
```
400 字段【优先级】所填值无效
```
  ).
```
testSteps
```
  must carry a
```
content[]
```
  array — a payload using only
```
stepContent
```
  /
```
expectedResult
```
  (which is the read-back shape) fails with
```
500 unknown exception
```
  . See references/common-scenarios.md Scenario 6.
- For Projex: call
```
projex-list-workitem-types
```
  (MCP:
```
list_work_item_types
```
  ) first — never use hardcoded type IDs

Full tool catalog: references/tool-catalog.md. Scenario examples: references/common-scenarios.md.

6. Success Verification

[RECOMMENDED] After
create_*
/
update_*
, call the corresponding
get_*
to verify when budget permits. If API returned success with a resource ID, creation can be considered successful even without read-back.
Known API limitations: Some fields may differ between write and read-back — see references/verification-method.md.

Operation	Verification command (CLI / MCP)	Check
Create pipeline	`flow-get-pipeline` (MCP: `get_pipeline` )	pipelineId + name match
Run pipeline	`flow-get-latest-pipeline-run` (MCP: `get_latest_pipeline_run` )	status != `FAIL`
Create branch	`codeup-get-branch` (MCP: `get_branch` )	Branch appears
Create MR	`codeup-get-change-request` (MCP: `get_change_request` )	state = `OPENED`
Create work item	`projex-get-workitem` (MCP: `get_work_item` )	subject + workItemTypeId correct
Create sprint	`projex-get-sprint` (MCP: `get_sprint` )	Date range matches

More: references/verification-method.md.

7. Observability

User-Agent Declaration (Mandatory)

[MUST] Every
aliyun devops
business command must carry the
--user-agent
flag for attribution and tracing. The UA value follows a fixed template that includes a per-session identifier.

UA Template:

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-devops/{session-id}

Session-ID Generation Rule:

Item	Rule
Format	32-character lowercase hexadecimal string, e.g., `f47ac10b58cc4372a5670e02b2c3d479`
Lifecycle	Generate once at the start of each skill invocation session; reuse the same value across all channels (CLI, MCP, mcporter) within that session
Consistency	The same `{session-id}` must be used for CLI `--user-agent` , MCP request metadata, and mcporter calls within one session
Generation method	`python3 -c "import uuid; print(uuid.uuid4().hex)"` or `uuidgen \| tr -d '-' \| tr '[:upper:]' '[:lower:]'`

Usage — append to every
aliyun devops
command:

bash

SESSION_ID=$(python3 -c "import uuid; print(uuid.uuid4().hex)")

aliyun devops <command> --<param1> <value1> \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-devops/${SESSION_ID}"

Important: The
--user-agent
flag is applied directly on each business command. Do NOT configure UA through any global mode-setting command — always pass it inline per invocation.

8. Best Practices

Read before write:
```
get_*
```
before
```
update_*
```
/
```
delete_*
```
to confirm current state
Pagination: List APIs paginate by default; pass
```
page
```
/
```
perPage
```
for large lists
YAML first: Pipeline creation goes through
```
flow-create-pipeline --name --content
```
(YAML is mandatory). Before composing the YAML, collect the three organization-specific values that are always rejected if guessed — the repository's
```
httpUrlToRepo
```
(never
```
webUrl
```
), the Codeup service connection
```
uuid
```
(query with the lowercase filter
```
--service-connection-type codeup
```
;
```
Codeup
```
reproducibly returns an empty list, which is not proof the connection is missing), and a
```
runsOn.group
```
harvested from an existing pipeline (no API lists build clusters, and
```
public/<region>
```
often does not exist). The Codeup credential is a nested
```
certificate
```
object, not a bare
```
serviceConnection
```
key, and a build-only pipeline must omit
```
ArtifactUpload
```
. MCP's
```
create_pipeline_from_description
```
builds its YAML internally and cannot be corrected — on any
```
yaml校验失败
```
/
```
服务连接[...]不存在
```
error, stop retrying it and switch to the CLI path. Verified template and preflight steps: references/common-scenarios.md Scenario 1.
Smart search:
```
flow-list-pipelines
```
with timestamp parameters —
```
--execute-start-time
```
/
```
--execute-end-time
```
/
```
--create-start-time
```
/
```
--create-end-time
```
take millisecond epoch values (13 digits, e.g.
```
$(($(date +%s) * 1000))
```
). Passing seconds (10 digits) is not rejected by the API; it silently filters against 1970 and returns misleading results, so always multiply by 1000 and sanity-check the digit count. (MCP provides
```
smart_list_pipelines
```
supporting natural-language time ranges.)
Read-only first: When uncertain, use
```
list_*
```
/
```
search_*
```
/
```
get_*
```
Fail fast: Two consecutive same-parameter failures → change approach. Report: methods tried, errors, root cause, next steps
Budget discipline: Plan critical path first; debugging ≤3 steps; near limit (≤2 remaining) → stop and report
Clean up: Delete experimental resources after use

9. Scenario Quick Reference

Full examples: references/common-scenarios.md.

Scenario	Product	Key CLI commands	Key MCP tools
Create Java build pipeline	Flow	`codeup-get-repository` (clone URL) → `flow-list-service-connections --service-connection-type codeup` (uuid; lowercase value, `Codeup` returns `[]` ) → `flow-get-pipeline` (harvest `runsOn` ) → `flow-create-pipeline` → `flow-list-pipelines`	`get_repository` → `list_service_connections` → `get_pipeline` → `create_pipeline_from_description` (falls back to CLI on YAML validation failure)
Create MR with review comment	Codeup	`codeup-get-repository` → `codeup-create-change-request` → `codeup-list-change-request-patch-sets` → `codeup-create-change-request-comment`	`get_repository` → `create_change_request` → `list_change_request_patch_sets` → `create_change_request_comment`
Create sprint and add requirement	Projex	`projex-search-projects` → `projex-create-sprint` → `projex-create-workitem`	`search_projects` → `create_sprint` → `create_work_item`
Run pipeline and view logs	Flow	`flow-get-pipeline` → `flow-create-pipeline-run` (branch goes in `--params '{"branchModeBranchs":"<branch>"}'` ; there is no `--branch` flag) → `flow-get-pipeline-run --pipeline-run-id` → `flow-get-pipeline-job-run-log --job-id <stages[].stageInfo.jobs[].id>`	`get_pipeline` → `create_pipeline_run` → `get_pipeline_run` → `get_pipeline_job_run_log`
Batch query artifacts	Packages	`packages-list-repositories` → `packages-list-artifacts`	`list_package_repositories` → `list_artifacts`
Create test cases	Testhub	`test-hub-get-testcase-field-config` (required fields + option IDs) → `test-hub-list-directories` → `test-hub-create-testcase` → `test-hub-search-testcases`	`get_testcase_field_config` → `list_testcase_directories` → `create_testcase` → `search_testcases`
Application release workflow	AppStack	`app-stack-list-all-release-workflows` → `app-stack-execute-change-request-release-stage`	`list_app_release_workflows` → `execute_app_release_stage`

10. Reference Index

Reference file	Content
references/aliyun-cli-install.md	Alibaba Cloud CLI installation guide (macOS/Linux/Windows)
references/mcp-setup.md	MCP Server connection modes and environment variables
references/intent-classification.md	Intent classification decision tree
references/product-mapping.md	Keyword → product mapping table
references/product-reference.md	Yunxiao documentation index and key concepts
references/tool-catalog.md	~165 MCP tools grouped catalog
references/token-scopes.md	Token authorization scopes and troubleshooting
references/common-scenarios.md	End-to-end workflow examples
references/verification-method.md	Success verification and read-back methods
references/acceptance-criteria.md	Tool call correctness acceptance criteria
references/ram-policies.md	Yunxiao permission model vs. standard Alibaba Cloud RAM

alibabacloud-devops

NPX Install

Tags

SKILL.md Content

Intelligent DevOps Execution via Yunxiao Tools

1. Overview

2. Prerequisites

2.1 CLI Channel Setup (Primary — MUST complete first)

2.2 Fallback Channel Setup (ONLY when CLI is unavailable)

2.2.1 Node.js/Docker Runtime Check

2.2.2 Yunxiao Personal Access Token (for MCP/mcporter)

2.2.3 MCP Server Setup

3. Authorization Failure Handling

4. Parameter Confirmation

5. Core Execution Flow

Step 1: Intent Classification

Step 2: Ambiguity Handling

Step 3: Product Mapping

Step 4: Read Product References

Step 5: Execute Tool Calls

6. Success Verification

7. Observability

User-Agent Declaration (Mandatory)

8. Best Practices

9. Scenario Quick Reference

10. Reference Index