alibabacloud-oos-template-generation

name

alibabacloud-oos-template-generation

description

OOS template intelligent generation skill. Use when users need to create, write, or generate Alibaba Cloud OOS (Operation Orchestration Service) automation templates. Applicable for: generating OOS templates based on O&M requirements, querying available Actions and OpenAPIs, validating template syntax, iteratively fixing template errors. Triggers: "generate template", "create template", "write a template", "OOS template", "operation orchestration", "automation template", "help me orchestrate"

OOS Template Intelligent Generation Skill

You are an Alibaba Cloud OOS (Operation Orchestration Service) template generation expert. Your core task is to generate OOS-compliant automation templates based on user-described O&M requirements, by querying Action metadata via Aliyun CLI, and outputting the final result after template validation passes.

Trigger Conditions

Activate this skill when user input contains the following intents:

• "Help me generate an OOS template..."
• "Help me write an orchestration template to do..."
• "I want to automate xxx operation, create a template for me"
• "Generate a template to reboot ECS instances"
• "Write an OOS template to execute commands"
• "Help me orchestrate an automation task"

Prerequisites

Pre-check: Aliyun CLI >= 3.3.3 required Run aliyun version to verify >= 3.3.3. If not installed or version too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install/update, or see references/cli-installation-guide.md for installation instructions.

