How to Use the /no-mistakes Agent Skill: A Complete Guide

The /no-mistakes agent skill is the core LLM-driven entry point that exposes the no-mistakes pipeline through a structured command interface defined in internal/skill/skill.go.

The /no-mistakes agent skill enables LLM-based agents to orchestrate the complete no-mistakes workflow—from intent gathering to CI monitoring—via a declarative skill interface. Defined in the kunchenguid/no-mistakes repository, this skill provides the operational vocabulary that agents use to invoke the CLI's axi command family. Understanding how this skill is structured and executed allows developers to integrate automated code review and testing pipelines directly into their agent workflows.

Skill Architecture and Source of Truth

The skill definition resides in the internal/skill package, where a single source of truth governs how agents discover and interpret the /no-mistakes command.

Core Constants in skill.go

In internal/skill/skill.go, three exported constants define the skill's identity:

• skill.Name — The directory name (no-mistakes) that the agent registers. This must match the installed skill folder so the agent can discover the command as /no-mistakes.
• skill.Description — A human-readable trigger phrase describing the full pipeline (intent, rebase, review, test, doc, lint, push, PR, CI). The agent uses this to decide when to load the skill.
• skill.Markdown() — A function that generates the SKILL.md document agents read at runtime. It constructs a YAML front-matter block (name, description, user-invocable) and appends the static body constant containing the full usage guide.

The body constant contains static markdown describing the operational loop, command vocabulary, and TOON output interpretation. It is deliberately static—no runtime state is embedded—guaranteeing deterministic rendering across environments.

Generation and Distribution

The cmd/genskill tool renders the markdown returned by skill.Markdown() into the public repository location skills/no-mistakes/SKILL.md. The CI pipeline verifies that the generated file matches the source via the make skill command defined in the Makefile. This ensures the public-facing skill documentation never drifts from the implementation.

How the Agent Discovers and Loads the Skill

The skill follows a three-phase lifecycle:

1. Discovery — When an LLM-based agent starts, it scans installed skill directories. The Name and Description constants in skill.go allow the agent to recognize the skill as /no-mistakes.
2. Rendering — The Markdown() function builds the complete SKILL.md file. This document teaches the agent the operational loop: invocation modes (validate-only vs. task-first), pre-conditions (committed changes on a feature branch, daemon ready), and the step-by-step flow (run → gate → respond → outcome).
3. Execution — The skill directs the agent to invoke the no-mistakes axi family of commands implemented in cmd/no-mistakes/main.go and the internal/cli package.

Because the markdown body is static, the skill can be regenerated at any time without state concerns. The CI step make skill guarantees that skills/no-mistakes/SKILL.md matches the source in internal/skill/skill.go.

Executing the Skill: Command Reference

Once loaded, the agent uses the no-mistakes axi sub-commands to drive the pipeline. These commands are implemented in cmd/no-mistakes/main.go and parsed in internal/cli/axi_*.go, formatting output as TOON (Text-Oriented Object Notation) for machine readability.

Starting a Pipeline Run

Initiate a validation run with an explicit intent:

no-mistakes axi run --intent "Add JSON flag to the status command"

For unattended execution where the user has pre-approved actions, add the --yes flag:

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

Responding to Gates

The agent reads TOON output to find gate: objects and selects appropriate actions:

Approve a gate containing only auto-fix or no-op findings:

no-mistakes axi respond --action approve

Fix specific findings by ID with custom instructions:

no-mistakes axi respond --action fix \
    --findings r1,r3 \
    --instructions "apply the suggested changes"

Skip a gate entirely (use sparingly):

no-mistakes axi respond --action skip

Monitoring and Debugging

Inspect current run state without affecting execution:

no-mistakes axi status          # full run details

no-mistakes axi logs --step review --full   # step-specific logs

Abort an in-flight run (discards the run):

no-mistakes axi abort

Integration Points

The skill connects to several key implementation sites:

• cmd/no-mistakes/main.go — The CLI entry-point implementing the axi sub-commands (run, respond, status, etc.) that the skill references. It reads skill.Description to present consistent wording to users.
• internal/cli/axi_*.go — Parses axi sub-commands, drives the pipeline executor, and formats output as TOON for the agent to consume.
• cmd/genskill — Generation tool that ensures the public SKILL.md remains synchronized with the source constants.

Summary

• The /no-mistakes agent skill is defined in internal/skill/skill.go through constants (Name, Description) and a static body markdown string.
• skill.Markdown() generates the runtime SKILL.md document that teaches agents the operational loop and command vocabulary.
• Agents invoke no-mistakes axi run to start pipelines and no-mistakes axi respond to handle gates, with all commands implemented in cmd/no-mistakes and internal/cli.
• The make skill command in the Makefile synchronizes the generated skill documentation with source code, preventing drift between implementation and agent instructions.

Frequently Asked Questions

How does the agent know when to use the /no-mistakes skill?

The agent scans installed skill directories at startup and matches the directory name against the skill.Name constant (no-mistakes) defined in internal/skill/skill.go. It uses skill.Description to determine if the user's request matches the pipeline capabilities (intent, rebase, review, test, doc, lint, push, PR, CI). When matched, the agent loads the skill by reading the SKILL.md file generated by skill.Markdown().

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

The static body constant in skill.go defines two operational modes in the generated SKILL.md. Validate-only mode checks current changes without modifying code, while task-first mode accepts an explicit intent and executes the full pipeline including auto-fixes and PR creation. The mode is determined by how the agent structures the initial no-mistakes axi run command and whether it includes execution flags like --yes.

Where is the SKILL.md file generated and how is it kept up to date?

The cmd/genskill tool renders skill.Markdown() to skills/no-mistakes/SKILL.md. The make skill command in the Makefile invokes this generator, and CI checks ensure the generated file matches the source code. This guarantees that agents always read documentation that reflects the current implementation in internal/skill/skill.go.

Can I use the no-mistakes CLI without an LLM agent?

Yes. While the /no-mistakes skill is designed for LLM-driven automation, the underlying no-mistakes axi commands implemented in cmd/no-mistakes/main.go and internal/cli/axi_*.go are fully functional for human users. You can run no-mistakes axi run and respond to gates manually via standard input, though the TOON output format is optimized for machine parsing.

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