Add AI agent/tool skills#4568
Conversation
Add an OpenCode agent skill that guides AI coding agents through the core coreos-assembler workflow: initializing a build directory, building from source or fetching published builds, and launching local QEMU VMs. The skill acts as a workflow guide rather than duplicating documentation. It references the canonical docs (docs/building-fcos.md, docs/cosa/run.md, src/cmd-init, src/cmd-buildfetch, etc.) and instructs the agent to read them at runtime for command details. This avoids staleness from having multiple sources of truth. Key workflow covered: - Step 1: Set up a COSA workdir (cosa init) - Step 2a: Build from source (cosa build + cosa osbuild qemu) - Step 2b: Fetch a published build (cosa buildfetch), defaulting to --artifact qemu --decompress for local QEMU usage - Step 3: Launch a VM (cosa run) Both container mode (default, via the cosa() bash alias) and local development mode are documented. Cloud platform workflows are explicitly out of scope for a future cosa-cloud skill. Assisted-by: <anthropic/claude-opus-4.6>
Just adds some clarity to the options and how they behave. Assisted-by: <anthropic/claude-opus-4.6>
We dropped testiso as a separate command in anomalyco/opencode#23794 so let's update the docs. Assisted-by: <anthropic/claude-opus-4.6>
Added more context here, including more of the options that `kola supports`. Assisted-by: <anthropic/claude-opus-4.6>
Add a skill that guides through the cosa kola test workflow: finding tests, running them, and checking results. The skill references docs/kola.md and docs/kola/external-tests.md for detailed flag and format documentation rather than duplicating them. Assisted-by: <anthropic/claude-opus-4.6>
cosa-kola's Prerequisites section duplicated build/fetch commands already covered by cosa-basics. Replace with a directive to load the cosa-basics skill, and add a reverse reference from cosa-basics to cosa-kola for running tests. Assisted-by: <anthropic/claude-opus-4.6>
Explain that ext.config.* test names map to paths under src/config/tests/kola/ in the cosa workdir. Include the dot-to-slash naming convention, which files to look for (test.sh, kola.json, config.bu), and concrete examples. Assisted-by: <anthropic/claude-opus-4.6>
The stream is auto-detected from the build ID version number when --build is provided. Update the example and explanation to reflect this, including the version-to-stream mapping examples. Assisted-by: <anthropic/claude-opus-4.6>
The buildextend-* commands are deprecated symlinks. Disk images are now built with 'cosa osbuild <platform>' and uploaded to cloud providers with 'cosa imageupload-<platform>'. - Rename docs/cosa/buildextend-aws.md to imageupload-aws.md - Rename docs/cosa/buildextend-secex.md to osbuild-secex.md - Update docs/design.md, docs/kola.md, docs/working.md, and mantle/README.md to use the new command names - Add imageupload-* commands to docs/cosa.md command reference - Rename 'Extended artifacts' section in docs/kola.md to 'Testing platform artifacts' Assisted-by: <anthropic/claude-opus-4.6>
cosa run is QEMU-only. Add a section pointing users to 'cosa kola spawn -p <platform>' for spawning instances on cloud platforms, with examples for AWS and GCP. Assisted-by: <anthropic/claude-opus-4.6>
New skill covering non-QEMU platform workflows: building disk images with 'cosa osbuild', uploading via 'cosa imageupload-*', running kola tests with '-p <platform>', and spawning cloud instances with 'kola spawn'. Includes a platform reference table, credential pointers, and workflow steps. Assisted-by: <anthropic/claude-opus-4.6>
Update cosa-basics to point to the actual cosa-platforms skill name instead of the placeholder 'cosa-cloud'. Add a directive in cosa-kola to load cosa-platforms when testing on non-QEMU platforms. Assisted-by: <anthropic/claude-opus-4.6>
When cloud images already exist for a build (e.g. AMIs uploaded to AWS), there is no need to fetch disk artifacts or decompress them. A plain 'cosa buildfetch -b <build-id>' fetches only meta.json, which contains the cloud image references that kola picks up automatically. Update cosa-platforms with a dedicated note explaining this shortcut and update cosa-basics to clarify when --artifact/--decompress are needed vs. when they can be skipped. Assisted-by: <anthropic/claude-opus-4.6>
Covers three workflows for iterating on cosa code: 1. Building mantle Go binaries (kola, ore, plume) inside the cosa container and mounting them over the installed copies for testing, with persistent Go build cache for fast incremental rebuilds. 2. Using COREOS_ASSEMBLER_GIT to mount modified Python/shell scripts from src/ without any rebuild. 3. Full container rebuild via podman build for Dockerfile or dependency changes. Assisted-by: <anthropic/claude-opus-4.6>
This should help getting blocked when querying Fedora's infra for information.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces new AI skill definitions (cosa-basics, cosa-dev, cosa-kola, and cosa-platforms) and adds a guide on how to use them. It also updates existing documentation to replace deprecated buildextend-* commands with the modern cosa osbuild and cosa imageupload equivalents. The review feedback focuses on standardizing credential paths, correcting non-standard -v= volume mount syntax in container examples, and addressing minor grammatical and semantic issues.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
| | Azure | `azure` | `--azure-disk-uri` | `~/.azure/azureCreds.json` | | ||
| | DigitalOcean | `do` | `--do-image` | `~/.config/digitalocean.json` | | ||
| | ESX/VMware | `esx` | `--esx-base-vm` | `~/.config/esx.json` | | ||
| | GCP | `gcp` | `--gcp-image` | GCP service account JSON key | |
There was a problem hiding this comment.
To maintain consistency with the other rows in the table (which specify default credential file paths like ~/.aws/credentials or ~/.azure/azureCreds.json), the default credentials path for GCP should be specified as ~/.config/gcp.json instead of describing the credential type.
| | GCP | `gcp` | `--gcp-image` | GCP service account JSON key | | |
| | GCP | gcp | --gcp-image | ~/.config/gcp.json | |
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\ | ||
| -v=/path/to/coreos-assembler:/srv/cosa-src:ro \ | ||
| -v=/tmp/cosa-bin:/srv/cosa-bin:rw \ | ||
| -v=/tmp/cosa-go-cache:/home/builder/.cache/go-build:rw" |
There was a problem hiding this comment.
Using -v= (with an equals sign) for short options is non-standard and can cause parsing issues or confusion. It is better to use -v (with a space) for short options, or --volume= for long options, to align with standard Docker/Podman CLI usage and other parts of the documentation.
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\ | |
| -v=/path/to/coreos-assembler:/srv/cosa-src:ro \ | |
| -v=/tmp/cosa-bin:/srv/cosa-bin:rw \ | |
| -v=/tmp/cosa-go-cache:/home/builder/.cache/go-build:rw" | |
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\\ | |
| -v /path/to/coreos-assembler:/srv/cosa-src:ro \\ | |
| -v /tmp/cosa-bin:/srv/cosa-bin:rw \\ | |
| -v /tmp/cosa-go-cache:/home/builder/.cache/go-build:rw" |
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\ | ||
| -v=/tmp/cosa-bin/kola:/usr/bin/kola:ro" |
There was a problem hiding this comment.
Use -v (with a space) instead of -v= to follow standard Docker/Podman CLI syntax.
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\ | |
| -v=/tmp/cosa-bin/kola:/usr/bin/kola:ro" | |
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\\ | |
| -v /tmp/cosa-bin/kola:/usr/bin/kola:ro" |
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\ | ||
| -v=/tmp/cosa-bin/kola:/usr/bin/kola:ro \ | ||
| -v=/path/to/aws-creds:/srv/aws-creds:ro" |
There was a problem hiding this comment.
Use -v (with a space) instead of -v= to follow standard Docker/Podman CLI syntax.
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\ | |
| -v=/tmp/cosa-bin/kola:/usr/bin/kola:ro \ | |
| -v=/path/to/aws-creds:/srv/aws-creds:ro" | |
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\\ | |
| -v /tmp/cosa-bin/kola:/usr/bin/kola:ro \\ | |
| -v /path/to/aws-creds:/srv/aws-creds:ro" |
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\ | ||
| -v=/tmp/cosa-bin/kola:/usr/bin/kola:ro" |
There was a problem hiding this comment.
Use -v (with a space) instead of -v= to follow standard Docker/Podman CLI syntax.
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\ | |
| -v=/tmp/cosa-bin/kola:/usr/bin/kola:ro" | |
| export COREOS_ASSEMBLER_CONTAINER_RUNTIME_ARGS="\\ | |
| -v /tmp/cosa-bin/kola:/usr/bin/kola:ro" |
| # Working with COSA's AI skills | ||
| {: .no_toc } | ||
|
|
||
| Example tasks to hand to an AI tool (i.e. opencode, goose) leveraging |
There was a problem hiding this comment.
Use e.g. (exempli gratia, meaning 'for example') instead of i.e. (id est, meaning 'that is') since 'opencode' and 'goose' are examples of AI tools, not an exhaustive definition.
| Example tasks to hand to an AI tool (i.e. opencode, goose) leveraging | |
| Example tasks to hand to an AI tool (e.g., opencode, goose) leveraging |
| prevent abuse. When querying APIs or web pages for information set a | ||
| User-Agent and Accept headers to increase the chance of making it |
There was a problem hiding this comment.
Add a comma after 'information' for better readability, and correct 'set a User-Agent and Accept headers' to 'set User-Agent and Accept headers' (or 'set a User-Agent and an Accept header') to fix the grammatical agreement.
| prevent abuse. When querying APIs or web pages for information set a | |
| User-Agent and Accept headers to increase the chance of making it | |
| prevent abuse. When querying APIs or web pages for information, set | |
| User-Agent and Accept headers to increase the chance of making it |
dustymabe
force-pushed
the
dusty-add-agent-skills
branch
from
f5b253f to
795420f
Compare
There was a problem hiding this comment.
While running cosa-basics I came across two issues:
-
Started with a simple
Fetch the latest stable FCOS build and launch a QEMU VM. After the fetching was done agent instructed to cd into the build directory and simplycosa run. This didn't work as my coreos-assembler image was outdated. I had to first run podman pull... to move onto the next step. -
Once coreos-assembler was updated cosa run didn't work because of
Error: creating container storage: the container name "cosa" is already in use...I guess the skill could be improved by adding :do not runcosa runas this leaves dangling containers.
Out of curiosity I also recorded the usage for this simple skill run:
Usage by model:
claude-opus-4-6: 3.6k input, 2.9k output, 180.9k cache read, 99.4k cache write
| {: .no_toc } | ||
|
|
||
| Example tasks to hand to an AI tool (i.e. opencode, goose) leveraging | ||
| the skills under .agents/skills. To leverage a skill run `/skills` and |
There was a problem hiding this comment.
I tried to run this skill in claude as I don't have mentioned in docs opencode or goose installed. Since claude Code looks for skills under .claude/skills/, not .agents/skills/. I got them working by symlinking:
mkdir -p .claude/skills
ln -s ../../.agents/skills/cosa-basics .claude/skills/cosa-basics
ln -s ../../.agents/skills/cosa-kola .claude/skills/cosa-kola
ln -s ../../.agents/skills/cosa-dev .claude/skills/cosa-dev
ln -s ../../.agents/skills/cosa-platforms .claude/skills/cosa-platforms
| This skill covers workflows for making and testing changes to | ||
| coreos-assembler (COSA) itself, including the Go binaries in `mantle/`, | ||
| the Python/shell scripts in `src/`, and the container image. | ||
|
|
There was a problem hiding this comment.
I ran this skill three times with the same prompt: "Add a --hello flag to mantle/cmd/kola/main.go that prints "hello from kola" and exits. Build the modified kola binary and verify it works with cosa kola --hello".
I succeeded only at the very last aproach after a little bit of tweaking. During the first two runs the agent bypassed the cosa container workflow completely - it ran go build and /tmp/kola --hello instead of building and testing insite the cosa container. When it couldn't run cosa kola it just said "can't test, cosa requires the container environment" and stopped.
Adding "Important" and "Prerequistes" section that explain how to set up the cosa alias and workdir before starting, instead of pointing to a separate skill. After that, the agent followed approach 1 as expected.
Again, interestingly the failed attempts used more tokens than the correct one:
Failed:
Usage by model:
claude-opus-4-6: 93 input, 3.4k output, 818.5k cache read, 98.3k cache write ($1.11)
Correct:
Usage by model:
claude-opus-4-6: 421 input, 3.1k output, 480.4k cache read, 54.2k cache write ($0.66)
| ## IMPORTANT: Always use the COSA container | |
| COSA is designed to run inside a container. You MUST NOT: | |
| - Run `go build` directly on the host | |
| - Run `mantle/build` or `make kola` directly on the host | |
| - Run `./build.sh` directly on the host | |
| - Execute built binaries directly on the host (e.g. `./bin/kola`, `/tmp/kola`) | |
| All building and testing MUST go through the `cosa` alias, which runs | |
| commands inside the COSA container. If `cosa` is not available, set it | |
| up first (see Prerequisites below) -- do not fall back to building | |
| on the host. | |
| ## Prerequisites | |
| Before using any approach below, you MUST: | |
| 1. **Set up the `cosa()` bash alias** -- check if `cosa` is already | |
| available in the user's shell (`type cosa`). If not, see the | |
| Key documentation references below for setup instructions. | |
| 2. **Have a cosa workdir** -- a directory where `cosa init` was previously | |
| run (contains `src/config/`, `builds/`, `tmp/`, etc.). Ask the user | |
| where their existing workdir is, or create one: | |
| ` | |
| mkdir myworkdir && cd myworkdir | |
| cosa init https://github.com/coreos/fedora-coreos-config | |
| ` | |
| All `cosa` commands must be run from inside a cosa workdir. | |
There was a problem hiding this comment.
I'll consider this. I've still been developing on these in the background and trying to make it easier for non-frontier models to work with.
That being said I don't know if telling the harness not to execute those commands "on the host" is the right thing.
"the host" is the environment the harness is running in. It could be an environment where users do develop cosa. It could be a slimmed down sandbox (no golang toolchain to build). It could be direct access to the host. It could be running inside a COSA container already. So I think we have to be careful with the guidance here.
|
I also went through all the docs updates (other than |
Thanks @c4rt0. I'll probably push up and update to these "skills" early next week. I've learned a lot in the past week. |
2 participants
The PR introduces several "skills" for use by AI agents/tools. These skills should enable some simple on up to advanced tasks to be handled in an open session/discussion with an advanced model.
See
docs/using-ai-skills.mdfor examples of prompts to run.