How to Write a Great SKILL.md File: A Creator's Guide

A SKILL.md file is the core of every AI skill on AgentPowers. It's a markdown file with YAML frontmatter that tells an AI assistant exactly how to perform a specific task.

When someone installs your skill, this file is what their AI reads. The quality of your SKILL.md directly determines:

• How well the skill performs
• How consistent the output is
• How many people buy it
• How many positive reviews you get

If you're new to skills, start with our beginner's guide to AI skills.

Every SKILL.md starts with YAML frontmatter between --- markers:

---
title: Code Review Pro
description: Comprehensive code review with security, performance, and style analysis
category: development
---

The frontmatter fields:

• title: Clear, descriptive name (3-100 characters). This shows in marketplace search results.
• description: One-line summary (10-500 characters). This is what buyers read first. Be specific about what the skill does, not vague marketing.
• category: Must match a valid marketplace category (development, productivity, marketing, design, sales, data, security).

For agents, also include tools and model. See skills vs agents to understand the difference.

After the frontmatter, write the instructions as if you're training a smart but literal team member. Be explicit about:

• The task: "You are a code review specialist. When the user shares code, analyze it for..."
• The methodology: Step-by-step process the AI should follow
• The output format: Tables, checklists, reports, structured sections
• Edge cases: "If the file is too large, focus on the top 3 issues"
• What NOT to do: "Don't rewrite the code. Only identify issues and suggest fixes."

The #1 mistake creators make is being too vague. "Review this code" produces generic output. "Analyze this code for SQL injection, XSS, CSRF, authentication bypasses, and insecure direct object references, using the OWASP Top 10 as your framework" produces expert-level output.

The best-selling skills include example outputs that show the AI what "good" looks like:

## Example Output Format

### Security Review: auth.py

| Severity | Line | Issue | Fix |
|----------|------|-------|-----|
| Critical | 42 | SQL injection via string concatenation | Use parameterized queries |
| High | 78 | Hardcoded API key | Move to environment variable |
| Medium | 15 | Missing rate limiting | Add rate limiter middleware |

**Summary**: 3 issues found (1 critical, 1 high, 1 medium)
**Recommendation**: Fix critical issue before deploying

This gives the AI a concrete template to follow, making output consistent across every use.

Before you publish to the marketplace:

1. Test with real projects: Not toy examples. Use production codebases with messy, real-world code.
2. Test edge cases: Empty files, huge files, multiple languages, files with errors.
3. Test with different platforms: Try it in Claude Code, Cursor, and Windsurf.
4. Get feedback: Share with a colleague and ask if the output is useful.
5. Iterate: Refine based on where the output falls short.

Skills that pass this process are worth $15-29. Skills that skip it produce generic output that anyone could get by asking the AI directly. That's the difference between a product and a prompt.

Once your SKILL.md is ready, you can publish from the web dashboard or via the CLI.

Your skill goes through an 8-layer security scan automatically. Once it passes, it's listed on the marketplace and available to users on 12+ AI platforms.

For pricing strategy, see our creator earning guide.