How the /no-mistakes Skill Installation Works for Coding Agents

The no-mistakes skill installation writes a canonical SKILL.md into user-level agent directories (~/.claude/skills/ and ~/.agents/skills/) when you run no-mistakes init, enabling coding agents to reference the skill without vendoring files in repositories.

The kunchenguid/no-mistakes repository provides a deterministic pipeline for code quality. At the heart of its agent integration is a canonical agent skill that coding agents like Claude, OpenCode, and Copilot parse to drive the pipeline. This skill is installed at the user level through a deterministic filesystem operation implemented in Go.

What Is the /no-mistakes Skill?

The skill is a markdown document that defines behavior, constraints, and instructions for coding agents. It lives in internal/skill/skill.go as the single source of truth. This file exports two critical functions: Markdown() which returns the skill text, and InstallUser() which handles the public installation interface.

Installation Flow Overview

The installation process follows these deterministic steps:

1. Define the skill – internal/skill/skill.go declares the skill name, description, and body.
2. Identify user bases – internal/skill/install.go specifies the two home-level directories where skills reside.
3. Execute installation – InstallUser() writes SKILL.md to both locations, handling symlink edge cases.
4. Trigger from CLI – internal/cli/init.go invokes the installer during no-mistakes init.
5. Clean up legacy – Detect and flag legacy vendored copies for removal.

Core Implementation Details

Skill Definition in skill.go

The canonical skill is defined in internal/skill/skill.go. This file contains the static skill content and exports:

• Markdown(): Returns the skill text as a string.
• InstallUser(): Installs the skill into user-level directories and returns the paths written.

User-Level Installation Bases

The internal/skill/install.go file defines the target directories in the InstallBases variable:

var InstallBases = []string{
    filepath.Join(".claude", "skills"),
    filepath.Join(".agents", "skills"),
}

These paths resolve relative to the user's home directory. The installer handles scenarios where these directories are symlinked together, ensuring the skill is written correctly regardless of link direction.

The InstallUser Function

The InstallUser() function iterates over InstallBases, creates the no-mistakes subdirectory if needed, and writes SKILL.md using the output from skill.Markdown(). Key behaviors include:

• Symlink awareness: Detects when the two bases are linked and writes to both logical locations.
• Cyclic symlink detection: Returns a clear error if a cyclic symlink is discovered (verified in TestInstallCyclicSymlink).
• Path reporting: Returns a slice of paths where the skill was successfully written.

CLI Integration

The no-mistakes init command triggers the installation from internal/cli/init.go:

_, skillErr := skill.InstallUser()
if skillErr != nil {
    fmt.Fprintf(w, "  %s  %s\n", sDim.Render(" skill"), sYellow.Render("skipped: "+skillErr.Error()))
} else {
    fmt.Fprintf(w, "  %s  %s %s\n", sDim.Render(" skill"), sGreen.Render("/no-mistakes"), sDim.Render("installed for agents at user level"))
}

This provides immediate visual feedback about the installation status in the terminal output.

Handling Legacy Vendored Copies

After installing the user-level skill, the CLI checks for legacy vendored copies using skill.Vendored(repo.WorkingPath). If found, it prints a note suggesting the file be removed. This ensures repositories remain free of skill files while maintaining functionality through the user-level installation.

Verification and Testing

The end-to-end test in internal/e2e/axi_journey_test.go validates the complete flow by running no-mistakes init in an isolated repo and asserting that both user-level paths contain SKILL.md. Unit tests in internal/skill/skill_test.go cover symlink handling, cyclic detection, and legacy path scenarios.

Programmatic Usage

You can install the skill directly without the CLI:

import "github.com/kunchenguid/no-mistakes/internal/skill"

func main() {
    paths, err := skill.InstallUser()
    if err != nil {
        log.Fatalf("skill install failed: %v", err)
    }
    fmt.Printf("installed skill to:\n")
    for _, p := range paths {
        fmt.Println("  -", p)
    }
}

Summary

• The no-mistakes skill installation is a pure filesystem operation that writes SKILL.md to ~/.claude/skills/no-mistakes/ and ~/.agents/skills/no-mistakes/.
• The InstallUser() function in internal/skill/install.go handles dual-directory installation and symlink edge cases.
• Cyclic symlinks are detected and reported as errors to prevent installation failures.
• The no-mistakes init command automates this process and suggests cleanup of legacy vendored copies.
• All functionality is verified through unit tests and end-to-end tests in the repository.

Frequently Asked Questions

Where does the no-mistakes skill get installed?

The skill is installed into two user-level directories: ~/.claude/skills/no-mistakes/ and ~/.agents/skills/no-mistakes/. Both locations receive an identical SKILL.md file containing the canonical agent instructions.

What happens if the skills directories are symlinked together?

The InstallUser() function detects symlinks between the two base directories and correctly handles any link direction. It ensures the skill file exists in both logical locations without causing duplicate writes or errors, unless a cyclic symlink is detected, which returns an explicit error.

Can I install the skill programmatically without using the CLI?

Yes, you can call skill.InstallUser() directly from the internal/skill package. This function returns the list of paths where the skill was written and any error encountered during the filesystem operations.

How do I migrate from a vendored skill copy to the user-level installation?

Run no-mistakes init to install the skill at the user level. The CLI will detect any existing vendored copy in your repository using skill.Vendored() and print a message indicating it can be safely removed, as the agents will now read from the user-level installation instead.

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