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 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; 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

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

mkdir -p skills/<skill-name> (kebab-case; matches name: in frontmatter).
Create skills/<skill-name>/SKILL.md with the frontmatter above.

Verify the skill loads cleanly:

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

Update the "Available skills" section of README.md with a short blurb and the main use-cases.
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:

Install the branch locally: npx skills add <path-to-local-checkout> --skill <name> -a claude-code.
Ask the agent to do something the skill targets (create a VM, fetch a kubeconfig, etc.).
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.

5.3 KiB Raw Blame History