Add AI agent/tool skills

.agents/skills/cosa-basics/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: cosa-basics
+description: Initialize a COSA workdir, build or fetch Fedora CoreOS images, and launch local QEMU VMs using coreos-assembler
+---
+
+# COSA Basics
+
+This skill guides you through the core coreos-assembler (COSA) workflow:
+initializing a build directory, obtaining a CoreOS build (either from source
+or by fetching a published build), and launching a local QEMU VM.
+
+## Out of scope
+
+Cloud platform image building and uploading (AWS, GCP, Azure, etc.) are not
+covered here. Load the **cosa-platforms** skill for those workflows.
+
+## Key documentation references
+
+Do NOT duplicate these docs. Read them at runtime for command details:
+
+| File | What it covers |
+|------|----------------|
+| `docs/building-fcos.md` | Full build walkthrough, prerequisites, the `cosa()` bash alias |
+| `docs/cosa.md` | Command reference overview (all cosa subcommands) |
+| `docs/cosa/run.md` | Detailed `cosa run` and QEMU VM options |
+| `docs/working.md` | Overrides, customization, advanced usage |
+| `docs/devel.md` | Running cosa locally outside a container |
+| `src/cmd-init` | `cosa init` source -- all supported flags |
+| `src/cmd-buildfetch` | `cosa buildfetch` source -- all supported flags |
+
+## Running COSA
+
+### Container mode (default)
+
+COSA is designed to run inside a container. The container image is:
+
+```
+quay.io/coreos-assembler/coreos-assembler
+```
+
+Before running any cosa commands, read `docs/building-fcos.md` and extract the
+`cosa()` bash alias function defined there. This alias wraps `podman run` with
+the necessary privileges, device mounts (`/dev/kvm`, `/dev/fuse`), user
+namespace mapping, and volume mounts. The current working directory is mounted
+as `/srv/` inside the container.
+
+Set up the alias in the user's shell before running any cosa commands.
+
+### Local mode (for cosa developers)
+
+Developers who have cosa installed locally can run commands directly without
+the container wrapper. Read `docs/devel.md` for details on this workflow. The
+commands themselves are the same; only the execution environment differs.
+
+## Workflow
+
+### Step 1: Set up a COSA workdir
+
+1. Ask the user for a working directory path. Default to `./fcos` if they
+   don't specify one.
+2. If the directory does not exist, create it.
+3. `cd` into the directory.
+4. Set up the `cosa()` bash alias (read it from `docs/building-fcos.md`).
+5. Initialize the workdir:
+
+```
+cosa init https://github.com/coreos/fedora-coreos-config
+```
+
+The user can override the config repo URL. Additional useful flags (read
+`src/cmd-init` for the full list):
+
+- `--branch BRANCH` -- use a specific branch of the config repo
+- `--variant VARIANT` -- select a build variant
+- `--force` -- allow init in a non-empty directory
+
+After init, the directory structure will contain `src/config/` (the cloned
+config repo), plus `builds/`, `cache/`, `tmp/`, and `overrides/` directories
+that are populated during builds.
+
+### Step 2: Obtain a build
+
+Choose one of the following paths based on what the user wants to do.
+
+#### Option A: Build from source
+
+This builds a fresh CoreOS image from the config repo and RPM sources:
+
+```
+cosa build
+cosa osbuild qemu
+```
+
+`cosa build` creates the bootable OCI container (ostree commit). `cosa osbuild
+qemu` derives a QEMU disk image from that container. Both are required before
+`cosa run` will work.
+
+Note: `cosa fetch` is a no-op in the current build flow. Package fetching
+happens automatically inside `cosa build` via buildah.
+
+#### Option B: Fetch an existing published build
+
+This downloads a previously published build from the Fedora CoreOS build
+servers. Use this when you want to test or inspect an existing release without
+building from source.
+
+**Default flags:** Include `--artifact qemu --decompress` when the user
+needs a local QEMU disk image (e.g. for `cosa run` or QEMU-based kola
+tests). The published artifacts are stored compressed on the server;
+`--decompress` expands them so the resulting qcow2 can be used directly.
+
+If the user only needs to run tests on a cloud platform where images already
+exist (e.g. AMIs in AWS), `--artifact` and `--decompress` are not needed.
+A plain `cosa buildfetch -b <build-id>` fetches only a few small metadata
+files (including `meta.json`), which contain cloud image references that
+kola picks up automatically. See the **cosa-platforms** skill for details.
+
+**Fetch the latest build for a stream:**
+
+```
+cosa buildfetch --stream <stream> --artifact qemu --decompress
+```
+
+Available streams: `stable`, `testing`, `testing-devel`, `next`, `rawhide`
+
+If the user does not specify a stream, default to `stable`.
+
+**Fetch a specific build by ID:**
+
+```
+cosa buildfetch -b <build-id> --artifact qemu --decompress
+```
+
+When `-b`/`--build` is given, `--stream` is not required -- the stream is
+auto-detected from the build ID's version number (the third dotted component
+maps to a stream, e.g. `.2.` = `testing`, `.3.` = `stable`). Read
+`src/cmd-buildfetch` for the full version-to-stream mapping. If `--stream`
+is also provided it must match or the command will error.
+
+**If the user wants a non-qemu artifact:** replace `--artifact qemu` with the
+appropriate artifact name (e.g., `metal`, `aws`, `gcp`). But note that cloud
+platform workflows are better served by the **cosa-platforms** skill.
+
+### Step 3: Launch the VM
+
+```
+cosa run
+```
+
+This launches a QEMU VM using the latest build image with `-snapshot` (changes
+are discarded on exit). By default it establishes an SSH connection with
+auto-login as the `core` user.
+
+**Common options** (read `docs/cosa/run.md` for the full list):
+
+| Flag | Purpose |
+|------|---------|
+| `-c` / `--devshell-console` | Use serial console instead of SSH (see full boot, GRUB menu) |
+| `--qemu-image PATH` | Use a specific qcow2 image instead of the latest build |
+| `-B` / `--butane PATH` | Pass a Butane config for the VM |
+| `-i` / `--ignition PATH` | Pass an Ignition config for the VM |
+| `--add-disk SIZE[:OPTS]` | Attach additional disks |
+| `--kargs 'ARGS'` | Append kernel arguments |
+| `-m SIZE` | Set VM memory in MB |
+
+**Exiting the VM:**
+
+- SSH mode: `exit` or `Ctrl-D`
+- Console mode: `Ctrl-a x`
+
+## Important notes
+
+- Each `cosa` command (via the alias) creates a transient container. Use
+  `cosa shell` for a persistent interactive session inside the container.
+- `/dev/kvm` is required for both building disk images and running VMs. The
+  host must be bare metal or have nested virtualization enabled.
+- The build directory at `$PWD` is mounted at `/srv/` inside the container.
+  Build artifacts persist across container invocations.
+- The workdir's `builds/latest` symlink always points to the most recent build.
+- To run kola tests against a build, load the **cosa-kola** skill. It covers
+  test discovery, `cosa kola run`, upgrade tests, and result inspection.
+- Fedora infrastructure services (like Bodhi or Koji) are behind Anubis to
+  prevent abuse. When querying APIs or web pages for information set a
+  User-Agent and Accept headers to increase the chance of making it
+  through unchallenged.