# Excloud Agent Skills

A collection of [agent skills](https://agentskills.io/) for working with [Excloud](https://excloud.in) from AI coding agents (Claude Code, Cursor, Codex, opencode, etc.).

Skills are `SKILL.md` playbooks the agent can load on demand — authenticated paths, safety guardrails, command syntax, and error recovery for a specific surface. Install them with the [`skills`](https://www.npmjs.com/package/skills) CLI.

## Install

This repo lives on Excloud's self-hosted Gitea at <https://git.excloud.in/excloud-in/excloud-skills>. Point `npx skills add` at the full clone URL (note the `.git` suffix — without it, the CLI looks for a `.well-known/agent-skills/index.json` manifest rather than cloning):

```bash
npx skills add https://git.excloud.in/excloud-in/excloud-skills.git
```

Install a single skill:

```bash
npx skills add https://git.excloud.in/excloud-in/excloud-skills.git --skill excloud-cli
```

Install all skills into every supported agent without prompts:

```bash
npx skills add https://git.excloud.in/excloud-in/excloud-skills.git --all
```

Target specific agents with repeated `-a` flags (defaults to global, user-level install):

```bash
npx skills add https://git.excloud.in/excloud-in/excloud-skills.git -a claude-code -a opencode --all
```

Dry-run — list what the repo offers without installing:

```bash
npx skills add https://git.excloud.in/excloud-in/excloud-skills.git --list
```

Private-repo users: set up git auth for `git.excloud.in` first (an HTTPS credential helper / `~/.netrc`, or use the SSH form `git@git.excloud.in:excloud-in/excloud-skills.git`). `npx skills add` shells out to plain `git clone`, so anything `git clone` can read, it can install from.

By default skills land under the agent's standard directory (`~/.claude/skills/`, `.agents/skills/`, `.augment/skills/`, ...). Run `npx skills --help` for the full option list, and `npx skills list` to see what is currently installed.

## Available skills

### `excloud-cli`

Safe end-to-end control of Excloud resources through the `exc` CLI. Covers compute (create / inspect / resize / restart / terminate, delete protection, exec / scp / console), networking (subnets, public IPv4, security groups and rules/bindings), volumes and snapshots, SSH keys, Kubernetes (clusters, workers, kubeconfig fetch / merge), IAM (accounts, service accounts, API keys, policies), billing, quota, serial console logs, and metrics.

**Use when:** the user asks to plan or run `exc` commands, provision / introspect / tear down VMs, attach a public IP, adjust a security group, pull a kubeconfig, debug a stuck boot via serial logs, or exec / scp against a VM.

**Key guidance the skill encodes:**

- Auth precedence (`EXCLOUD_ACCESS_TOKEN` / env tokens / `~/.exc/config`) and what "not authenticated" means.
- Discovery first: lookup tables (`exc compute instancetype list`, `image list`, `subnet list`, `securitygroup list`, ...) as the source of truth — no hard-coded IDs.
- Safety guardrails around `terminate`, `publicip release`, `rule delete`, `cluster delete`, `apikey delete`, and destructive shell commands over `exec`.
- Interactive access patterns: when to use `exec` (one-shot, bash-interpreted), when `scp` (upload/download, symlinks rejected), when `console` (interactive TTY, SSH ↔ WS fallback).
- Output-format buckets so agents pipe to `awk`/`jq` correctly.
- A cheat sheet of error messages the CLI actually emits, paired with what each means and how to fix it.

Prerequisites on the user's machine: the `exc` CLI on `$PATH` and an `exc login` session. `k8s cluster kubeconfig merge` additionally needs `kubectl`.

## Repository layout

```
excloud-skills/
├── README.md              # this file
├── AGENTS.md              # contributor / agent guidance for editing skills
├── .gitignore
└── skills/
    └── excloud-cli/
        └── SKILL.md       # the skill itself
```

Each skill lives in `skills/<skill-name>/` with a single `SKILL.md`. Scripts (`scripts/`) and reference docs (`references/`) can live alongside `SKILL.md` when a skill needs them.

## Contributing a new skill

See [`AGENTS.md`](./AGENTS.md) for conventions (directory name, `SKILL.md` frontmatter, when to add scripts vs. references, how to keep skills discovery-friendly). Open a PR with the new `skills/<skill-name>/` directory; agent-side install is `npx skills add excloud-in/excloud-skills --skill <name>` once merged.

## License

TBD.