# DevOps API Skills

## Layer

`devops-api` 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
    ├── devops_http.sh
    └── generate_subskills_index.py
```

- Entry Skill: `SKILL.md`
  - Handles intent detection (release, query, operations, etc.).
  - Handles routing and decides which sub-skill should be loaded.
  - Provides a unified API access method (via `scripts/devops_http.sh`).
  
- SubSkill: for example `query-clusters/SUBSKILL.md`
  - Focuses on a single task domain (such as cluster query).
  - Defines required parameters, API paths, methods, and execution steps for that domain.

## 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 user 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).

## Shared transport

`devops_http.sh` is the unified access layer for DevOps APIs. Its core goals are:

- Standardize authentication and base configuration loading.
- Standardize request construction (`method/path/query/body/header`).
- Standardize output and error handling conventions.

### Authentication

By default the script loads configuration from `.env`, and `--env-file` can override it.

Key variables:

- `DEVOPS_API_TOKEN`: required. Sent via the `X-API-TOKEN` header.
- `DEVOPS_BASE_DOMAIN`: optional. Default is `https://prod.devops.pingcap.com`.