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

> Understand how the no-mistakes skill installation effortlessly integrates with coding agents. Learn how it enables skill referencing without vendoring files, streamlining your development workflow.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: internals
- Published: 2026-07-01

---

**The no-mistakes skill installation writes a canonical [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go) declares the skill name, description, and body.
2. **Identify user bases** – [`internal/skill/install.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/install.go) specifies the two home-level directories where skills reside.
3. **Execute installation** – `InstallUser()` writes [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) to both locations, handling symlink edge cases.
4. **Trigger from CLI** – [`internal/cli/init.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/install.go) file defines the target directories in the `InstallBases` variable:

```go
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/init.go):

```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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md). Unit tests in [`internal/skill/skill_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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:

```go
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`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) to `~/.claude/skills/no-mistakes/` and `~/.agents/skills/no-mistakes/`.
- The `InstallUser()` function in [`internal/skill/install.go`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.