# Understanding the Agent-Native /no-mistakes Skill: A Built-in AI Agent Interface

> Explore the agent-native /no-mistakes skill a built-in AI agent interface. Drive validation pipelines via CLI commands without external dependencies.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: deep-dive
- Published: 2026-06-28

---

**The agent-native /no-mistakes skill is a built-in, self-contained instruction set that enables AI agents to drive the full no-mistakes validation pipeline through CLI commands without external dependencies.**

The `kunchenguid/no-mistakes` repository ships with an **agent-native /no-mistakes skill** that embeds directly into the CLI binary. This feature provides AI agents with a deterministic, version-controlled instruction set for executing the complete validation pipeline, eliminating the need for hand-edited configuration files or external scripts.

## What Is the Agent-Native /no-mistakes Skill?

The **agent-native /no-mistakes skill** is a hard-coded capability within the `no-mistakes` tool designed specifically for AI agents such as Claude, Codex, Rovo Dev, and Open-Code. Unlike traditional external skill definitions, this capability lives entirely inside the binary, ensuring perfect synchronization between the tool's behavior and the agent's instructions.

The skill provides a single source of truth for how agents should invoke the `no-mistakes` pipeline. It defines the trigger command (`/no-mistakes`), the expected workflow, and the exact CLI commands agents must use to drive the validation process from intent through CI.

## Skill Definition in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go)

The canonical definition of the skill resides in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go). This file contains the constants and functions that generate the skill documentation, ensuring the binary and the skill file never drift.

### The `Markdown()` Function

The `Markdown()` function generates the complete skill document programmatically. This approach guarantees that any change to the skill logic in the source code automatically propagates to the generated documentation.

```go
// internal/skill/skill.go
func Markdown() string {
    var b strings.Builder
    b.WriteString("---\n")
    b.WriteString("name: " + Name + "\n")
    b.WriteString("description: " + Description + "\n")
    b.WriteString("user-invocable: true\n")
    b.WriteString("---\n")
    b.WriteString(body)
    return b.String()
}

```

When the `genskill` generator runs (via `make skill`), it calls `Markdown()` to produce [`skills/no-mistakes/SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/skills/no-mistakes/SKILL.md).

### Skill Constants and Discovery

Three key constants define the skill's identity:

- **`Name`** (line 15): Set to `"no-mistakes"`, this becomes the directory name under the agent's skill home and the slash command trigger `/no-mistakes`.
- **`Description`** (lines 17-20): Provides the front-matter that agent discovery logic reads to determine when to load the skill.
- **`body`** (starting at line 45): Contains the complete instruction set that agents receive upon activation.

## Skill Body and Agent Instructions

The `body` constant contains the complete protocol for driving the `no-mistakes` pipeline. It explains that `no-mistakes` acts as a local gate running a full pipeline: intent, rebase, review, test, lint, push, PR, and CI.

### Validation-Only vs Task-First Modes

The skill defines two distinct invocation modes (lines 58-73):

1. **Validate-only**: The agent runs the pipeline to verify existing work without creating new tasks.
2. **Task-first**: The agent initiates a new task, commits changes, and then drives the pipeline from the beginning.

Both modes require pre-conditions: committed work on a feature branch and an initialized repository.

### The Interactive Gate Protocol

The skill body details how agents handle interactive gates. When the pipeline pauses, the CLI emits machine-readable **TOON** objects to `stdout` and human-readable progress to `stderr`. The agent must parse these TOON outputs to determine outcomes like `checks-passed`, `passed`, or `failed`, then respond using the appropriate `axi` command.

## Runtime Integration with CLI Commands

The skill directs agents to use the `no-mistakes axi` command family, implemented in `internal/cli/axi*.go` files such as [`internal/cli/axi_run.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_run.go) and [`internal/cli/axi_respond.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/axi_respond.go).

### Driving the Pipeline with `no-mistakes axi`

Agents initiate the pipeline using the `axi run` command:

```sh

# Step 1: Create a feature branch and commit changes

git checkout -b feat/add-json-flag
git add .
git commit -m "Add --json flag to status command"

# Step 2: Drive the pipeline with intent

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

```

### Responding to Gates via TOON Output

When the run pauses at a gate, the agent parses TOON output and responds using `axi respond`:

```sh

# Example: Auto-fixable lint findings appear

no-mistakes axi respond --action fix --findings 12,15 \
    --instructions "apply the suggested lint fixes"

```

The pipeline then re-runs the affected step and proceeds to the next gate or final outcome.

## Generation and Distribution

The `genskill` tool consumes the `Markdown()` function to generate [`skills/no-mistakes/SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/skills/no-mistakes/SKILL.md). Running `no-mistakes init` copies this file to `~/.no-mistakes/agent/skills/no-mistakes`, ensuring the local agent sees the exact same skill definition as the repository.

This generation process ensures that the **agent-native /no-mistakes skill** remains version-controlled and deterministic. Because the body is generated from code rather than hand-edited, the skill never drifts between the binary, the repository-level skill file, and the user-level copy.

## Summary

- The **agent-native /no-mistakes skill** is a built-in instruction set defined in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go).
- The `Markdown()` function generates [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) deterministically, preventing drift between source and documentation.
- Agents trigger the skill via `/no-mistakes` and drive the pipeline using `no-mistakes axi` commands.
- The skill supports two invocation modes: validate-only and task-first.
- Interactive gates use TOON objects for machine-readable communication between the CLI and the agent.
- Distribution occurs through `genskill` generation and `no-mistakes init` installation.

## Frequently Asked Questions

### How does the agent-native /no-mistakes skill differ from external skill definitions?

Unlike external skills that require hand-edited markdown files or external scripts, the agent-native /no-mistakes skill lives entirely within the binary. The `Markdown()` function in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go) generates the skill documentation programmatically, ensuring the agent always receives instructions that match the exact version of the CLI binary.

### What CLI commands does the skill use to control the pipeline?

The skill directs agents to use the `no-mistakes axi` command family defined in `internal/cli/axi*.go`. Primary commands include `no-mistakes axi run` to initiate the pipeline and `no-mistakes axi respond` to handle interactive gates, with both emitting TOON objects for machine-readable parsing.

### Where is the skill file installed for agents to discover?

The generated [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) is written to [`skills/no-mistakes/SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/skills/no-mistakes/SKILL.md) in the repository and copied to `~/.no-mistakes/agent/skills/no-mistakes` when users run `no-mistakes init`. This ensures agents discover the skill through the standard slash command `/no-mistakes` with consistent documentation across all environments.

### Can agents use the skill without installing external dependencies?

Yes. Because the skill is agent-native and embedded in the binary, agents only need the `no-mistakes` CLI installed. The skill body contains all necessary instructions for driving the pipeline, and the `axi` commands handle the complete validation workflow without requiring additional tools or configuration files.