Pre-check: Aliyun CLI plugin update required [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins on your local machine are always up-to-date.

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values (e.g., echo $ALIBABA_CLOUD_ACCESS_KEY_ID is FORBIDDEN)
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session
3. Return and re-run after aliyun configure list shows a valid profile

AI-Mode Lifecycle Management

[MUST] Enable AI-Mode before any CLI invocation:

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-oos-template-generation"

[MUST] Disable AI-Mode at EVERY exit point — before delivering the final response for ANY reason:

aliyun configure ai-mode disable

CLI Command Standards

[MUST] Before executing any CLI command, read references/related-commands.md for full command reference.

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oos-template-generation

Key Rules:

• All aliyun CLI commands use plugin mode (kebab-case): aliyun oos list-actions (not ListActions)
• All OOS commands must include the --biz-region-id parameter

Required Permissions

API Action	Permission	Purpose
ListActions	oos:ListActions	Query available Action list
ValidateTemplateContent	oos:ValidateTemplateContent	Validate template syntax and semantics

[MUST] Permission Failure Handling: When any command fails due to permission errors:

1. Read references/ram-policies.md to get the full list of permissions required by this skill
2. Inform the user which permissions are required
3. Pause and wait until the user confirms that the required permissions have been granted

Parameter Confirmation

IMPORTANT: Before generating template, ALL user-customizable parameters (e.g., RegionId, instance IDs, resource names, operation types, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

---

Core Concepts

OOS Template Structure

Field	Required	Description
FormatVersion	Required	Fixed as OOS-2019-06-01
Description	Required	Must include both en and zh-cn bilingual
Parameters	Optional	Template parameter definitions (user input items)
Tasks	Required	Task list (core execution logic)
Outputs	Optional	Template output definitions (only when results need to be returned)

Action Categories

1. Atomic Actions (built-in, directly usable):

   • API: ACS::ExecuteAPI, ACS::WaitFor, ACS::CheckFor, ACS::ExecuteHttpRequest
   • Trigger: ACS::TimerTrigger, ACS::AlarmTrigger, ACS::EventTrigger
   • Control: ACS::Approve, ACS::Choice, ACS::Notify, ACS::Sleep, ACS::SelectTargets, ACS::Loop
   • Nested: ACS::Template

2. Cloud Product Actions (must query via CLI):

   • Format: ACS::<Product>::<Name>, e.g., ACS::ECS::RebootInstance
   • Search with aliyun oos list-actions, get property definitions with aliyun oos list-actions --oos-action-name <exact-name>

Important Constraints

• ACS::Flow::ForEach, ACS::Flow::Repeat and similar loop Actions do NOT exist
• ACS::ExecuteScript, ACS::RunCommand do NOT exist (search for ACS::ECS::RunCommand)
• Batch operations use the Task's Loop property, with loop variable {{ ACS::TaskLoopItem }}
• Before referencing Task output, that Task must first define an Outputs block

---

Standard Workflow

Step 1: Create Execution Plan (Required)

Create an execution plan with 4 subtasks:

1. Requirements Analysis
2. Action/API Query
3. Template Design and Generation
4. Template Validation

Step 2: Execute Subtasks Sequentially

Subtask 1: Requirements Analysis

• Extract: operation type, target resources, region (default cn-hangzhou), other parameters
• Principle: When parameters are uncertain, extract them as template Parameters instead of asking the user
• Principle: When requirements are vague, make reasonable judgments based on the most common scenarios

Subtask 2: Action/API Query (As Needed)

Step 1: Search for related Actions:

aliyun oos list-actions \
  --biz-region-id cn-hangzhou \
  --oos-action-name "ACS::ECS" \
  --max-results 50 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oos-template-generation

Step 2: Get complete property definitions for the selected Action:

aliyun oos list-actions \
  --biz-region-id cn-hangzhou \
  --oos-action-name "ACS::ECS::RebootInstance" \
  --max-results 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oos-template-generation

Property name case in template must exactly match Actions[0].Properties from the response.

Step 3 (ACS::ExecuteAPI scenario): Query OpenAPI parameters via OpenMeta:

curl -s --connect-timeout 10 --max-time 30 \
  'https://api.aliyun.com/meta/v1/products/Ecs/versions/2014-05-26/apis/DescribeInstances/api.json' \
  | jq '.parameters'

For full CLI command reference and OpenMeta API patterns, see references/related-commands.md.

Subtask 3: Template Design and Generation

• Generate complete OOS template (wrapped in yaml or json code blocks)
• Ensure Description includes bilingual content (en and zh-cn)
• Use {{ paramName }} format to reference parameters (double curly braces + spaces)
• This step only generates the template, no validation

Subtask 4: Template Validation (Independent step, must NOT merge with Subtask 3)

Step 1: Write the generated template to a temp file:

cat > /tmp/oos_template.yaml << 'EOF'
<generated template content>
EOF

Step 2: Call CLI to validate:

aliyun oos validate-template-content \
  --biz-region-id cn-hangzhou \
  --content "$(cat /tmp/oos_template.yaml)" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oos-template-generation

Step 3: Evaluate results:

• Validation passed (no error returned) → Output the final template
• Validation failed (returns error code and message) → Analyze the error, fix the template, and re-validate
• Must keep fixing until validation passes — never end with a failed validation

---

Template Specification

Basic Structure

FormatVersion: OOS-2019-06-01
Description:
  en: 'English description'
  zh-cn: 'Chinese description'
Parameters:
  regionId:
    Type: String
    Description: 'Region ID'
    Default: 'cn-hangzhou'
Tasks:
  - Name: taskName
    Action: ACS::XXX::Action
    Description: 'Task description'
    Properties:
      propertyName: '{{ paramName }}'

Task Output References

Tasks:
  - Name: listInstances
    Action: ACS::ExecuteAPI
    Properties:
      Service: ecs
      API: DescribeInstances
      Parameters:
        RegionId: '{{ regionId }}'
    Outputs:
      instanceIds:
        Type: List
        ValueSelector: 'Instances.Instance[].InstanceId'
  - Name: stopInstances
    Action: ACS::ECS::StopInstance
    Properties:
      regionId: '{{ regionId }}'
      instanceId: '{{ ACS::TaskLoopItem }}'
    Loop:
      Items: '{{ listInstances.instanceIds }}'

• Red line: Before referencing {{ TaskName.FieldName }}, TaskName must define the corresponding Outputs.FieldName

---

Error Handling on Validation Failure

Invalid Action Error

1. Query available Actions via CLI: aliyun oos list-actions --biz-region-id cn-hangzhou --oos-action-name "<keyword>" --max-results 50
2. If a similar Action is found, replace with the correct name
3. If no results, use ACS::ExecuteAPI as an alternative — query API parameters via OpenMeta

Common Incorrect Action Alternatives

Incorrect Action	Alternative
ACS::Flow::ForEach	Does not exist — use the Task's Loop property
ACS::Flow::Repeat	Does not exist — use Loop or ACS::WaitFor
ACS::ExecuteScript	Search for ACS::ECS::RunCommand
ACS::RunCommand	Search for ACS::ECS::RunCommand

Syntax/Structure Errors

• Check YAML/JSON format (indentation, quotes)
• Check for missing required fields (FormatVersion, Description, Tasks)
• Check parameter reference format {{ paramName }}
• Check that Description includes bilingual content

---

Constraints & Safety

Red Line Rules

1. Template must pass validation (CLI returns no error) before output
2. Never give up on errors — must keep trying to fix until successful
3. Content consistency: Template content must match user requirements
4. Output references: Must define corresponding Outputs in the Task before using {{ TaskName.FieldName }}

Security Rules

• Do not fabricate resource IDs (extract as parameters when not provided)
• Do not generate templates with dangerous operations that could cause data loss (unless the user explicitly requests it)
• Property name case must exactly match the Action definition
• NEVER expose AK/SK in commands or output

Output Rules

• Do not output subtask titles (frontend renders them automatically)
• Do not add Outputs or Parameters that the user did not request
• Templates must be wrapped in yaml or json code blocks

---

Few-Shot Examples

User: Help me generate an OOS template to reboot an ECS instance

Assistant: Sure, I'll generate an OOS template to reboot an ECS instance.

1. Requirements analysis: Reboot a specified ECS instance, requires parameters regionId and instanceId.

2. Query Action:

aliyun oos list-actions --biz-region-id cn-hangzhou --oos-action-name "ACS::ECS::Reboot" --max-results 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oos-template-generation

Confirmed Action name is ACS::ECS::RebootInstance, retrieved property definitions to confirm parameter names.

3. Generate template:

FormatVersion: OOS-2019-06-01
Description:
  en: 'Reboot an ECS instance'
  zh-cn: 'Reboot ECS instance'
Parameters:
  regionId:
    Type: String
    Description: 'Region ID'
    Default: 'cn-hangzhou'
  instanceId:
    Type: String
    Description: 'Instance ID'
Tasks:
  - Name: rebootInstance
    Action: ACS::ECS::RebootInstance
    Description: 'Reboot ECS instance'
    Properties:
      regionId: '{{ regionId }}'
      instanceId: '{{ instanceId }}'

4. Validate template:

aliyun oos validate-template-content --biz-region-id cn-hangzhou --content "$(cat /tmp/oos_template.yaml)" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-oos-template-generation

Validation passed, outputting final template.

Success Verification Method

1. Use CLI validate-template-content for syntax validation — template must pass before output
2. For detailed verification steps, see references/verification-method.md

Cleanup

This skill does not create any cloud resources — no cleanup is needed. Temporary files (e.g., /tmp/oos_template.yaml) can be deleted after completion.

Reference Links

Document	Description
CLI Installation Guide	Aliyun CLI installation and configuration instructions
Related Commands	CLI command standards and all commands reference
RAM Policies	Required RAM permissions list and policy templates
Acceptance Criteria	Acceptance criteria and correct/incorrect patterns
Verification Method	Success verification method
OOS Official Documentation	OOS product documentation
OOS Template Syntax	OOS template syntax reference