# Understanding the /no-mistakes Agent Skill: Structure and Usage

> Discover the structure and usage of the /no-mistakes agent skill. Learn how agents execute deterministic Markdown files via YAML front-matter and a canonical body for operating loops and command vocabulary.

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

---

**The /no-mistakes agent skill is defined in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go) as a deterministic, programmatically generated Markdown file that agents discover via YAML front-matter and execute through a canonical body containing the operating loop and command vocabulary.**

The `kunchenguid/no-mistakes` repository implements a structured agent skill system that enables AI agents to execute commands through a well-defined interface. The `/no-mistakes` skill serves as the primary entry point for agent interactions, providing a minimal schema that ensures consistent behavior across different agent runtimes. Understanding this structure is essential for developers integrating with or extending the no-mistakes ecosystem.

## Core Skill Architecture in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go)

The canonical skill definition lives entirely within [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go) and follows an immutable schema designed for programmatic discovery and deterministic rendering.

### Skill Identity Constants

The skill declares its identity through three constants that form the contract between the tool and agent runtimes:

- **`Name`**: Defined as `"no-mistakes"` at line 15, this constant serves as both the directory identifier and the front-matter key that agents match against the `/no-mistakes` command.
- **`Description`**: Located at lines 17-20, this constant supplies the trigger description containing keywords that agents use for intent-matching logic.
- **`body`**: The unexported string constant at lines 42-78 houses the complete Markdown documentation, including the operating loop, command vocabulary, and TOON output interpretation rules.

### The `Markdown()` Rendering Function

The `func Markdown() string` function at lines 31-40 constructs the deterministic output by concatenating a YAML front-matter block (`name`, `description`, `user-invocable`) with the canonical `body`. This rendering acts as the **single source of truth** for both the public skill definition at [`skills/no-mistakes/SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/skills/no-mistakes/SKILL.md) and the user-installed copy.

## How Agents Discover and Utilize the Skill

Agents consume the skill through a four-stage pipeline that ensures consistency between the public definition and runtime execution.

### Discovery Phase

Agent runtimes scan user-level skill directories (typically `~/.no-mistakes/skills/`) for [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) files. The YAML front-matter `name: no-mistakes` establishes the mapping to the `/no-mistakes` command, while the `description` field feeds the agent's intent-matching algorithm to decide whether to activate the skill.

### Loading and Execution

Upon invocation, agents read the rendered [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) file from the user's skill directory. The body section contains the exact instruction set passed to the language model, which then drives the `no-mistakes axi` CLI based on generated output. All runtime decisions—including which `axi run` flags to append—derive directly from this canonical text, preventing configuration drift.

## Installation and Skill Regeneration

The `no-mistakes init` command installs the skill by copying the rendered Markdown to `$HOME/.no-mistakes/skills/no-mistakes/SKILL.md`. Developers regenerate the public skill file using the `genskill` tool via `make skill`, which re-runs `skill.Markdown()` and updates the committed version. The test suite in [`skill_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/skill_test.go) validates the generated Markdown, while [`axi_guidance_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/axi_guidance_test.go) ensures CLI guidance strings remain synchronized with the skill body.

## Code Examples

```go
// Programmatically obtain the full SKILL.md text
import "github.com/kunchenguid/no-mistakes/internal/skill"

func main() {
    md := skill.Markdown()
    fmt.Println(md) // prints YAML front-matter + body
}

```

```bash

# Install the skill for current user

$ no-mistakes init

# Copies rendered Markdown to:

# $HOME/.no-mistakes/skills/no-mistakes/SKILL.md

```

```go
// Agent-side skill loading pseudo-code
func loadSkill(dir string) (*Skill, error) {
    fm, body, err := parseSkillFile(filepath.Join(dir, "SKILL.md"))
    if err != nil || fm.Name != skill.Name {
        return nil, fmt.Errorf("skill mismatch")
    }
    return &Skill{Description: fm.Description, Body: body}, nil
}

```

## Summary

- The `/no-mistakes` skill is defined as code in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go), not as static documentation.
- Three constants (`Name`, `Description`, `body`) provide the immutable skill contract.
- The `Markdown()` function generates deterministic output combining YAML front-matter with the canonical body.
- Agents discover skills via `~/.no-mistakes/skills/` directory scanning and YAML front-matter parsing.
- The `genskill` tool and `make skill` target ensure the public [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) stays synchronized with source code.
- CI tests prevent drift between the programmatic definition and the installed skill copy.

## Frequently Asked Questions

### Where is the /no-mistakes agent skill defined?

The skill is defined in [`internal/skill/skill.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/skill/skill.go) within the `kunchenguid/no-mistakes` repository. This file contains the `Name`, `Description`, and `body` constants, along with the `Markdown()` renderer that produces the final skill file consumed by agents.

### How does an agent know when to trigger the /no-mistakes skill?

Agents use the `description` field from the YAML front-matter to match user intent. When scanning the skill directory, the runtime reads the front-matter from [`SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/SKILL.md) and uses the description keywords to determine if the current request should invoke the `/no-mistakes` command.

### What prevents the installed skill from drifting out of sync with the source code?

The `skill.Markdown()` function serves as the single source of truth. The `genskill` tool regenerates [`skills/no-mistakes/SKILL.md`](https://github.com/kunchenguid/no-mistakes/blob/main/skills/no-mistakes/SKILL.md) from this function, and CI tests in [`skill_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/skill_test.go) compare the generated file against the committed version. Additionally, [`axi_guidance_test.go`](https://github.com/kunchenguid/no-mistakes/blob/main/axi_guidance_test.go) ensures CLI guidance strings remain synchronized with the skill body.

### How do I install the /no-mistakes skill for my agent?

Run the `no-mistakes init` command, which copies the rendered Markdown output to `$HOME/.no-mistakes/skills/no-mistakes/SKILL.md`. This places the deterministic skill definition in the standard location where agent runtimes perform discovery.