What is the purpose of the frontmatter in SKILL.md?

The frontmatter provides essential metadata (name and description) and must match the directory name for consistency.

Where should I place long-form docs vs code?

Place long-form docs in references/ and code in scripts/. Assets can go in assets/. Keep SKILL.md concise and within 500 lines.

How do I validate a new skill before publishing?

Ensure the frontmatter name matches the directory name, tests/scripts run, and all required folders/files exist before publishing.

create-skill

npx machina-cli add skill aiskillstore/marketplace/create-skill --openclaw

Files (1)

SKILL.md

1.2 KB

Create Skill

Skill Structure

skill-name/
├── SKILL.md          # instructions + metadata
├── scripts/          # executable code (optional)
├── references/       # documentation (optional)
└── assets/           # templates/resources (optional)

Requirements

Frontmatter: Must include name (lowercase-alphanumeric) and description.
Description: Must include what it does and when to use it.
Body: Keep under 500 lines. Use imperative language.
Resources: Move detailed docs to references/ and code to scripts/.

Process

Directory: mkdir <name>. Create scripts/, references/, or assets/ only if you actually have content for them.
Metadata: Write the SKILL.md frontmatter first.
Resources: Implement scripts and test them.
Instructions: Write concise steps in SKILL.md body.
Verify: Ensure frontmatter name matches directory name.

References

Source

git clone https://github.com/aiskillstore/marketplace/blob/main/skills/0xmsc/create-skill/SKILL.mdView on GitHub

Overview

This skill outlines the standard structure for a new Agent Skill, including required frontmatter, the folder layout, and a practical workflow. It emphasizes separating metadata (SKILL.md), code (scripts/), and references (references/) to keep skills consistent and maintainable. Following the process helps teams launch reliable, well-documented skills.

How This Skill Works

Start by naming the directory and writing a SKILL.md frontmatter with name and description. Then populate optional folders (scripts, references, assets) only if you have content, and keep the body under 500 lines written in imperative language. Finally, verify that the frontmatter name matches the directory name before publishing.

When to Use It

When starting a brand-new Agent Skill from scratch.
When documenting or auditing metadata for an existing skill.
When organizing detailed docs and code into dedicated folders.
When validating consistency between the directory name and frontmatter.
When preparing a skill for handoff to another team.

Quick Start

Step 1: mkdir <name>
Step 2: Create SKILL.md with frontmatter: name: <name>, description: <description>
Step 3: Add content to references/ and/or scripts/ as needed, then verify the frontmatter name matches the directory name

Best Practices

Use lowercase-alphanumeric only for the frontmatter name.
Ensure the description clearly states what the skill does and when to use it.
Keep the SKILL.md body concise, under 500 lines, and in imperative language.
Move detailed docs to references/ and code to scripts/ with tests.
Always verify frontmatter name matches the directory name before publishing.

Example Use Cases

weather-skill: create a new skill with SKILL.md frontmatter, add reference docs in references/, and a sample script in scripts/.
summarize-chat-skill: add references/chat-summary.md for documentation and scripts/summarize.py for code.
data-clean-skill: include references/data-cleaning.md plus scripts/clean.py and tests.
notify-team-skill: store notification templates in references/, and a sending script in scripts/.
auth-skill: document authentication flow in references/auth-flow.md and implement checks in scripts/auth-check.py.

Frequently Asked Questions

Add this skill to your agents