Authoring Guide

What is a skill?

A skill is a markdown file that instructs an AI agent how to perform a specific task. When placed in the agent's skills directory (for example ~/.claude/skills/ for Claude Code or ~/.agents/skills/ for Codex), the agent loads it when a task calls for it and follows its guidance.

Skill directory structure

my-skill/
  SKILL.md          # Required - the skill instructions
  examples/         # Optional - usage examples
    example-1.md
  SELF-TEST.md      # Optional - self-test instructions

The only required file is SKILL.md. Everything else is optional.

Writing SKILL.md

A skill file is standard markdown with a few conventions.

Front matter

Start with a YAML front matter block containing metadata:

---
name: my-skill
display_name: My Skill
category: code-review
description: One-line description of what the skill does
tags:
  - lang-python
  - ctx-testing
---

You do not number versions yourself: each push creates the next version.

Body structure

After the front matter, write the instructions the agent should follow. A typical structure:

## Purpose

Explain what the skill does and when to use it.

## Instructions

Step-by-step guidance for the agent.

## Rules

Constraints, edge cases, and things to avoid.

## Examples

Inline examples showing input/output pairs.

Writing effective instructions

Be specific. Vague instructions produce inconsistent results. Instead of "review the code", write "check for unused imports, missing error handling, and functions longer than 50 lines."

Use imperative mood. Write "Return a bulleted list" rather than "You should return a bulleted list."

Include examples. Show the agent what good output looks like. Concrete examples are more effective than abstract rules.

Set boundaries. Tell the agent what not to do. If the skill should only analyze code without modifying it, say so explicitly.

Keep it focused. One skill should do one thing well. A skill that tries to do code review, test generation, and documentation at once will do all three poorly.

Adding examples

Create an examples/ directory with markdown files showing real usage:

examples/
  python-fastapi.md
  typescript-express.md

Each example file should contain a description of the scenario and the expected agent output.

Validation

Before publishing, validate your skill locally:

jsm validate ./my-skill

This checks:

• SKILL.md exists and is valid markdown
• Front matter contains all required fields
• The name field is URL-safe
• The description is under the character limit
• No broken internal links

Self-tests

A SELF-TEST.md file defines a test scenario the agent can run to verify the skill works correctly. This is optional but recommended for complex skills.

jsm create my-skill --with-self-test

Local testing

Install your skill locally and try it in your agent (Claude Code shown here):

# Mirror from workspace to ~/.claude/skills/
jsm workspace mirror my-skill

# Or copy manually
cp -r ./my-skill ~/.claude/skills/

Then open your agent in a project and ask it to perform the task your skill covers. Verify the output matches your expectations.

Categories

Skills are organized into categories for catalog browsing. The category field takes one of:

workflow, code-generation, code-review, testing, debugging, documentation, refactoring, architecture, devops, brainstorming, learning, productivity, flywheel-tool, multi-agent, other

Choose the category that best fits your skill's primary purpose. jsm validate and jsm push refuse any other value.

Versioning

Every time you push an update, a new version is created automatically. Users can pin to specific versions or receive updates on sync. Write a clear changelog message with each push:

jsm push ./my-skill -m "Added support for async functions"