Understanding the Openclaw Skill.md Format

What is skill.md?

Every Openclaw skill must include a skill.md file in its root directory. This file is the skill manifest — it tells Openclaw what the skill does, what permissions it needs, and how to use it.

File Structure

A typical skill.md includes these sections:

### Metadata Header ``yaml --- name: My Skill Name version: 1.0.0 description: A brief description of what this skill does author: Author Name tags: [tag1, tag2, tag3] ---

### Description Section A detailed explanation of what the skill does, its use cases, and any important context.

### Configuration Section Documents all required and optional configuration: - Environment variables - API keys - File paths - Feature flags

### Usage Section Examples of how to invoke the skill, including: - Basic commands - Advanced patterns - Expected outputs

### Permissions Section Explicitly declares what the skill needs: - Network access - Filesystem access - Shell execution - Secret management

Best Practices

• Be explicit about permissions — list everything the skill needs
• Include examples — real-world usage patterns help users
• Document configuration — every variable and option
• Version correctly — use semantic versioning
• Keep it current — update as the skill evolves

Validation

You can validate your skill.md format using: - The official Openclaw skill linter - Community validation tools - Manual review against the specification

Common Mistakes

• Missing required metadata fields
• Undocumented permissions
• Outdated version numbers
• Missing usage examples