ai-superpower/.ai/skills/write-skill/REFERENCE.md

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:

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:

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.