Skip to main content

​
What it does

The skill files integration creates a .claude/skills/gitwhy/ directory in your repository with three markdown files that coding agents discover and use as guidance: Agents that support skill discovery (Claude Code, Cursor, and others) automatically load these files when relevant. The files tell the agent the GitWhy format without requiring prompt injection on every turn.

​
Setup

Run git why setup and select Skill Files from the menu. This creates:

​
What the files contain

​
SKILL.md

The quick reference. Contains:
  • The full context format template (all sections with descriptions)
  • The git why save and gitwhy_save commands
  • Required vs optional sections
  • Context ID format

​
WORKFLOWS.md

Step-by-step patterns for common workflows:
  • When to suggest saving context (after meaningful work, before context window fills)
  • How to fill each section (what belongs in Reasoning vs Key Decisions, etc.)
  • The retrieve workflow (when a developer asks “what did we decide about X”)
  • The push workflow (before opening a PR)

​
TROUBLESHOOTING.md

Resolutions for:
  • Validation errors (missing required sections)
  • Domain/topic assignment issues
  • MCP connection problems

​
Standalone installation via skills.sh

You can install GitWhy skill files without the full CLI using the skills.sh ecosystem:
This installs the skill files into .claude/skills/gitwhy/ without requiring the GitWhy CLI. Useful for teams that want format guidance while evaluating the full tool.

​
Agent compatibility

All modern coding agents support the Agent Skills standard and automatically discover skill files: Selecting Skill Files in git why setup detects your agent and creates the skill files in the correct directory.

​
See also

  • MCP server — pair with skill files for tool access
  • Rules — alternative for agents without skill discovery