Agent skills

Ward ships three agent skills. A skill is a SKILL.md file that teaches a coding agent a workflow. With these skills, your agent sets up Ward with you: it looks at the project first, explains each choice for this codebase, and changes files only after you approve.

Skill	What it does
ward-init	Inspects the project, asks about the preset, gates, architecture style, tools, agent integration, and Git hooks one question at a time, with a recommendation based on what it found. It then previews the exact changes with ward init --dry-run and applies the same options after you approve the plan.
ward-tune	Fits the rules of the gates you already run to the code: Checkstyle and PMD rule selection, the JaCoCo coverage threshold, PIT mutation testing, and ArchUnit architecture rules. For a large backlog of findings it plans the fixes rule by rule instead of hiding them. Every edit is grounded in findings from ward check, shown as a diff, and written only after you approve it.
ward-fix	Fixes the code so the failing gates pass. It reads the findings from ward check --format json, plans the fixes gate by gate and rule by rule with you, and re-runs the gate after each rule. It never edits ward.toml or rule files and never adds suppressions; a rule you want changed goes to ward-tune.

The skills follow the open Agent Skills format, so the same files work in Claude Code, OpenCode, Codex, Cursor, and other agents that support skills. They are distributed separately from the ward binary, so you can install them before Ward is set up in a project. ward-init checks for the CLI and offers the installer when it is missing.

Install

Claude Code

Add the repository as a plugin marketplace, then install the ward plugin:

/plugin marketplace add RicardoRB/ward-ai
/plugin install ward@ward-ai

Then ask Claude to set up Ward, for example “Set up Ward quality gates in this project”. You can also invoke the skill by name: /ward:ward-init.

Other agents

Install the skills with the cross-agent installer. It asks which agents to install them for:

npx skills add RicardoRB/ward-ai --skill ward-init ward-tune ward-fix

Requirements

Each skill declares the minimum ward version it supports. It runs ward --version before doing anything else, and stops with an upgrade offer when the CLI is older.

Skill	Minimum ward version
ward-init	0.2.0
ward-tune	0.2.0
ward-fix	0.2.0

Each skill needs a Java, TypeScript, or JavaScript project and a shell. ward-tune and ward-fix also need an existing ward.toml.

Guardrails

All skills follow the same rules, whatever the agent is asked:

• ward.toml is treated as executable code. Reading it is safe. Before running ward check on a ward.toml that existed before the session, the agent asks you to confirm the repository is trusted. See Security.
• Gates are never weakened to make a check pass. The agent does not drop gates, lower thresholds, or add suppressions (@SuppressWarnings, // NOPMD, suppression files, @ArchIgnore).
• Nothing is installed without a specific yes. That covers the Ward installer and each gate tool, such as brew install semgrep. Approving a plan is not consent to install.
• Every answer comes from you. ward-init passes each answer as an explicit init option. It never uses --yes and never pipes answers into the wizard. --overwrite, --install-tool, and --accept-compatibility-updates are asked about separately.

How ward-init applies changes

The agent’s shell is not a terminal, so ward init skips its own Proceed? [Y/n] review. The skill does that review instead:

1. It builds one command from your answers and checks each option against ward init --help.
2. It runs the command with --dry-run and shows you the plan exactly as printed.
3. After you approve, it runs the identical command without --dry-run, and compares what changed with the plan.

If the plan lists a conflict, or an installation you did not consent to, the skill does not apply it.

How ward-tune handles rule changes

Each proposal is classified before you see it:

• Strengthen: the gate accepts less code than today. Examples: adding a rule, raising a coverage minimum, adding an architecture constraint.
• Neutral: the same code is accepted. Examples: comments, ordering.
• Weaken: the gate accepts more code than today. Examples: removing or relaxing a rule, lowering a minimum, adding an exclusion. Each weakening is shown on its own with the old and new values, and needs its own approval and a reason. The reason is written as a comment next to the change.

Rule file ownership

Rule files that a preset writes start with <!-- managed-by: ward preset=<id> -->. A later ward init refreshes those files, which would undo any tuning. Before the first edit to a managed file, ward-tune asks whether the file should become yours. If you agree, it removes the marker in the same edit. From then on, ward init keeps the file and lists it as keep in its plan. If you decline, the file is not edited.

JaCoCo settings in your build file and existing ArchUnit test classes carry no marker. Init leaves them unchanged.

How ward-fix fixes findings

1. It runs the profile you want green and sorts the gates: missing tools and configuration errors are reported, not fixed in code.
2. It shows one table of the failing rules, largest first, each marked as a mechanical or a design fix, and you choose which to fix and in what order.
3. It fixes one rule at a time and re-runs the gate before moving on. Design fixes, real bugs, changed test expectations, and dependency upgrades each need your yes first.
4. Coverage and mutation gaps are closed with tests that assert behavior, and a leaked secret is moved out of the code with a reminder to rotate it.

Uninstall

• Claude Code: /plugin uninstall ward@ward-ai.
• Other agents: delete the ward-init, ward-tune, and ward-fix directories from the agent’s skills directory.

Uninstalling the skills does not change anything Ward configured in your projects.