45 lines
1.8 KiB
Markdown
45 lines
1.8 KiB
Markdown
# 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. |