Writing Effective Skills

What Is a SKILL.md File?

A SKILL.md file is a structured Markdown document that teaches an AI coding tool how to perform a specific task. It combines YAML frontmatter (metadata) with a Markdown body (instructions). Praxl uses SKILL.md as the canonical format across all supported platforms.

Anatomy of a Skill

Every skill has two parts: YAML frontmatter for metadata, and a Markdown body for instructions.

---
name: code-review
description: Performs a thorough code review with actionable feedback
version: 1.2.0
tags:
  - review
  - quality
---

# Code Review

## Trigger
Run this skill when asked to "review", "CR", or "check this PR".

## Steps
1. Read every changed file in the diff.
2. For each file, check for:
   - Logic errors and edge cases
   - Naming clarity and consistency
   - Missing error handling
   - Performance concerns
3. Output findings grouped by severity (critical, warning, nit).

## Output Format
Use a Markdown table with columns: File, Line, Severity, Finding.

## Examples
```
| File         | Line | Severity | Finding                        |
|--------------|------|----------|--------------------------------|
| src/auth.ts  | 42   | critical | Token is never validated       |
| src/utils.ts | 18   | warning  | O(n^2) loop, consider a Set    |
```

Frontmatter Fields

Structure Best Practices

• Clear instructions - write as if you are giving directions to a capable but literal colleague. Be explicit about what to do and what not to do.
• Numbered steps - break the task into an ordered sequence. AI tools follow numbered lists more reliably than prose paragraphs.
• Concrete examples - show the expected input and output. A single example is worth a paragraph of explanation.
• Triggers- define when the skill should activate. Use a "Trigger" section to list phrases or contexts (e.g., "when the user says review this PR").
• Output format - specify exactly how results should be presented (Markdown table, bullet list, code block, etc.).

Quality Dimensions

When you request an AI review of your skill in the Skill Editor, Praxl scores it across five dimensions:

1. Clarity - are the instructions unambiguous and easy to follow?
2. Specificity - does the skill avoid vague language and provide concrete details?
3. Structure - is the document well-organized with headings, numbered steps, and logical flow?
4. Completeness - does the skill cover edge cases, error handling, and output format?
5. Actionability - can the AI tool execute the skill without asking follow-up questions?

Each dimension is scored from 1 to 5. The overall quality score is the average. Skills scoring 4+ are considered production-ready.

Reference Files

Some skills need supporting material - code templates, configuration snippets, example outputs, or helper scripts. These are stored as reference files alongside the skill.

my-skill/
  SKILL.md
  references/
    template.tsx
    config-example.json
  scripts/
    setup.sh
  assets/
    diagram.png

Reference files are synced alongside the skill to every target platform. You can create and edit them directly in the web editor.

Platform-Specific Tips

• Some platforms impose file size limits. Keep skills concise - if a skill exceeds 50 KB, consider splitting it or moving large examples into reference files.
• File format requirements vary. Praxl handles conversion automatically, but be aware that some platforms expect .md files while others use .yaml or custom extensions.
• Certain platforms do not support reference file directories. In those cases, Praxl inlines critical references into the skill body during sync.

Anti-Patterns

Avoid these common mistakes:

• Vague instructions- "Write good code" tells the AI nothing. Be specific: "Use early returns instead of nested if-else blocks."
• No examples - without a concrete example, the AI has to guess your expectations. Always include at least one.
• Too long - a 2,000-line skill will overwhelm context windows. Keep the core instructions under 200 lines and use reference files for supporting material.
• No triggers - if you do not specify when the skill should activate, it may never be invoked or may fire at the wrong time.