Skip to main content
This guide covers the structure, format, and requirements for creating new skills.

​
Skill Structure

Every skill follows this directory structure: 
skills/your-skill-name/
└── SKILL.md           # Required, under 500 lines
└── references/        # Optional, for detailed docs

​
Required: SKILL.md

The main skill file containing:
  • YAML frontmatter with metadata
  • Expert role definition
  • Instructions and workflows
  • Output format specifications
  • Examples and templates
Line limit: Keep under 500 lines for optimal performance.

​
Optional: references/

Detailed documentation loaded on demand. Use for:
  • Comprehensive guidelines (App Store Review Guidelines)
  • Large reference data (keyword lists, category taxonomies)
  • API documentation
  • Extended examples

​
YAML Frontmatter Format

Every SKILL.md must start with valid YAML frontmatter: 
---
name: your-skill-name
description: When the user wants to [action]. Also use when the user mentions "[trigger phrases]". For [related task], see [other-skill].
metadata:
  version: 1.0.0
---

​
Field Requirements

​
name
string
required
  • Must match directory name exactly
  • Lowercase letters and hyphens only
  • 1-64 characters
  • No consecutive hyphens
  • Pattern: ^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$
Valid: keyword-research, metadata-optimizer, ab-testInvalid: KeywordResearch, metadata--optimizer, ab_test
​
description
string
required
  • 1-1024 characters
  • Must include trigger phrases (“when”, “mention”, “use”)
  • Define scope boundaries
  • Cross-reference related skills
Example:
When the user wants to optimize app metadata for the App Store or Google Play. Use when the user mentions "keywords", "title", "description", or "ASO". For competitor analysis, see competitor-research.
​
metadata.version
string
required
Semantic version number (e.g., 1.0.0)

​
Naming Rules

Lowercase only: keyword-research
Hyphens for separation: app-store-optimizer
1-64 characters total
No consecutive hyphens: metadata--optimizer ❌
No underscores: ab_test ❌
No uppercase: KeywordResearch ❌

​
Writing the Skill

1

Start with Role Definition

Begin the content with a clear expert role:
You are an expert in App Store Optimization (ASO) with deep knowledge of:
- Apple App Store Search algorithm
- Google Play search ranking factors
- Keyword research methodologies
- A/B testing best practices
2

Include Structured Output Format

Define exactly what the agent should produce:
## Output Format

Provide recommendations in this structure:

**Title Options**
1. [Option 1] (XX chars) — [Rationale]
2. [Option 2] (XX chars) — [Rationale]

**Keyword Strategy**
- Primary: [keywords]
- Secondary: [keywords]
- Keyword density: X%
3

Add Cross-References

Include a “Related Skills” section:
## Related Skills

- For competitor analysis: `competitor-research`
- For A/B testing: `ab-test-framework`
- For localization: `metadata-localization`
4

Include Real Examples

Add practical examples from real apps:
## Example

**Before:** "Best Photo Editor - Filters & Effects"
- Issues: Generic terms, low keyword efficiency

**After:** "ProCam: RAW Photo Editor"
- Improvements: Unique brand, specific feature, technical keyword

​
Description Best Practices

The description drives skill discovery. Agents read all descriptions to decide which skill to load.

​
Include Trigger Phrases

description: When the user wants to research and select keywords for app metadata. Use when the user mentions "keyword research", "ASO keywords", "search terms", or "keyword optimization". For metadata writing, see metadata-optimizer.

​
Define Scope Boundaries

Clearly indicate what the skill does NOT cover: 
description: When the user wants to analyze competitor apps. Use when the user mentions "competitor analysis", "competitive research", or "market positioning". For keyword research, see keyword-research. For feature comparison, see feature-analysis.

​
Validation

Before submitting, run the validation script: 
bash validate-skills.sh

​
What Gets Checked

  • YAML frontmatter exists
  • name field present and matches directory
  • description field present and 1-1024 chars
  • metadata.version field present
  • Matches pattern: ^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$
  • No consecutive hyphens (--)
  • Lowercase only
  • 1-64 characters
  • Contains trigger phrases (“when”, “mention”, “use”)
  • Length between 1-1024 characters
  • Warning if SKILL.md exceeds 500 lines
  • Move lengthy content to references/ directory

​
Example Validation Output

$ bash validate-skills.sh

PASS: keyword-research (287 lines)
PASS: metadata-optimizer (412 lines)
ERROR: ab-test — missing 'description' in frontmatter
WARNING: competitor-research — SKILL.md has 523 lines (recommended: <500)

Results: 1 errors, 1 warnings

​
Complete Example

Here’s a minimal but complete skill: 
---
name: keyword-research
description: When the user wants to research and select keywords for app metadata. Use when the user mentions "keyword research", "ASO keywords", or "search optimization". For metadata writing, see metadata-optimizer.
metadata:
  version: 1.0.0
---

You are an expert in App Store Optimization keyword research.

## Process

1. **Seed Keywords**: Start with core app features and benefits
2. **Expansion**: Use App Store autocomplete, competitor analysis
3. **Filtering**: Remove irrelevant, too competitive, or trademarked terms
4. **Prioritization**: Balance search volume, relevance, competition

## Output Format

**Recommended Keywords**

| Keyword | Volume | Competition | Relevance | Priority |
|---------|--------|-------------|-----------|----------|
| [term] | High/Med/Low | High/Med/Low | 1-10 | P0/P1/P2 |

**Keyword Field (100 chars)**
term1,term2,term3 

## Related Skills

- For metadata writing: `metadata-optimizer`
- For competitor analysis: `competitor-research`

​
Next Steps

Agent Guidelines

Learn writing style and formatting conventions

Build docs developers (and LLMs) love

Get started for freeTalk to us