# Lean SKILL.md Pattern

Skills teach agents specialised capabilities. Each skill is a directory containing a `SKILL.md` file and optional `references/` subdirectory.

## Directory Structure

```
skills/
  my-skill/
    SKILL.md              <- Main file (lean index)
    references/
      detailed-guide.md   <- Loaded on demand
      templates.md
```

## SKILL.md Template

```markdown
---
name: my-skill
description: "One-line summary of what this skill does — used for agent routing."
---

# My Skill

Applies when [activation conditions].

## When to Activate

- [Trigger condition 1]
- [Trigger condition 2]

## Behaviour

[Concise rules — keep this section short. Move detailed procedures to references.]

## References

Load `references/detailed-guide.md` for [what it covers].
Load `references/templates.md` for [what it covers].
```

## Principles

1. **SKILL.md is an index, not a manual.** Keep it under 30 lines of instructions. The agent reads it on every activation — bloated skills waste context.

2. **References hold the detail.** Procedures, templates, data formats, and examples go in `references/`. The agent loads them on demand.

3. **Frontmatter is required.** Every SKILL.md must start with YAML frontmatter containing `name` and `description`. Missing `description` causes the skill to be silently skipped.

4. **Description drives routing.** The description is injected into the agent's prompt as part of the available skills list. Make it specific enough that the agent activates the skill for the right messages.

5. **Behaviour, not data.** Skills define how the agent should act. Business-specific data (pricing, customer info, hours) belongs in memory, not in the skill file. Skills are generic; memory is specific.

## Available Icon Names

These are [Lucide](https://lucide.dev) icon names. Choose one that reflects the skill's purpose:

`Zap` · `Globe` · `BookOpen` · `Calendar` · `Camera` · `Clock` · `Cloud` · `Code` · `Database` · `FileText` · `Headphones` · `Heart` · `Home` · `Image` · `Mail` · `Map` · `MessageSquare` · `Music` · `Phone` · `Puzzle` · `Search` · `Settings` · `ShoppingCart` · `Star` · `Tag` · `Truck` · `User` · `Wallet` · `Wrench` · `Cpu`

Any valid Lucide icon name works — this list is a starting point, not a constraint.

## Examples

### Simple skill (no references)

```markdown
---
name: weather
description: "Provide weather context for scheduling and outdoor work decisions."
---

# Weather

When scheduling or planning outdoor work, check weather conditions.

## When to Activate

- Customer asks about weather
- Scheduling outdoor appointments
- Weather might affect planned work

## Behaviour

Use the `web_search` tool to check current weather for the business location.
Keep weather info brief — one or two sentences unless asked for detail.
```

### Lean skill with references

```markdown
---
name: event-management
description: "Manage anything time-bound: appointments, meetings, reminders, follow-ups."
---

# Event Management

Applies when handling anything time-bound.

## When to Activate

- Customer requests or confirms an appointment
- Business owner asks to schedule, reschedule, or cancel something
- A reminder or follow-up needs to be recorded

## References

Load `references/events.md` for the standard event template, file naming, and calendar query instructions.
```