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

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. This file defines the skill’s name, description, and the full 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. 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, it automatically reflects any pipeline changes.

User-Level Installation

During no-mistakes init, the CLI calls skill.InstallUser() from internal/cli/init.go. This function copies 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 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), 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:

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

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

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

Inspect an active run:

no-mistakes axi status          # TOON view with awaiting_agent flag

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

Abort a runaway process:

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 and rendered to 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, as 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, the Markdown() function regenerates the content. Running make skill updates skills/no-mistakes/SKILL.md, and the CLI’s init command copies this file to user directories. Because 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 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.

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