# Meta-Skill Reference Guide

This document contains rules for description formatting, file splitting, and structural guidelines for `ai-superpower` agent skills.

## Skill Structure
The default storage places the main instructions inside a dedicated folder:

```
.ai/skills/skill-name/
├── SKILL.md           # Main instructions (required - strictly < 100 lines)
├── REFERENCE.md       # Detailed docs or explanations (if needed)
└── EXAMPLES.md        # Enormous code blocks / usage examples (if needed)
```

## Description Requirements

The `description:` field in the YAML frontmatter is **the only thing your agent sees** when deciding which skill to load. It surfaces in the system prompt. It MUST be optimized for LLM tool-calling logic.

**Goal**: Give the agent enough info to know:
1. What capability this skill provides.
2. When/why to trigger it.

**Format**:
- Max 1024 chars.
- Write in the third person.
- First sentence: what it does.
- Second sentence: "Use when [specific triggers or keywords]."

**✅ Good example**:
```yaml
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
```

**❌ Bad example**:
```yaml
description: Helps with documents.
```
*(The bad example gives the agent no operational triggers to distinguish this from other document parsing tools).*

## When to Split Files

Do not create empty or slightly used `REFERENCE.md` files. Split into separate files ONLY when:
- The core `SKILL.md` (which should only contain Prohibitions, Workflows, and short Examples) exceeds 100 lines.
- The content has entirely distinct domains (e.g., theory vs. hard practice rules).
- The skill includes massive code examples that do not need to be loaded during every minor task.