Jeffrey's Skills.md

What is a skill?

A skill is a markdown file that instructs Claude Code how to perform a specific task. When placed in ~/.claude/skills/, Claude reads the file at the start of every session 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
title: My Skill
category: code-quality
description: One-line description of what the skill does
tags:
  - python
  - linting
version: 1
---

Field	Required	Description
`name`	yes	URL-safe identifier (lowercase, hyphens)
`title`	yes	Human-readable name
`category`	yes	Skill category
`description`	yes	One-line summary
`tags`	no	Compatibility tags for discovery
`version`	no	Auto-incremented on push

Body structure

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

## Purpose

Explain what the skill does and when to use it.

## Instructions

Step-by-step guidance for Claude.

## 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 Claude what good output looks like. Concrete examples are more effective than abstract rules.

Set boundaries. Tell Claude 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 Claude 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 Claude 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 a Claude Code session:

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

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

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

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"

Authoring Guide