Guide · Agent skill
How to use the gentle-ai Bench Journeys agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gentle-ai-bench skill is a set of project rules that an AI agent loads when it works on the gentle-ai benchmark 'journey' tests, which script realistic end-to-end use of the product. This guide is for contributors who write or change those journeys, and for maintainers and reviewers who need proof that journeys actually ran. After reading it you will know what the skill changes about the agent's behaviour, how to install it, how to trigger it, and what the project expects before a journey change ships.
gentle-ai Bench JourneysGentleman-Programming/gentle-ai · MIT Download the skill Quick start
- 1Download and unzip. Download the ZIP from this page and unzip it so that SKILL.md sits in a gentle-ai-bench folder.
- 2Place the folder. Copy the folder to ~/.claude/skills/ for personal use or to .claude/skills/ inside your project. Alternatively, upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Open a gentle-ai checkout. Work inside a gentle-ai repository that contains bench/ and .github/workflows/ci.yml.
- 4Ask a bench question. Make a request that uses a trigger word such as bench, journey or gentle-ai-bench, so the agent loads the skill.
- 5Run declarations and the harness. Run go test ./... in bench/, then build the binary and run gentle-ai-bench run --binary with the exact command from the CI Unit Tests step.
- 6Report the summary. Include the driven-mode summary line from your locally built binary in the PR body alongside the go test output.
What are agent skills, and what does this one do?
An agent skill is a folder containing a SKILL.md file. The file gives an AI agent instructions it can load when a task matches the skill's description. This skill's file is named SKILL.md and has the name gentle-ai-bench.
Once loaded, the skill tells the agent that a passing unit-style check does not prove a journey runs. Running go test ./bench only validates the corpus declarations. To prove execution, the agent must build the harness and the product binary and run the harness against that binary. The skill also sets rules for journey IDs, review settings and stale expectations.
- Keeps journey IDs unique across every journeys_*.go file.
- Requires every journey to declare a Review setting.
- Asks for stale journeys to be checked when a product behaviour changes.
- Requires PR evidence from a locally built binary, including the driven-mode summary line.
How do you install the gentle-ai-bench skill?
Download the ZIP from this page and unzip it. For a personal setup, place the resulting gentle-ai-bench folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills. Check that the folder contains SKILL.md at its top level after unzipping, since that is the file the skill is defined by.
- Personal: ~/.claude/skills/gentle-ai-bench/
- Project: .claude/skills/gentle-ai-bench/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
What do you need before using it?
The skill assumes you are working inside a gentle-ai repository checkout. It expects the bench/ directory and .github/workflows/ci.yml to exist, because the skill tells the agent to copy its build and run commands from the CI workflow rather than guessing them.
You also need a Go toolchain to run go test and build the binary, plus a locally built gentle-ai binary and the gentle-ai-bench harness. The skill does not install any of these for you.
- Go toolchain
- A gentle-ai repository checkout with bench/ and .github/workflows/ci.yml
- A locally built gentle-ai binary
- The gentle-ai-bench harness
How do you trigger the skill with natural requests?
The skill's description lists trigger words: bench, journey, journeys, driven mode, gentle-ai-bench, journey corpus, j-numbers and bench axis. Mention one of these in your request and the agent should load the skill. You can also name the skill directly.
The skill also loads when the work touches bench/, when you add or change a journey, when you change a product behaviour a journey might check, or when you diagnose a bench failure in CI's Unit Tests job.
- 'Add a journey that checks the review switch is on by default.'
- 'Why is the Unit Tests job failing on a bench journey?'
- 'Use gentle-ai-bench to drive only the journey with ID j-12 and report the summary.' (replace j-12 with a real ID from your corpus)
- 'I changed how reviews default. Which journeys pin the old behaviour?'
How do you run journeys and report the result?
Follow the skill's steps: read the corpus area you are changing and the CI invocation first. Copy the exact build and gentle-ai-bench run --binary commands from the Unit Tests step in .github/workflows/ci.yml. Use --only with a journey ID to drive a single journey.
Run go test ./... inside bench/ for declarations, then run the driven harness for execution. Put both results in the PR body. The driven-mode summary line (completed, unsupported and failed counts) must come from a locally built binary, not only from go test output.
- Declarations: go test ./... run inside bench/
- Execution: build the binary and run gentle-ai-bench run --binary against it, copying the exact command from CI
- One journey: add --only <journey-id>
go test ./bench
gentle-ai-bench run --binary ...
gentle-ai-bench run --binary ... --only <journey-id>What are the key rules for writing a journey?
Every journey must declare Review as either reviewOptedIn or reviewUntouched. Without this declaration, validateCorpus fails the run. Reviews default to ON, and reviewUntouched does not imply OFF, so a journey that needs OFF must disable it explicitly.
Every execute transition needs a runnable command, or the dead-execute guard fails the run. The dead_end column prints n/a unless the run actually measured a value, and you must never fabricate one. A by_design exemption needs a shape from the closed vocabulary and a verified quote of the product's own next-action text.
- Review: reviewOptedIn (receipt-driven development is enabled before the first step) or reviewUntouched (the journey's subject is the switch, or it is unrelated to reviews)
- Prefer a new journeys_*.go file when shared files are owned by open PRs, and bump the core journey-count pin in the same change
- Record why each expectation holds in the journey title, step names or comment, citing the issue or ratified decision
What people use it for
- Adding a new journey for a product behaviour and declaring its Review setting correctly.
- Diagnosing why a bench journey fails in CI's Unit Tests job by reproducing the CI command locally.
- Finding journeys that still pin old behaviour after a ratified product change.
- Giving a reviewer PR evidence that journeys were executed, not just declared.
Frequently asked questions
Is the gentle-ai-bench skill free to use?
The directory lists the item under the MIT licence, but the SKILL.md frontmatter states Apache-2.0. Check the licence file in the gentle-ai repository before reusing the skill outside the project.
What do I need to install gentle-ai-bench?
You need a Go toolchain, a gentle-ai repository checkout that includes bench/ and .github/workflows/ci.yml, a locally built gentle-ai binary and the gentle-ai-bench harness. The skill itself only consists of SKILL.md and does not install these tools.
Does the skill run tests for me?
No. The skill only guides the agent. The commands it mentions must be run by you or the agent in a suitable environment, and the skill does not run scripts or use the network.
Why does go test ./bench pass but the journey still fails?
go test ./bench only validates corpus declarations and never executes journeys. To prove a journey runs, build the product binary and run the gentle-ai-bench harness against it.
How do I run just one bench journey?
Use the --only flag with a journey ID, as in gentle-ai-bench run --binary ... --only <journey-id>. Copy the rest of the command from the Unit Tests step in .github/workflows/ci.yml.
Can I use this skill outside the gentle-ai project?
It is not meant for that. It assumes the project's specific files, CI workflow and Go test layout, and its rules are project-specific. Other Go or testing work will not benefit from it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you contribute to gentle-ai bench journeys, maintain the Unit Tests job, or review PRs that need proof of execution. Pick something else if you work outside the gentle-ai project or need general Go testing help, because the rules are specific to this corpus and the skill cannot run tests on your behalf.
Download the skill