84 lines
5.1 KiB
Markdown
84 lines
5.1 KiB
Markdown
# Excloud Agent Skills
|
|
|
|
A collection of [agent skills](https://agentskills.io/) for working with [Excloud](https://excloud.dev) 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.dev/excloud-dev/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.dev/excloud-dev/excloud-skills.git
|
|
```
|
|
|
|
Install a single skill:
|
|
|
|
```bash
|
|
npx skills add https://git.excloud.dev/excloud-dev/excloud-skills.git --skill excloud-cli
|
|
```
|
|
|
|
Install all skills into every supported agent without prompts:
|
|
|
|
```bash
|
|
npx skills add https://git.excloud.dev/excloud-dev/excloud-skills.git --all
|
|
```
|
|
|
|
Target specific agents with repeated `-a` flags (defaults to global, user-level install):
|
|
|
|
```bash
|
|
npx skills add https://git.excloud.dev/excloud-dev/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.dev/excloud-dev/excloud-skills.git --list
|
|
```
|
|
|
|
Private-repo users: set up git auth for `git.excloud.dev` first (an HTTPS credential helper / `~/.netrc`, or use the SSH form `git@git.excloud.dev:excloud-dev/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), object storage buckets (bucket lifecycle, object copy/sync/delete/share, access keys, multipart uploads), org secrets (path-addressed encrypted store with versions, audited reveals, value-source flags, reveal output combinators), IAM (accounts, service accounts, API keys, policies), billing details, pre-flight cost estimates, cost explorer triage, quota, serial console logs, and metrics.
|
|
|
|
**Use when:** the user asks to plan or run `exc` commands, provision / introspect / tear down VMs, estimate VM costs before creation or resizing, investigate what is costing money, attach a public IP, adjust a security group, pull a kubeconfig, manage buckets or S3 access keys, save / reveal / rotate an org secret, 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).
|
|
- Bucket workflows: safe recursive deletes, command-specific remote refs (`bucket/key` and `s3://bucket/key`, with `buckets cp` requiring `s3://` for remote operands), auto multipart uploads, `sync --dry-run`, presigned URLs, and AWS profile configuration for `buckets.excloud.dev`.
|
|
- 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-dev/excloud-skills --skill <name>` once merged.
|
|
|
|
## License
|
|
|
|
TBD.
|