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