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

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

The canonical definition of the skill resides in 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.

// 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.

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 and internal/cli/axi_respond.go.

Driving the Pipeline with no-mistakes axi

Agents initiate the pipeline using the axi run command:

# 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:

# 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. 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.
• The Markdown() function generates 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 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 is written to 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}