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

Run no-mistakes init to install the /no-mistakes agent skill into your user-level skill directories (~/.claude/skills/ and ~/.agents/skills/), enabling coding agents like Claude Code, Codex, and OpenCode to discover and invoke the quality gate pipeline.

The /no-mistakes agent skill in the kunchenguid/no-mistakes repository provides the primary interface between coding agents and the no-mistakes validation pipeline. Installing this skill allows agents to automatically validate commits or execute tasks through the quality gate system without polluting your repository with configuration files.

Understanding the /no-mistakes Skill Implementation

The canonical implementation lives in internal/skill/skill.go, which serves as the single source of truth for the skill's name, description, and Markdown body. This file defines the Description field (lines 13-20) that agents use for discovery via front-matter, and the Markdown() method that generates the full skill instructions.

Key implementation details you should know:

• Skill name: /no-mistakes (the slash command agents type)
• Description: Embedded in YAML front-matter for agent discovery
• Body: Markdown instructions that teach agents how to translate user intents into no-mistakes axi flags

Installing the /no-mistakes Agent Skill

Step 1: Initialize the Installation

Run the initialization command from any repository where you want to use the skill:

no-mistakes init

This command, implemented in internal/cli/init.go, performs a best-effort installation that follows existing symlinks between .claude and .agents directories. This ensures the skill is visible to all supported agents without requiring manual configuration.

Step 2: Verify Installation Locations

The no-mistakes init command generates the skill's SKILL.md from skill.Markdown() and copies it to:

• ~/.claude/skills/no-mistakes/
• ~/.agents/skills/no-mistakes/

No skill files are written into the repository itself; the installation is purely user-level. This design prevents repository contamination while making the skill globally available to agents.

How Agents Use the /no-mistakes Skill

Once installed, agents can invoke the skill in two modes, both driving the non-interactive no-mistakes axi command surface that prints TOON output to stdout and progress messages to stderr.

Validate-Only Mode (Bare)

Invoke the skill without arguments to validate already-committed changes on a feature branch:

/no-mistakes

This mode is useful when you want the agent to check existing work without performing new tasks.

Task-First Mode

Pass a task description to have the agent perform work, commit it automatically (creating a feature branch if you're on the default branch), and run the pipeline:

/no-mistakes add a --json flag to the status command

According to internal/skill/skill.go (lines 58-78), this mode translates the task text into the --intent flag for no-mistakes axi run. The agent reads the skill's Markdown body to know how to invoke axi respond --action fix when gates fail.

Direct CLI Usage Without Agents

For non-agent use or CI pipelines, invoke the pipeline directly without installing the skill:

# Run with specific intent

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

# Full automation mode (skips confirmations)

no-mistakes axi run --intent "Add JSON flag" --yes

Generating Skill Documentation for Development

For CI pipelines or testing purposes, the repository includes cmd/genskill/main.go, a CLI tool that renders skill.Markdown() to skills/no-mistakes/SKILL.md. This is useful for verifying skill syntax or generating documentation artifacts without performing a user-level install.

Summary

• The /no-mistakes agent skill is defined in internal/skill/skill.go and serves as the bridge between coding agents and the validation pipeline.
• Install via no-mistakes init, which copies SKILL.md to ~/.claude/skills/ and ~/.agents/skills/ following any existing symlinks between these directories.
• Agents invoke the skill in two modes: bare (validate-only) or task-first, both ultimately calling no-mistakes axi with appropriate flags.
• The installation is user-level and repository-agnostic, keeping your projects clean while enabling global agent access to the quality gate.

Frequently Asked Questions

Where is the /no-mistakes skill installed?

The skill installs to user-level directories at ~/.claude/skills/no-mistakes/ and ~/.agents/skills/no-mistakes/. According to the source code in internal/cli/init.go, the installation follows existing symlinks between .claude and .agents directories to ensure the skill is visible to all supported agents without duplicating files across locations.

What coding agents support the /no-mistakes skill?

The skill is compatible with Claude Code, Codex, OpenCode, Rovo Dev, Pi, and other agents that follow the standard skill directory convention. The skill's Description field in internal/skill/skill.go (lines 13-20) generates front-matter that agents parse for discovery, making it visible in supported environments.

Can I use no-mistakes without installing the agent skill?

Yes. The skill is merely a convenience wrapper around the no-mistakes axi command surface. You can run the pipeline directly from the terminal using commands like no-mistakes axi run --intent "your task" --yes. The skill installation only enables natural language invocation through agents and automatic branch management.

How do I update the skill after installation?

Run no-mistakes init again after updating the CLI tool. This regenerates the SKILL.md from skill.Markdown() in internal/skill/skill.go and overwrites the files in your skill directories with the latest version. Since the install is user-level and not repository-specific, you only need to update once per machine to affect all repositories.

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