Skill Files

Understanding the structure and usage of skill files.

Location

Skill files are stored in .claude/skills/, each in its own subdirectory: 

.claude/skills/
  commit/SKILL.md
  code-review/SKILL.md
  pattern-discovery/SKILL.md
  chunk-breakdown/SKILL.md

SKILL.md Structure

Each skill file starts with YAML frontmatter followed by markdown instructions: 

---
name: my-skill
description: What this skill does and when to use it
---

# Skill Name

Detailed instructions for the skill...

Fields

  • name - Identifier used for installation and discovery (defaults to the directory name).
  • description - Short summary of what the skill does and when to use it.
  • disable-model-invocation - Optional. Set to true so only the user can invoke it (no automatic triggering).
  • user-invocable - Optional. Set to false to hide it from the / menu (Claude-invoked only).

Invocation Modes

By default a skill is both user- and model-invocable. Two optional frontmatter fields narrow that, giving three effective modes:

Mode Frontmatter Description
User + Automatic (default — no field) Invokable via slash command and auto-invoked by Claude when relevant
User only disable-model-invocation: true Slash command only; Claude will not trigger it (e.g. all /hypr:* workflows)
Automatic only user-invocable: false Claude-invoked and hidden from the / menu (e.g. pattern-discovery, chunk-breakdown)

Skills vs Agents

Skills and agents serve different purposes:

Skills

Self-contained workflows and processes. They describe how to perform a specific task — like making commits or reviewing code. Think of them as runbooks.

Agents

Specialized roles with their own system prompt and tool access. They define who performs work — like a frontend executor or accessibility analyzer. They often use skills as part of their workflow.

Installing Skills

Install skills from the official directory, GitHub, or local paths:

/hypr:list skills # Browse available skills /hypr:add commit # Install from directory /hypr:add mycompany/custom-skill # Install from GitHub /hypr:add ~/local/my-skill # Install from local path

Built-in Skills

Hypr includes four built-in skills that are automatically used by the core agents:

  • pattern-discovery - Discovers implementation patterns by analyzing similar files
  • rule-extraction - Converts discovered patterns into actionable rules
  • chunk-breakdown - Breaks features into small, implementable chunks
  • pattern-validation - Validates code against established project patterns

Writing Custom Skills

A good skill file includes:

  • When it activates - Clear trigger conditions
  • Step-by-step process - Numbered steps the skill follows
  • Output format - What the result looks like
  • Quality checks - How to verify the output
  • Examples - Concrete examples of inputs and outputs