back
loading skill details...
OOS template intelligent generation skill. Use when users need to create, write, or generate Alibaba Cloud OOS (Operation Orchestration Service) automation t...
---
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 |
don't have the plugin yet? install it then click "run inline in claude" again.