# Dedicated Cloud Toolkit Skills

## Layer

`dedicated-cloud-toolkit` 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 toolkit intent detection and routing.
  - Decides which toolkit sub-skill should be loaded.
- Sub-skill: for example `<sub-skill-name>/SUBSKILL.md`
  - Focuses on one toolkit domain.
  - Defines required inputs, execution steps, and completion checks.

## Relationship and Responsibility

- `dedicated-cloud-toolkit` is the base layer for reusable Dedicated Cloud actions.
- `dedicated-cloud-diag` depends on toolkit `read-only` actions to keep diagnosis non-intrusive.
- `dedicated-cloud-ops` depends on toolkit `read-only` and `change` actions for remediation.

## 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 `get-` prefix for read-only query and data collection subskills.
  - Use the `act-` prefix for mutation and operational change subskills.
  - Prefix naming helps distinguish subskill directories from non-subskill folders such as `scripts/` and `mechanisms/`.
- Template role:
  - `get-xxx/SUBSKILL.md` and `act-xxx/SUBSKILL.md` are minimal examples for expected structure and writing style.
  - Replace `xxx` with a concrete domain phrase when creating a real subskill.
- Routing role:
  - Template sub-skills must be excluded from runtime routing and from generated `SUBSKILLS_INDEX.md`.

## Sub-skill Contract

Each toolkit `SUBSKILL.md` should explicitly define:

- **Action Type**: `read-only` or `change`.
- **Inputs**: required IDs, environment, and optional filters.
- **Outputs**: structured result fields and human-readable summary.
- **Side Effects**: explicit mutation scope for `change`; `read-only` must state no mutation.
- **Verification**: post-action checks and success criteria.
- **Confirmation Rule**: for `change`, require user confirmation before execution.

## 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 toolkit intent.
3. Read that sub-skill's `SUBSKILL.md` and execute its instructions.

### Re-generating `SUBSKILLS_INDEX.md` After sub-skill changes

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

```bash
python3 scripts/generate_subskills_index.py
```

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

## Implementation Mechanisms

This section defines reusable execution mechanisms for toolkit subskills.

- Routing mechanism decides which subskill to execute.
- Implementation mechanism defines how the selected subskill executes.
- Mechanism documents live under `mechanisms/`, and multiple mechanisms can
  coexist.

### Mechanism: `extend-devops-api`

`extend-devops-api` is one implemented mechanism for reusing DevOps API
transport while keeping toolkit routing ownership.

Mechanism details:

- `mechanisms/extend-devops-api.md`

#### Subskill Authoring Reference

When authoring a toolkit subskill that uses `extend-devops-api`, keep a short
`Reuse Mechanism` section like:

```markdown
## Reuse Mechanism

This subskill follows `mechanisms/extend-devops-api.md` in `transport-only`
mode and reuses `devops_http.sh` from installed `devops-api` skill directories.
```

Authoring checklist:

- [ ] Keep action ownership in toolkit.
- [ ] Reference `mechanisms/extend-devops-api.md`.
- [ ] Point execution guidance to provider `devops-api/SKILL.md` sections:
      `Environments` and `DevOps API Access`.
- [ ] Keep only interface-specific path and output details in each subskill.