# Dedicated Cloud Ops Skills

## Layer

`dedicated-cloud-ops` uses a layered model of "entry skill + sub-skill":

```bash
.
├── SKILL.md
├── SUBSKILLS_INDEX.md
├── <sub-skill-1>
│   └── SUBSKILL.md
├── <sub-skill-2>
│   └── SUBSKILL.md
└── scripts
    └── generate_subskills_index.py
```

- Entry Skill: `SKILL.md`
  - Handles operations intent detection and routing.
  - Decides which operations sub-skill should be loaded.
- SubSkill: for example `<sub-skill-name>/SUBSKILL.md`
  - Focuses on one operations domain.
  - Defines required inputs, execution steps, and completion checks.

## Relationship and Responsibility

- `dedicated-cloud-ops` is the operations and remediation layer.
- It can invoke toolkit `read-only` and `change` actions.
- It can run a diagnose-then-act path by invoking `dedicated-cloud-diag` first when needed.
- It can also consume user-provided diagnosis output and select a remediation action.

## Template Sub-skills and Naming Intent

Template sub-skills are naming placeholders and authoring examples.
They are not executable runtime sub-skills.

- Naming role:
  - Use the `ops-` prefix to clearly mark operations/remediation subskills and distinguish them from non-subskill folders such as `scripts/`.
- Template role:
  - `ops-xxx/SUBSKILL.md` is a minimal example for structure and writing style.
  - Replace `xxx` with a concrete operations domain phrase when creating a real subskill.
- Routing role:
  - Template sub-skills must be excluded from runtime routing and from generated `SUBSKILLS_INDEX.md`.

## SubSkill Contract

Each operations `SUBSKILL.md` should explicitly define:

- **Action Type**: `read-only` or `change` (default should be `read-only` when possible).
- **Inputs**: resource scope, preconditions, and dependency checks.
- **Outputs**: execution result, changed entities, and operator-facing summary.
- **Side Effects**: explicit mutation plan, blast radius, and rollback path.
- **Confirmation Rule**: for every `change`, show action details and rationale, then require explicit user confirmation.
- **Verification**: post-action checks that report resolved, partially resolved, or unresolved.

## Routing Mechanism

`SUBSKILLS_INDEX.md` is the key metadata file for sub-skill discovery.

The AI Agent first reads `SUBSKILLS_INDEX.md`, then selects the best matching sub-skill:

1. Read the index to get candidate sub-skill names, descriptions, and paths.
2. Select the most relevant sub-skill based on operations intent.
3. Read that sub-skill's `SUBSKILL.md` and execute its instructions.

### Re-generating `SUBSKILLS_INDEX.md` After SubSkill Changes

Run index generation after adding or editing any sub-skill, before commit.

```bash
python scripts/generate_subskills_index.py
```

| WARN: Do not manually edit `SUBSKILLS_INDEX.md` (it is marked as auto-generated).