AGENTS.md

Guidance for AI agents working with this repository.

Overview

Skills for generating unit tests with consistent quality. Each skill is self-contained.

Skills

Recommended Workflow

The skills are meant to run in sequence, and the agent is the one that chains them: generate-test-cases produces the plan, generate-tests generates from that plan instead of analyzing the target a second time. Both analyze the same way and print the same list, so invoking the second without handing it the first one's output does the work twice.

1. generate-test-cases <target> — lists the cases as Given-When-Then, writes no code
2. generate-tests <target> — generates from that list, naming what it added or dropped

/generate-tests invoked on its own is the safe fallback, not a second path to maintain: with no list in front of it, it builds one in its own Step 2 and prints it before writing code. Each skill runs end to end without stopping for input, so that printed list is the record of what it decided to do.

This file guides agents working on this repository. The copy that reaches consuming projects is templates/AGENTS-SNIPPET.md — a change to the workflow belongs in both.

Rules Location

Rules are inside each skill folder:

• generate-test-cases/rules/general/ — general rules only
• generate-tests/rules/tests/ — all rules (general, java, post-generation)

Plugin Validation

This repository doubles as a Claude Code plugin and a marketplace, declared in .claude-plugin/. Both manifests must stay valid, because the community-marketplace review pipeline runs claude plugin validate on every submission.

After changing anything under .claude-plugin/ or skills/, run:

./scripts/validate-plugin.sh

CI runs the same script on every pull request touching those paths (.github/workflows/validate-plugin.yml). No credentials are needed — validation is entirely local.

What it checks, and why each check exists

Conventions that follow from this

• Declare version in plugin.json only. Repeating it in the marketplace entry adds a way for the two to drift, and the entry's copy is ignored.
• The plugin name is immutable once published — it is the install id and the skill namespace (/unit-tests-skills:generate-tests). Do not rename it.
• Keep skills/ at the repository root. Only plugin.json and marketplace.json belong inside .claude-plugin/.

Rule Validation

A skill is only as good as the rules it actually loads, and every way that can break is silent at runtime: the agent reads SKILL.md, follows a reference to a rule that is not there, and generates tests without it. Nothing errors — the output just gets worse.

After adding, renaming, moving, or deleting anything under a skill's rules/, run:

./scripts/validate-rules.sh

CI runs the same script in its own workflow (.github/workflows/validate-rules.yml), on every pull request rather than only ones touching skills/. Two reasons it is separate from plugin validation: it needs no Node and no CLI, so a broken upstream release cannot take it down; and it carries no path filter, so it always reports and is safe to require before merge. A required check that gets skipped never reports, and a pull request waiting on a check that will never arrive cannot merge.

What it checks, and why each check exists

Conventions that follow from this

• A new rule takes two edits, not one: the file itself and an entry in the relevant SKILL.md. The second check fails without it.
• Edit general rules in both locations in the same commit. Fixing one copy and leaving the other for later fails the third check.

Creating a New Skill

Directory Structure

skills/
  {skill-name}/
    SKILL.md
    rules/          # Rules used by this skill

Naming Conventions

• Skill directory: kebab-case (e.g., generate-tests, generate-test-cases)
• SKILL.md: Always uppercase, exact filename

SKILL.md Format

---
name: skill-name
description: One sentence describing when to use this skill.
allowed-tools: Read, Write, Glob, Grep
---

# Skill Title

What this skill does.

## Rules Reference

List rule files from `./rules/` directory.

## Instructions

**Target:** $ARGUMENTS

Steps:
1. First step
2. Second step
3. ...

Tools a Skill May Declare

Keep allowed-tools to tools every agent runtime provides. AskUserQuestion is Claude Code's own — Codex and the other agents this distribution targets (README.md, "Recommended for other agents") have no equivalent, so a skill that stops to ask the user works in one runtime and silently does nothing in the rest.

Skills here run end to end and print what they decided instead. Do not add a tool that pauses for input, and do not set context: fork — a forked skill's output does not reach the user, which is the whole point of printing the plan.

Adding a New Rule

Add rules inside the skill folder that uses them:

skills/{skill-name}/rules/
  general/
    {rule-name}.md
  {language}/unit/
    {rule-name}.md

Then list it in that skill's SKILL.md and run ./scripts/validate-rules.sh. See Rule Validation for what the checks enforce.

Rule File Format

## Rule Title

Why this rule matters.

**Incorrect:**

```java
// Bad example

Correct:

// Good example

Guidelines

1. Guideline one
2. Guideline two