Skills
Auto-activating workflows that respond to natural language, providing intuitive access to complex development processes through semantic matching.
Definition
Skills are auto-activating workflows that live in .claude/skills/ directories. Unlike slash commands which require explicit invocation, Skills activate automatically when Claude detects semantic matches between user input and skill descriptions.
Each Skill is a self-contained directory containing a SKILL.md file with frontmatter metadata and detailed instructions. Skills may also include supporting files like checklists, templates, and helper documentation.
Philosophy
Core Principle
Skills embody the principle of progressive disclosure. Rather than overwhelming Claude's context with hundreds of lines of instructions, Skills keep the main CLAUDE.md lean while providing deep, specialized workflows on demand.
The farming metaphor extends naturally to Skills: they're like specialized tools in a well-organized barn. You don't carry every tool to every task - you reach for the right one when needed. Skills activate contextually, bringing their full capabilities to bear only when relevant.
Why Skills Over Inline Instructions
- Reduces context window consumption - instructions load only when needed
- Prevents instruction drift during long conversations
- Enables version control of individual workflows
- Allows parallel development of different workflow improvements
- Makes complex workflows maintainable and testable
Structure
A Skill directory follows a consistent structure that Claude Code recognizes and processes:
.claude/skills/[skill-name]/
├── SKILL.md # Required: Main workflow definition
├── checklist.md # Optional: Step-by-step checklist
└── [helpers].md # Optional: Supporting documentationSKILL.md Format
The SKILL.md file uses YAML frontmatter to define metadata, followed by markdown content containing the workflow instructions:
---
name: farm-audit
description: Audit all Farmwork systems and update FARMHOUSE.md
metrics. Use when user says "open the farm", "audit systems",
"check farm status", or asks about project health.
---
# Farm Audit Skill
## Purpose
Run a comprehensive audit of all Farmwork systems...
## Workflow
1. Read FARMHOUSE.md to understand current state
2. Run parallel audit agents...
...Activation Mechanism
Skills activate through semantic matching against their description field. Claude analyzes user input and determines if any skill descriptions are contextually relevant. This is not keyword matching - Claude understands intent.
Activation Hook
Farmwork configures a UserPromptSubmit hook that reminds Claude to check for applicable skills on every message. This ensures reliable activation without context drift over long conversations.
Multiple Triggers
A single skill can respond to multiple phrases. The description field should include all semantic variations that should trigger the skill:
- "open the farm" / "audit systems" / "check farm status"
- "I have an idea for" / "plant this idea" / "add to garden"
- "let's research" / "investigate" / "look into"
Built-in Skills
Farmwork installs six core Skills during initialization:
| Skill | Trigger Phrases | Purpose |
|---|---|---|
farm-audit |
"open the farm" | Audit all systems, update FARMHOUSE.md |
farm-inspect |
"count the herd" | Full code inspection, dry run quality gates |
garden |
"I have an idea", "water the garden" | Manage ideas in GARDEN.md |
research |
"let's research..." | Systematic research documentation |
production |
"go to production" | Production readiness checks |
market |
"go to market" | i18n and accessibility audits |
Creating Custom Skills
You can create custom Skills for your project's specific workflows. A well-designed Skill should:
- Have a clear, focused purpose (single responsibility)
- Include comprehensive trigger phrases in the description
- Provide step-by-step instructions Claude can follow
- Reference any supporting files or agents needed
- Define expected outputs and success criteria
Best Practice
Keep Skills focused. If a workflow requires multiple distinct phases, consider splitting it into separate Skills that can be composed together rather than one monolithic workflow.