Alibabacloud Oos Template Generation

SKILL.md

---
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`](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
>
> ```bash
> 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](https://ram.console.aliyun.com/manage/ak)
> 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:
```bash
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:
```bash
aliyun configure ai-mode disable
```

## CLI Command Standards

> **[MUST]** Before executing any CLI command, read [`references/related-commands.md`](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`](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:
```bash
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:
```bash
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:
```bash
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`](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:
```bash
cat > /tmp/oos_template.yaml << 'EOF'
<generated template content>
EOF
```

**Step 2**: Call CLI to validate:
```bash
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
```yaml
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
```yaml
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](references/related-commands.md#cloud-product-openapi-query-via-openmeta-api)

### 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:
```bash
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:
```yaml
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:
```bash
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](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](references/cli-installation-guide.md) | Aliyun CLI installation and configuration instructions |
| [Related Commands](references/related-commands.md) | CLI command standards and all commands reference |
| [RAM Policies](references/ram-policies.md) | Required RAM permissions list and policy templates |
| [Acceptance Criteria](references/acceptance-criteria.md) | Acceptance criteria and correct/incorrect patterns |
| [Verification Method](references/verification-method.md) | Success verification method |
| [OOS Official Documentation](https://help.aliyun.com/zh/oos) | OOS product documentation |
| [OOS Template Syntax](https://help.aliyun.com/zh/oos/user-guide/template-syntax) | OOS template syntax reference |