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

The /no-mistakes agent skill is defined in 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

The canonical skill definition lives entirely within 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 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 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 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 validates the generated Markdown, while axi_guidance_test.go ensures CLI guidance strings remain synchronized with the skill body.

Code Examples

// 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
}

# Install the skill for current user

$ no-mistakes init

# Copies rendered Markdown to:

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

// 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, 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 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 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 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 from this function, and CI tests in skill_test.go compare the generated file against the committed version. Additionally, 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.

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