# How the /no-mistakes Agent Skill Works and What It Can Drive

> Discover how the /no-mistakes agent skill uses a three-layer architecture to validate and drive CI workflows. Learn to leverage the no-mistakes axi command family for seamless integration.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: how-to-guide
- Published: 2026-06-27

---

**The /no-mistakes skill is a static markdown specification that bridges LLM agents to the no-mistakes pipeline through a three-layer architecture, driving validation and CI workflows via the `no-mistakes axi` command family.**

The `no-mistakes` agent skill in the `kunchenguid/no-mistakes` repository provides LLM agents with a deterministic protocol to validate code changes and drive CI pipelines. Unlike traditional integrations that rely on live APIs, this skill operates as a **static, self-contained specification** that instructs agents on invoking the `no-mistakes axi` CLI commands to run, monitor, and respond to pipeline gates.

## Three-Layer Architecture

The skill implementation guarantees immutability and synchronization with the CLI through a strict three-layer model defined in the source code.

### Canonical Source Definition

The single source of truth resides in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go). This file defines the skill’s **name**, **description**, and the full [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) body content. The `Markdown()` function constructs a deterministic document containing YAML front-matter and the instruction body. This ensures that both the public skill and user installations derive from identical content, preventing configuration drift.

### Public Skill Rendering

The `genskill` tool, invoked via `make skill`, writes the canonical markdown to [`skills/no-mistakes/SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/skills/no-mistakes/SKILL.md). Discovery tools like `npx skills add kunchenguid/no-mistakes` read this generated file to understand the skill’s capabilities and trigger phrases. Because the file is generated from [`skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/skill.go), it automatically reflects any pipeline changes.

### User-Level Installation

During `no-mistakes init`, the CLI calls `skill.InstallUser()` from [`internal/cli/init.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/init.go). This function copies [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) into the standard agent skill directories under the user’s home folder: `~/.claude/skills` and `~/.agents/skills`. The implementation in [`internal/skill/install.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/install.go) handles file copying and symlinks, ensuring the agent always loads the current version.

## What the Skill Can Drive

The skill drives the no-mistakes pipeline exclusively through the **`no-mistakes axi`** command family. These commands output **machine-readable TOON on stdout** and human-friendly progress on stderr, allowing agents to parse pipeline state programmatically.

### Pipeline Control Commands

The skill instructs agents to use the following CLI commands:

1. **`no-mistakes axi run --intent "<user goal>" [--skip=step …] [--yes]`** – Launches a run on a feature branch, validates committed changes, and blocks until the first gate or final outcome.
2. **`no-mistakes axi status`** – Returns the current run’s TOON object, including branch name, findings, and the `awaiting_agent` flag.
3. **`no-mistakes axi respond --action approve|fix|skip [--findings id,…] [--instructions "..."]`** – Answers a gate. Use `approve` to accept, `fix` to apply auto-fixes, or `skip` to bypass the step.
4. **`no-mistakes axi abort`** – Cancels the current branch’s run. Use `--run <id>` to abort a specific run from any directory.
5. **`no-mistakes axi logs --step <step> --full`** – Retrieves raw logs for a specific pipeline step.
6. **`no-mistakes axi`** – Displays the home view summarizing the current branch, active runs, and next actions.

### Gate Protocol and Actions

As documented in the skill markdown (lines 45-80 in [`skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/skill.go)), the pipeline exposes gates such as **review**, **test**, **lint**, and **CI**. The skill defines three response actions:

- **`auto-fix`** – Apply automated corrections immediately.
- **`no-op`** – Acknowledge without changes.
- **`ask-user`** – Request human confirmation.

The **`--yes`** flag provides stand-alone consent, allowing the agent to automatically approve `ask-user` gates and apply `auto-fix` findings without pausing for confirmation.

## Agent Invocation Modes

The skill supports two distinct invocation patterns based on the agent’s context.

### Validate-Only Mode

When an agent sees the trigger `/no-mistakes` without additional task context, it enters validate-only mode. The agent may pass optional flag-style requests (e.g., "skip lint") to the `axi run` command to bypass specific pipeline steps.

### Task-First Mode

When invoked as `/no-mistakes <task>`, the agent first performs the specified task, commits the changes on a feature branch, then executes the pipeline with `--intent "<task>"`. This mode integrates development work with immediate validation.

## Practical Examples

Drive a simple validation run:

```bash

# Agent sees "/no-mistakes"

no-mistakes axi run --intent "add a --json flag to the status command"

# Run blocks; returns gate: review with findings

no-mistakes axi respond --action approve

# Or apply fixes: no-mistakes axi respond --action fix --findings r1

```

Drive a full pipeline with automatic consent:

```bash
no-mistakes axi run --intent "refactor logger" --yes

# --yes auto-fixes findings and approves ask-user gates

```

Inspect an active run:

```bash
no-mistakes axi status          # TOON view with awaiting_agent flag

no-mistakes axi logs --step test --full

```

Abort a runaway process:

```bash
no-mistakes axi abort           # Cancel current branch run

no-mistakes axi abort --run 42  # Cancel specific run ID

```

## Summary

- The **no-mistakes agent skill** is defined in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go) and rendered to [`skills/no-mistakes/SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/skills/no-mistakes/SKILL.md) via the `genskill` tool.
- It installs to `~/.claude/skills` and `~/.agents/skills` during `no-mistakes init` through `skill.InstallUser()`.
- The skill drives the **`no-mistakes axi`** command family to start runs, check status, respond to gates, and fetch logs.
- It supports **validate-only** and **task-first** invocation modes with optional `--yes` auto-consent.
- All pipeline changes require updating only [`skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/skill.go), as [`internal/cli/axi.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi.go) uses `skill.Description` for help text and the markdown stays synchronized automatically.

## Frequently Asked Questions

### How does the /no-mistakes skill stay synchronized with CLI updates?

The skill uses a canonical source pattern. When developers modify [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go), the `Markdown()` function regenerates the content. Running `make skill` updates [`skills/no-mistakes/SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/skills/no-mistakes/SKILL.md), and the CLI’s `init` command copies this file to user directories. Because [`internal/cli/axi.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi.go) references `skill.Description` for help output, the entire system remains synchronized through a single source file.

### What directories does the skill install to during initialization?

The `skill.InstallUser()` function in [`internal/skill/install.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/install.go) copies the skill to two standard locations: `~/.claude/skills` for Claude Desktop agents and `~/.agents/skills` for other compatible agent frameworks. This ensures broad compatibility across different LLM agent implementations.

### How does an agent handle gates that require user approval?

The skill defines an `ask-user` action type for gates requiring human confirmation. When the `--yes` flag is passed to `no-mistakes axi run`, the agent receives stand-alone consent to automatically approve these gates. Without the flag, the agent uses `no-mistakes axi status` to detect `awaiting_agent` states and pauses for user input before calling `no-mistakes axi respond --action approve`.

### What is the difference between validate-only and task-first invocation?

**Validate-only** mode triggers when the agent sees `/no-mistakes` alone, causing it to run the pipeline against existing commits with optional skip flags. **Task-first** mode triggers with `/no-mistakes <task>`, where the agent performs the task, commits to a feature branch, then runs the pipeline with `--intent "<task>"` to validate the new changes.