Guide · Agent skill
How to use the Project Test Suite Health Checker agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Project Test Suite Health Checker is an agent skill, a folder with a SKILL.md instruction file that tells an AI agent how to carry out a specific job. This one is built for the gbrain repository: it checks that skills are structured correctly, runs the project's tiered tests, and explains why tests failed. This guide shows you how to install it, trigger it with plain requests, and understand what it will and won't do.
Project Test Suite Health Checkergarrytan/gbrain · MIT Download the skill Quick start
- 1Download the ZIP. Download the testing skill ZIP from this page.
- 2Unzip into the skills folder. Unzip it into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ folder for one project.
- 3Check the prerequisites. Make sure Bun, a Git repository with history, the gbrain CLI and Postgres access are available.
- 4Open the gbrain repository. Start your agent inside the gbrain repository so the paths and manifests the skill checks are present.
- 5Ask for a conformance check. Say "validate skills" to get a Skill Validation Report.
- 6Ask for a test run. Say "what's broken" or "run the tests" to get the daily report with failures classified.
- 7Review the report. Check each classification, especially any regression or security failure, before changing code or tests.
What the skill makes the agent do
The skill has two modes. In skill conformance validation, the agent checks that every skill directory has a SKILL.md with valid frontmatter, that skills/manifest.json and skills/RESOLVER.md list every skill, and that no two skills share the same trigger phrases.
In project test-suite health mode, the agent runs the tests in tiers (unit, evals, integration and system health), uses git history to work out why a failing test broke, sorts each failure into a category, and writes a daily report. It also keeps a history file at ~/.gbrain/test-state.json so you can see trends over time.
- Unit: bun test, deterministic with no external calls
- Evals: LLM-judge or quality evals, run daily if the project has an evals config
- Integration: end-to-end tests against real Postgres, run before shipping and nightly
- System health: disk, memory, CPU, service liveness and gbrain doctor --fast --json
- Failure categories: REGRESSION, STALE, FLAKE, NEW and INFRA
Install the testing skill
Download the skill ZIP from this page. Then choose one of two routes. For a personal install, unzip it into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.
You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: unzip into ~/.claude/skills/
- Single project: unzip into the project's .claude/skills/
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the requirements before you start
The skill is designed for the gbrain repository and needs several tools available. Without them, the matching checks will fail or be skipped.
- Bun, to run bun test
- A Git repository with history, since failure analysis reads recent commits
- The gbrain CLI, for the gbrain doctor health check
- Access to a Postgres database for integration tests
Trigger the skill with natural requests
You don't need a special command. The skill responds to phrases like the ones below. Mode 1 is used for skill validation requests, and mode 2 for test runs and health questions. The skill description lists the trigger phrases it matches.
- "validate skills" or "skill health check" (mode 1)
- "test skills" or "run conformance tests" (mode 1)
- "run the tests" or "how are the tests" (mode 2)
- "what's broken" (mode 2)
- "daily test run" (mode 2)
bun test test/skills-conformance.test.ts test/resolver.test.ts test/openclaw-plugin-manifest.test.tsExample requests and what you get back
For a conformance check, ask "validate skills". The agent returns a Skill Validation Report with counts for skills found, conformance, manifest coverage, resolver coverage, round-trip checks and MECE violations, followed by a list of issues by skill.
For a test run, ask "what's broken". The agent runs the tiers, compares changes from the last 24 hours in git, and returns a daily report. Each red test is marked as a regression, stale test, flake, new test or infrastructure problem, and the report says which commit broke it when that applies.
Safety notes: scripts and network
This skill runs scripts and uses the network. It runs bun test and the gbrain doctor command, and it reads your git log. Integration tests connect to a Postgres database, so review the database you point them at before running them.
The skill is marked as not mutating in its frontmatter, but auto-fix rules can change test files. It will not auto-fix behaviour mismatches or security test failures. Those go to you for a decision.
- Runs local commands (bun test, gbrain doctor, git log)
- Connects to Postgres for integration tests
- Auto-fixes only simple cases such as renamed paths, old version strings and removed files
- Always escalates security test failures to you
Tips for getting useful results
Run the skill after a significant code change, and treat its classifications as a starting point. The skill's own guidance warns that many red tests are stale or flaky, so classify before assuming a regression. Keep your history file so trend tracking has data to work with.
- Use the conformance mode right after adding a new skill, and update RESOLVER.md whenever you add a skill to manifest.json
- Don't ask the agent to un-skip a test without a reason for the skip
- If a failure comes from a missing API key, the report should name the key
What people use it for
- Maintainers getting a daily summary of unit, eval and health results for gbrain
- Developers asking why tests broke after a refactor, with the commit that caused it
- Contributors checking that a new skill has SKILL.md frontmatter and appears in manifest.json and RESOLVER.md
- Reviewers spotting two skills that claim the same trigger phrase
Frequently asked questions
Is the testing skill free and what is its licence?
The skill is listed under the MIT licence. Check the repository's licence file for the full terms before you reuse or redistribute it.
What do I need to run this skill?
You need Bun to run bun test, a Git repository with history, the gbrain CLI for gbrain doctor, and Postgres access for integration tests. It is built for the gbrain project and its paths.
Can I use this skill on a project other than gbrain?
Not as intended. The paths, manifests and commands are specific to the gbrain repository, so it is not a general test checker for other projects.
Where do I install the skill?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Will the skill fix my failing tests automatically?
Only in narrow cases, such as updating an old file path after a rename or an old version string. It does not auto-fix tests that expect different behaviour or security tests, because changing a test to match changed behaviour can hide a real bug.
Why does the skill sometimes report a failure as stale or flaky?
The skill classifies each red test before calling it a regression. A stale test expects old behaviour while the code is correct, and a flake comes from things like API timeouts or service downtime, so the report separates these from real code breaks.
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
This skill suits gbrain maintainers, developers diagnosing test breaks, and contributors adding skills who want structural checks. If you only use gbrain for everyday tasks or work on a different project, pick a general test or linting tool instead, and don't let it auto-fix tests unattended.
Download the skill