How to Create a Skill

A skill is a structured set of instructions that tells an AI model exactly what to do, what format to follow, and what good output looks like. Instead of writing a long prompt from scratch every time, you load a skill and get consistent, high-quality results.

There are two ways to create one.

Path 1: Use the Skill Writer

This is the path most people should take. The Skill Writer is a skill that builds other skills. It is specifically designed for ecommerce workflows and knows SkillShelf’s conventions, so the skills it produces are well-structured whether you keep them private or submit them to the library.

How it works

Open a new conversation in Claude or ChatGPT. Upload the Skill Writer’s SKILL.md file and its reference files. Then describe the ecommerce task you want to turn into a skill. Something like: “I want a skill that writes product collection descriptions from a Shopify catalog export.”

The Skill Writer walks you through four phases:

1. Understand. It asks what the skill does, who uses it, and what it produces. You can share rough notes, an existing prompt, example output, or just a sentence describing the idea. It collects what it needs and asks follow-up questions only for gaps.

2. Design. It presents a structured design summary covering the scope, input and output patterns, whether calibration is needed, edge cases, and how the skill fits into the broader ecosystem. You review this and confirm or adjust before any files are written.

3. Write. It produces all the files: the SKILL.md with instructions, an example output showing what the skill produces at its best, a skillshelf.yaml with metadata, and optionally a glossary if other skills will consume the output.

4. Review. It checks the produced files against a conventions checklist and flags anything that needs fixing.

By the end, you have a complete skill directory ready to use or submit.

Why use it over a generic approach

The Skill Writer knows how ecommerce skills should handle CSV data from Shopify, WooCommerce, Amazon, and other platforms. It knows when to include a calibration step and when not to. It knows how to structure output so other skills can reference it. If you later decide to submit your skill to SkillShelf, all the documentation and metadata are already in place.

That said, the conventions it follows produce better skills regardless of whether you submit. Clear scope, structured input handling, honest confidence notes, and well-organized output are good practices for any skill, including ones you only use privately.

Alternatives for non-ecommerce skills

If you are building a skill that is not ecommerce-related, you can use Claude’s built-in skill-creator (go to Settings, then Capabilities, then Skills, and activate the “skill-creator” example skill) or start a conversation in ChatGPT describing the workflow you want to turn into a skill. Both platforms will help you generate a SKILL.md file.

Test and iterate

This is the most important part. Do not stop at the first version.

Once you have your skill, test it. Give it a real task and see what comes out. If the output is not right, tell the model what you would change. Be specific: “The tone is too formal,” “It is missing the size chart,” “It should always include a meta description.” The model will update the skill based on your feedback.

Test it again with a different input. Skills need to work across a range of scenarios, not just the one you tested first. If it handles product descriptions for jackets, try it with shoes. Try it with a product that has minimal information. Try it with messy data. Each test reveals edge cases that make the skill more robust.

Keep iterating until you are consistently getting results you would use without editing.

Path 2: Write it manually

If you have specific requirements around data handling, output structure, or prompting strategy, or if you want full control over every instruction, you can write a skill by hand. You can also start from a skill you built through conversation (Path 1) and edit it manually to fine-tune the details.

The format

Skills follow the Agent Skills open standard. At minimum, a skill is a folder containing a single file called SKILL.md.

The SKILL.md file has two parts: a YAML frontmatter block at the top, and markdown instructions below it.

Here is the basic structure:

---
name: product-description-writer
description: >
  Generate product descriptions from a product feed CSV.
  Use when given a product catalog or individual product
  data that needs customer-facing copy.
license: Apache-2.0
---

# Product Description Writer

## Overview
This skill generates product descriptions for ecommerce
product pages.

## Input
A product feed in CSV or JSON format containing at minimum:
product name, category, key features, and price.

## Instructions
1. Read the product data.
2. For each product, write a description that includes...

## Output format
Return each description as markdown with the product name
as an H2 heading...

## Examples
### Input
...
### Expected output
...

Frontmatter fields

The frontmatter is the metadata block between the --- markers. Two fields are required:

name (required): A lowercase, hyphenated identifier. Max 64 characters. Letters, numbers, and hyphens only. This becomes the folder name and the way platforms identify your skill.

description (required): A plain-language explanation of what the skill does and when to use it. Max 1024 characters. This is how AI platforms decide whether to activate your skill for a given task, so be specific about both the capability and the trigger conditions.

license (recommended): For SkillShelf submissions, this should be Apache-2.0.

You can also include optional metadata fields for author, version, and other properties. See the full specification for details.

The instruction body

Below the frontmatter, write the actual instructions in markdown. This is what the AI reads when the skill is activated. A few principles that lead to better results:

Write in the imperative. “Read the input file” is better than “The skill should read the input file.”

Be specific about the output format. If you want a markdown table, say so. If you want a JSON object with particular keys, define them. Vague instructions produce vague results.

Include examples. Show what good input looks like and what the corresponding output should be. Examples are one of the most effective ways to get consistent behavior from a model.

Define constraints explicitly. If the skill should never invent information that is not in the input data, say that. If it should always include a particular field in the output, say that. Models follow explicit rules more reliably than implied ones.

Keep the main SKILL.md under 500 lines. If you need extensive reference material, documentation, or supporting scripts, put them in subdirectories:

my-skill/
  SKILL.md
  references/
    style-guide.md
  scripts/
    validate.py
  assets/
    template.html

Reference these files from your SKILL.md using relative paths, and the platform will load them as needed.

SkillShelf-specific metadata

When you submit a skill to SkillShelf, we generate a skillshelf.yaml sidecar file that captures additional metadata like category, tags, and install method. You do not need to create this yourself. It is generated automatically from the information you provide in the submission form.

Submitting your skill to SkillShelf

Whether you built your skill through conversation or wrote it by hand, the end result is the same: a skill file you can share.

To submit it to SkillShelf, go to the submit page and upload your file. We accept .skill files (exported from Claude) and .zip files (exported from ChatGPT or packaged manually). Pick a category, add some tags, and submit. We review it, run it through our certification process, and if it passes, it goes on the site.

If you prefer working with GitHub directly, you can also fork the repository and open a pull request.

Every skill on SkillShelf is published under the Apache 2.0 license.