83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
# 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.
|