init

AGENTS.md

@@ -0,0 +1,104 @@
+# AGENTS.md
+
+Guidance for AI coding agents (Claude Code, Cursor, Codex, opencode, ...) and human contributors editing this repository. This file is loaded automatically by agents that honour `AGENTS.md` conventions.
+
+## What this repo is
+
+A collection of [agent skills](https://agentskills.io/) for working with Excloud. Skills are `SKILL.md` playbooks that an agent loads on demand; they are prose, not code. They encode Excloud-specific knowledge (auth, safety rails, command syntax, error recovery) that the agent would otherwise have to rediscover each run.
+
+Skills are installed with [`npx skills add`](https://www.npmjs.com/package/skills); see `README.md` for user-facing install instructions.
+
+## Directory layout
+
+```
+skills/
+  <skill-name>/              # kebab-case, matches the `name:` in SKILL.md frontmatter
+    SKILL.md                 # required; the playbook
+    scripts/                 # optional; executable helpers the skill references
+      *.sh                   # prefer bash; mark chmod +x
+    references/              # optional; long-form docs the skill links to
+      *.md
+```
+
+One skill per directory. Do not put multiple skills' playbooks in the same `SKILL.md`.
+
+## SKILL.md conventions
+
+### Frontmatter
+
+```yaml
+---
+name: <kebab-case-name>
+description: <one or two sentences: what the skill does and when an agent should load it>
+---
+```
+
+- `name` must match the parent directory name and be unique across the repo.
+- `description` is what the agent sees before it decides to load the skill — write it as a trigger hint. Name the resource or verb, the pain point it addresses, and ideally a couple of trigger phrases.
+- Optional: `metadata.internal: true` hides the skill from default discovery; users opt in with `INSTALL_INTERNAL_SKILLS=1`.
+
+### Body
+
+Write for an agent that has never seen this surface. The best skills:
+
+- Tell the agent what to **discover before acting** (`list` / `get` / `--help`) rather than hard-coding IDs, flags, or versions.
+- Call out destructive operations explicitly and tell the agent to confirm first.
+- State the auth model once, plus what "not authenticated" looks like.
+- Capture real error strings the CLI or API emits, paired with the actual cause and fix. These are pure gold — they turn agent flailing into one-shot recovery.
+- Document output shapes (table vs. JSON vs. Go-struct dump) so the agent picks the right parser (`awk`, `jq`, or "don't parse this").
+- Prefer "here is the shape you'll see" over "here is the schema" when the surface shifts often.
+- Open with a disclaimer that the installed tool's `--help` is canonical and this file can drift. The agent should trust the tool over the skill when they disagree.
+
+Avoid:
+
+- Hard-coded account / org / resource IDs.
+- Personal paths like `~/Projects/…` or `/Users/<name>/…` (those leak into generated commands).
+- Source-tree pointers (consumers of the skill won't have the repo checked out).
+- Any secret material (tokens, keys, passwords) — even in examples.
+- `"last updated"` timestamps or version numbers in the body; they rot fast.
+
+### Length
+
+Keep `SKILL.md` under ~400 lines when you can. If a topic needs more, split it into a `references/<topic>.md` and link to it from `SKILL.md`.
+
+## Adding a new skill
+
+1. `mkdir -p skills/<skill-name>` (kebab-case; matches `name:` in frontmatter).
+2. Create `skills/<skill-name>/SKILL.md` with the frontmatter above.
+3. Verify the skill loads cleanly:
+   ```bash
+   # list only — verifies the skill is discoverable without touching your agent dirs
+   npx skills add ./ --list
+
+   # real install from the local checkout
+   npx skills add ./ --skill <skill-name>
+   ```
+4. Update the "Available skills" section of `README.md` with a short blurb and the main use-cases.
+5. Open a PR. One skill per PR keeps review easy.
+
+## Editing an existing skill
+
+- Changes to `SKILL.md` should be reviewable as prose — small, focused edits, with the commit message explaining the _intent_ (e.g. "document --download flag on compute scp" beats "update skill").
+- If you verified a new behaviour against a live tool, mention the tool version or the date of verification in the PR description (not in the skill body).
+- If a section becomes stale because the upstream tool's surface shifted, prefer rewriting it to point the agent at `--help` rather than chasing every flag change.
+
+## Testing
+
+There is no build step. A "test" is: does an agent loaded with this skill do the right thing on a representative prompt? A useful flow:
+
+1. Install the branch locally: `npx skills add <path-to-local-checkout> --skill <name> -a claude-code`.
+2. Ask the agent to do something the skill targets (create a VM, fetch a kubeconfig, etc.).
+3. Watch for: does it discover IDs from `list`? Does it confirm before destructive ops? Does it recognise real error strings?
+
+If all three feel right, the skill is doing its job.
+
+## Style
+
+- Markdown only. Plain prose; lists for flag enumerations; fenced code blocks for commands.
+- Backticks around every flag, file path, env var, and command substring.
+- American or British English, pick one and stay consistent within a skill.
+- No emojis in `SKILL.md` unless the user explicitly asked for a playful tone somewhere.
+
+## Release / publish
+
+There is no package to publish. `npx skills add` clones this repo directly from `git.excloud.in` and reads `SKILL.md` files straight from the default branch, so merging to `main` is the release — no tags, no npm publish step.