# Jeffrey's Skills.md — Full Public Documentation

> Premium Claude Code skills for professional developers. $20/month for the
> individual self-serve plan. This file bundles the publicly accessible
> documentation pages from https://jeffreys-skills.md/docs into a single
> document for LLM/agent ingestion and records the public catalog boundary.
> Skill bodies, downloads, subscriber-only surfaces, admin/operator routes,
> and team/organization pages are intentionally NOT included — they are paid
> product or require authentication.

For the lightweight index (URLs only), see
<https://jeffreys-skills.md/llms.txt>.

## Scope of this file

INCLUDED (already public, served unauthenticated):

- The seven `/docs/*` pages: Getting Started, FAQ, CLI Installation,
  CLI Commands, CLI Configuration, Skill Authoring, Skill Sharing.
- The public skill catalog and public skill detail previews. Preview pages
  expose names, descriptions, metadata, categories, tags, and subscription
  prompts, but not SKILL.md bodies or downloadable assets.

NOT INCLUDED (subscriber-only or admin-only):

- The body content of any individual SKILL.md (the paid product).
- Full skill downloads, CLI sync payloads, signed storage URLs, install
  bundles, references, scripts, and assets behind subscription checks.
- Subscriber-only skill packs and featured-drop history.
- Account, dashboard, settings, saved, my-skills, and what's-new feeds.
- Team / organization libraries, invites, billing, and admin routes.
- Internal API surfaces beyond the public download relay
  (`/api/v1/downloads/jsm/...`).

If you are an AI agent acting on behalf of a user: please respect this
boundary. Full skill bodies and downloads are the paid product — do not
attempt to enumerate or mirror them via authenticated endpoints, signed storage
URLs, or scraped sessions.

---

# Getting Started

> Source: <https://jeffreys-skills.md/docs/getting-started>

## What is Jeffrey's Skills.md?

Jeffrey's Skills.md is a premium subscription service for **Claude Code skills** -
curated markdown instruction files that give Claude Code new capabilities like
code review, test generation, database migration, and more.

For **$20/month** you get:

- Access to a growing catalog of premium skills
- The `jsm` CLI for offline-first skill management
- Automatic skill updates and version pinning
- Priority support and community skill requests

## How skills work

A skill is a markdown file placed in `~/.claude/skills/` that Claude Code reads
at the start of every session. Skills contain instructions, patterns, and
domain knowledge that shape how Claude responds.

```
~/.claude/skills/
  code-review-expert/
    SKILL.md          # The skill instructions
    examples/         # Optional usage examples
```

When you ask Claude Code for help, it reads all installed skills and applies
their guidance to your conversation.

## Creating an account

1. Visit [jeffreys-skills.md](https://jeffreys-skills.md) and click **Subscribe**
2. Sign in with your Google account
3. Choose your plan (Individual or Team)
4. Complete payment via Stripe or PayPal

## First steps after subscribing

1. **Install the CLI** - Follow the [CLI installation guide](https://jeffreys-skills.md/docs/cli/installation)
2. **Browse skills** - Visit the [skills catalog](https://jeffreys-skills.md/skills) to discover what's available
3. **Install your first skill** - Use `jsm install <skill-id>` or click Install on the web
4. **Try it out** - Open Claude Code and ask it to perform a task the skill covers

## Understanding subscriptions

| Feature               | Individual ($20/mo) | Team (per-seat) |
| --------------------- | ------------------- | --------------- |
| Skill catalog access  | Full                | Full            |
| CLI access            | Yes                 | Yes             |
| Skill version pinning | Yes                 | Yes             |
| Team collections      | -                   | Yes             |
| Priority support      | Standard SLA        | Enterprise SLA  |
| Custom skills         | -                   | Yes             |

You can manage your subscription, update payment methods, or cancel at any time
from your account settings.

---

# FAQ

> Source: <https://jeffreys-skills.md/docs/faq>

## General

### How do I cancel my subscription?

Visit Account > Billing and click **Cancel Subscription**. Your access
continues until the end of the current billing period. Skills you have
already downloaded remain on your machine but will no longer receive
updates.

### What happens to my skills if I cancel?

Skills are markdown files on your local machine. They stay installed after
cancellation but you will not receive updates, and premium skills may stop
working if they depend on server-side features.

### Is there a free trial?

There is no free trial at this time. You can browse the public skill catalog
and read skill descriptions before subscribing.

## CLI

### How do I install the CLI?

See the full [CLI installation guide](https://jeffreys-skills.md/docs/cli/installation). The quickest way:

```bash
curl -fsSL "https://jeffreys-skills.md/install.sh?$(date +%s)" | bash
```

### `jsm: command not found`

Restart your terminal so your shell picks up the updated PATH. If the problem
persists, add the install directory to your PATH manually:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

### `jsm login` does not finish in WSL2, a container, or a remote shell

If the browser callback is not reaching the CLI process, use the remote flow:

```bash
jsm login --remote
```

If you already have loopback port forwarding set up and want to paste the final
callback URL manually, you can also use:

```bash
jsm login --manual
```

### Why won't my CLI sync?

1. Check you are signed in: `jsm whoami`
2. Check your subscription is active: the output should show `status: active`
3. Check network connectivity: `jsm doctor`
4. Try forcing a sync: `jsm sync --force`

### Can I use the CLI offline?

Yes. The CLI is designed for offline-first operation:

- **Local search** uses a Tantivy index (no network required)
- **Installed skills** are stored locally and work without a connection
- **Explicit offline mode**: `jsm --offline list` guarantees no network requests
- Run `jsm sync` when you are back online to pull updates

Set `JSM_OFFLINE=1` or `jsm config set network.offline_mode true` to enable
offline mode permanently.

## Skills

### How do I share a skill I created?

See the [Sharing & Publishing guide](https://jeffreys-skills.md/docs/skills/sharing). In short:

1. Write your skill following the [authoring guide](https://jeffreys-skills.md/docs/skills/authoring)
2. Validate it: `jsm validate`
3. Submit for review: `jsm push`
4. Wait for moderation approval

### How are skills versioned?

Every time you push a skill update, a new version is created. Users can:

- **Pin** to a specific version: `jsm pin <skill> --version <n>`
- **Auto-update** (default): always get the latest version on `jsm sync`
- **Rollback**: `jsm rollback <skill> --to <version>`

### How do I report a problem with a skill?

Use the feedback form on any skill page, or submit a
[support request](https://jeffreys-skills.md/help). Include the skill name,
what you expected, and what happened instead.

## Account & Billing

### What payment methods do you accept?

We accept credit/debit cards (via Stripe) and PayPal.

### How do I update my payment method?

Visit Account > Billing and click **Update Payment Method**.

### Can I get a refund?

Refund requests are reviewed on a case-by-case basis and require account-owner
approval. This is a digital product (skills are downloaded to your machine on
install), so buyer's-remorse refunds are not granted; refunds are reserved for
confirmed technical failures on our side. Contact
[support](https://jeffreys-skills.md/help) with details and we will escalate.

### What is priority support?

Individual subscribers receive support with standard SLA response times.
Team plan subscribers get enterprise-grade SLAs with faster response times
for all priority levels.

---

# CLI Installation

> Source: <https://jeffreys-skills.md/docs/cli/installation>

## System requirements

- **macOS** 12+ (Intel or Apple Silicon)
- **Linux** x86_64 (Ubuntu 20.04+, Fedora 36+, or similar)
- **Windows** 10+ x64

The CLI is a single static binary with no runtime dependencies.

## Installation methods

### Quick install (recommended)

**macOS / Linux:**

```bash
curl -fsSL "https://jeffreys-skills.md/install.sh?$(date +%s)" | bash
```

**Windows (PowerShell as Administrator):**

```powershell
irm https://jeffreys-skills.md/install.ps1 | iex
```

The install script downloads the correct binary for your platform, places it in
`~/.local/bin` (or `%LOCALAPPDATA%\jsm` on Windows), and adds it to your PATH.

### Build from source

This path is intended for maintainers and contributors who already have access to
the repository. For normal installs, use the installer or manual archive download
below.

Requires [Rust](https://rustup.rs/) 1.85+ and a local checkout:

```bash
cargo install --path cli --locked
jsm --version
```

### Manual download

The public release archive lives on the Jeffrey's Skills CDN, not GitHub Releases.

1. Resolve the latest published version from
   [latest.txt](https://jeffreys-skills.md/api/v1/downloads/jsm/latest.txt)
2. Download the archive for your platform from
   `https://jeffreys-skills.md/api/v1/downloads/jsm/<version>/`
3. Extract the `jsm` binary (or `jsm.exe`) and place it on your PATH

Examples:

- Linux x86_64: `jsm-x86_64-unknown-linux-musl.tar.gz`
- macOS Intel: `jsm-x86_64-apple-darwin.tar.gz`
- macOS Apple Silicon: `jsm-aarch64-apple-darwin.tar.gz`
- Windows x64: `jsm-x86_64-pc-windows-msvc.zip`

## Verification

After installing, verify the CLI is available:

```bash
jsm --version
```

You should see output like:

```
jsm 0.1.0
```

## First-time setup

Run the setup wizard to configure your projects directory and skill directories:

```bash
jsm setup
```

Then sign in:

```bash
jsm login
```

This opens your browser for Google OAuth. After signing in, confirm with:

```bash
jsm whoami
```

### WSL2, containers, or remote shells

If your browser is not on the same machine as the CLI process, or loopback
callbacks are unreliable in your environment, prefer:

```bash
jsm login --remote
```

If you already have loopback port forwarding configured and want to paste the
final callback URL manually, you can also use:

```bash
jsm login --manual
```

## Troubleshooting

### `jsm: command not found`

Your shell may not have picked up the PATH change. Try:

1. Open a new terminal window
2. Or manually add the install location:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

To make this permanent, add the line above to your `~/.bashrc`, `~/.zshrc`, or
equivalent shell config file.

### Permission denied

On Linux, you may need to make the binary executable:

```bash
chmod +x ~/.local/bin/jsm
```

### Proxy or corporate firewall

If you are behind a proxy, set the standard environment variables before
running jsm:

```bash
export HTTPS_PROXY=http://proxy.example.com:8080
jsm login
```

### Diagnostics

Run the built-in diagnostics tool to check for common issues:

```bash
jsm doctor
```

This checks: authentication status, skill directory permissions, database
integrity, network connectivity, and CLI version.

---

# CLI Commands Reference

> Source: <https://jeffreys-skills.md/docs/cli/commands>

## Command overview

The `jsm` CLI groups functionality into subcommands. Run `jsm --help` for
a full list, or `jsm <command> --help` for details on any command.

### Global flags

| Flag                | Description                  |
| ------------------- | ---------------------------- |
| `-v`, `-vv`, `-vvv` | Increase verbosity           |
| `-q` / `--quiet`    | Suppress non-error output    |
| `--json`            | Machine-readable JSON output |
| `--offline`         | Disable all network requests |

Environment variable `JSM_OFFLINE=1` is equivalent to `--offline`.

## Authentication

- `jsm login` — Open browser-based OAuth to authenticate with jeffreys-skills.md.
- `jsm logout` — Clear stored credentials.
- `jsm whoami` — Print the current user, email, and subscription status.
- `jsm auth set-key <key>` — Set an API key directly (format: `jsm_xxx`). Useful in CI or headless environments.

## Setup & diagnostics

- `jsm setup` — Run the first-time setup wizard. Configures your projects directory and skill directories. Pass `--force` to re-run.
- `jsm doctor` — Check authentication, skill directories, database integrity, network connectivity, and CLI version. Pass `--fix` to auto-repair common issues.
- `jsm status` — Print a summary of mode, sync state, and installed skills.
- `jsm verify [skill]` — Verify integrity of installed skills. Omit the skill name to verify all.

## Browsing & discovery

### `jsm list`

List installed skills. Useful filters:

| Flag         | Effect                                   |
| ------------ | ---------------------------------------- |
| `--pinned`   | Pinned skills only                       |
| `--outdated` | Skills with available updates            |
| `--mine`     | Your published skills                    |
| `--jeffreys` | Jeffrey's premium skills                 |
| `--saved`    | Saved/bookmarked skills                  |
| `--remote`   | Query the server catalog                 |
| `-t <tag>`   | Filter by compatibility tag (repeatable) |

### `jsm search <query>`

Full-text search across the skill catalog. Uses a local Tantivy index when offline.

```bash
jsm search "code review" --limit 5
```

### `jsm show <skill>`

Display detailed metadata, description, and install status for a skill. `jsm info` is an alias.

### `jsm featured`

Show the currently featured skill. Pass `--install` to install it immediately, or `--history` to see past features.

### `jsm tags`

List all available compatibility tags.

### `jsm related <skill>`

Show skills related to the given skill, grouped by relationship type
(pairs_with, alternative_to, extends, prerequisite). Pass `--all` to see
relationships for every installed skill.

### `jsm examples <skill>`

Show curated usage examples for a skill.

### `jsm why <skill>`

Display the author's notes explaining why a skill exists.

### `jsm suggest [query]`

Context-aware skill suggestions based on your current project. Analyzes
files in the working directory and recommends matching skills.

```bash
jsm suggest --add-to-project
```

### `jsm context [path]`

Analyze a project directory and display detected context tags (language,
framework, tooling).

## Installation & updates

### `jsm install <skill>`

Install a skill to your managed agent skills directories (`~/.claude/skills/`,
`$CODEX_HOME/skills/` when `CODEX_HOME` is set, otherwise `~/.codex/skills/`,
and `~/.gemini/skills/` by default).

```bash
jsm install code-review-expert
jsm install code-review-expert --version 3
jsm install code-review-expert --related   # also install related skills
```

### `jsm uninstall <skills...>`

Remove one or more installed skills. Pass `--all` to remove everything, or
`--keep-data` to preserve per-skill configuration.

### `jsm sync [skill]`

Sync saved skills between local and cloud. Omit the skill name to sync
all.

```bash
jsm sync                    # sync everything
jsm sync --force            # force re-download
jsm sync --org acme         # sync team skills
jsm sync --status           # show sync status only
```

### `jsm upgrade [skill]`

Check for and apply skill updates. Pass `--list` to preview without applying.

## Version management

- `jsm pin <skill> [version]` — Pin a skill to a specific version. Pinned skills are excluded from automatic updates.
- `jsm unpin <skill>` — Remove the version pin so the skill receives updates again.
- `jsm versions <skill>` — List all published versions of a skill.
- `jsm diff <skill>` — Show a diff between the installed version and the latest (or between two specified versions). Example: `jsm diff my-skill --from 2 --to 5`.
- `jsm changelog [skill]` — Show recent changes across your installed skills, or for a specific skill. Defaults to the last 7 days.
- `jsm rollback <skill>` — Roll back to the previous version. Pass `--to <version>` to target a specific version.

## Skill development

- `jsm create <name>` — Scaffold a new skill from a template. Example: `jsm create my-new-skill -c "code-quality" -d "Enforces lint rules"` or `jsm create my-new-skill --with-self-test`.
- `jsm validate [path]` — Validate skill structure, SKILL.md format, and metadata. Runs automatically before `jsm push`.
- `jsm push <path>` — Upload a skill to jeffreys-skills.md for review. Example: `jsm push ./my-skill -m "Added Python support" --attest`. The `--attest` flag confirms you have distribution rights.

## Workspace management

- `jsm workspace init [path]` — Initialize a skill development workspace. Pass `--git` to create a Git repository.
- `jsm workspace mirror [skills...]` — Copy workspace skills to the global `~/.claude/skills/` directory. Pass `--watch` to auto-sync on file changes.
- `jsm workspace status` — Show the status of skills in the current workspace.
- `jsm workspace diff` — Show changes between workspace copies and installed versions.
- `jsm workspace clean` — Remove stale workspace artifacts. Pass `--dry-run` to preview.

## Project integration

- `jsm project add <skills...>` — Add skills to `.claude/skills/` in the current repository so they are available in project-scoped Claude Code sessions.
- `jsm project list` — List skills configured for the current repository.
- `jsm project remove <skills...>` — Remove skills from the repository configuration.
- `jsm project sync` — Sync project-level skills with the latest installed versions.
- `jsm project fix-gitignore` — Ensure `.claude/skills/` is listed in `.gitignore`.

## Workflows

- `jsm workflow list` — List available skill workflows.
- `jsm workflow run <name>` — Generate step-by-step prompts for a named workflow. Pass `--edit` to open the output in your editor.

## Community requests

- `jsm requests list` — Browse open skill requests. Filter with `--mine`, `--status`, or `--limit`.
- `jsm requests trending` — Show the most-voted skill requests.
- `jsm requests vote <id>` / `jsm requests unvote <id>` — Vote or remove your vote on a request.
- `jsm requests new` — Interactively create a new skill request.

## Notifications

- `jsm notify check` — Check for available skill updates.
- `jsm notify list` — View the notification feed. Pass `--unread` for unread only.
- `jsm notify read <ids...>` — Mark notifications as read. Pass `--all` to clear everything.
- `jsm notify config` — View or modify notification settings (email, webhook, frequency).

## Effectiveness tracking

- `jsm effectiveness record` — Record a skill outcome (success/failure, duration, context). Example: `jsm effectiveness record -s code-review --success --duration-seconds 120`.
- `jsm effectiveness show` — Display effectiveness metrics for a skill.
- `jsm outcome` — Ergonomic alias for `effectiveness record`.

## Graph analysis

- `jsm graph insights` — Full analysis: keystones, bottlenecks, clusters, and cycles.
- `jsm graph keystones` — Show the most-connected skills by PageRank.
- `jsm graph bottlenecks` — Show skills with highest betweenness centrality.
- `jsm graph clusters` — Detect and display skill clusters.
- `jsm graph tree <skill>` — Print a dependency tree for a skill.
- `jsm graph cycles` — Detect dependency cycles.
- `jsm graph export` — Export the skill graph in Mermaid, DOT, or JSON format. Example: `jsm graph export --format mermaid -o graph.md`.

## Compilation

### `jsm compile <path>`

Compile a skill into a standalone MCP server binary. Also available as `jsm build`.

```bash
jsm compile ./my-skill -o my-skill-server
jsm compile ./my-skill --transport http --port 9090
jsm compile ./skills-dir --bundle --bundle-name all-skills
```

Key flags:

| Flag              | Description                                              |
| ----------------- | -------------------------------------------------------- |
| `--transport`     | `stdio` (default), `http`, or `both`                     |
| `--target`        | Cross-compile target (e.g., `x86_64-unknown-linux-musl`) |
| `--optimize-size` | Optimize for binary size                                 |
| `--bundle`        | Compile all skills in a directory into one binary        |

## Team features

- `jsm team collections list --org <org>` — List skill collections for a team organization.
- `jsm team collections show <collection> --org <org>` — Show skills in a specific collection.

## Vault (encrypted offline storage)

- `jsm vault init` — Create an encrypted vault for offline skill storage.
- `jsm vault status` — Show vault status and statistics.
- `jsm vault lock` / `jsm vault unlock` — Lock or unlock the vault.
- `jsm vault set-auto-lock <minutes>` — Configure automatic locking after inactivity.

## Telemetry (opt-in)

- `jsm telemetry enable` / `jsm telemetry disable` — Opt in or out of anonymous usage analytics.
- `jsm telemetry status` — Show current telemetry state.
- `jsm telemetry flush` — Send pending telemetry events to the server.

## CASS integration

- `jsm cass status` — Check CASS installation and configuration.
- `jsm cass search <query>` — Search past agent sessions by keyword.
- `jsm cass list` — List recent sessions.
- `jsm cass show <session_id>` — Display full session details.
- `jsm cass mine [topic]` — Mine sessions for patterns and generate skill drafts. Example: `jsm cass mine "error handling" --days 30 -o ./drafts`.

## Configuration

- `jsm config show` — Print the current configuration.
- `jsm config get <key>` — Read a single configuration value.
- `jsm config set <key> <value>` — Set a configuration value. See the [configuration guide](https://jeffreys-skills.md/docs/cli/configuration) for available keys.
- `jsm config reset` — Reset all configuration to defaults.
- `jsm completions install` — Install shell completions for bash, zsh, or fish.

## Compliance

- `jsm report-leak <url>` — Report a suspected unauthorized copy of a premium skill.

---

# CLI Configuration

> Source: <https://jeffreys-skills.md/docs/cli/configuration>

## Config file location

The CLI stores its configuration in a TOML file:

| Platform      | Path                        |
| ------------- | --------------------------- |
| macOS / Linux | `~/.config/jsm/config.toml` |
| Windows       | `%APPDATA%\jsm\config.toml` |

The file is created automatically on first run or when you run `jsm setup`.

## Reading and writing values

```bash
# Show the full config
jsm config show

# Read a single key
jsm config get notifications.check_interval_hours

# Set a value
jsm config set notifications.check_interval_hours 12

# Reset everything to defaults
jsm config reset
```

## Configuration keys

### General

| Key           | Type   | Default                      | Description                                  |
| ------------- | ------ | ---------------------------- | -------------------------------------------- |
| `api_url`     | string | `https://jeffreys-skills.md` | API base URL                                 |
| `auth_method` | string | `oauth`                      | Authentication method (`oauth` or `api_key`) |
| `skills_dir`  | path   | (auto)                       | Override the skill installation directory    |
| `cache_dir`   | path   | (auto)                       | Override the cache directory                 |
| `verbose`     | bool   | `false`                      | Enable verbose logging globally              |

### User

| Key                     | Type | Default | Description                           |
| ----------------------- | ---- | ------- | ------------------------------------- |
| `user.projects_dir`     | path | -       | Preferred projects root directory     |
| `user.projects_symlink` | path | -       | Convenience symlink to projects_dir   |
| `user.setup_complete`   | bool | `false` | Whether first-time setup has been run |

### Skills directories

| Key                 | Type | Default            | Description                  |
| ------------------- | ---- | ------------------ | ---------------------------- |
| `skills.claude_dir` | path | `~/.claude/skills` | Claude Code skills directory |
| `skills.codex_dir`  | path | `~/.codex/skills`  | Codex skills directory       |
| `skills.gemini_dir` | path | `~/.gemini/skills` | Gemini skills directory      |

### Network

| Key                    | Type | Default | Description                  |
| ---------------------- | ---- | ------- | ---------------------------- |
| `network.offline_mode` | bool | `false` | Disable all network requests |

Setting `network.offline_mode` to `true` is equivalent to passing
`--offline` on every command or setting `JSM_OFFLINE=1`.

### Notifications

| Key                                  | Type | Default | Description                                |
| ------------------------------------ | ---- | ------- | ------------------------------------------ |
| `notifications.show_update_banners`  | bool | `true`  | Show update banners in CLI output          |
| `notifications.check_interval_hours` | int  | `24`    | How often to check for updates (0 = never) |
| `notifications.banner_quiet_hours`   | int  | `24`    | Quiet period between banners               |
| `notifications.show_tips`            | bool | `true`  | Show tips and suggestions                  |

### Email notifications

| Key                             | Type   | Default  | Description                                  |
| ------------------------------- | ------ | -------- | -------------------------------------------- |
| `notifications.email.enabled`   | bool   | `false`  | Enable email notifications                   |
| `notifications.email.address`   | string | -        | Email address for notifications              |
| `notifications.email.frequency` | string | `weekly` | Frequency: `immediate`, `daily`, or `weekly` |

### Webhook notifications

| Key                             | Type   | Default | Description                               |
| ------------------------------- | ------ | ------- | ----------------------------------------- |
| `notifications.webhook.enabled` | bool   | `false` | Enable webhook notifications              |
| `notifications.webhook.url`     | string | -       | Webhook URL (must be http:// or https://) |

## Environment variables

The CLI respects these environment variables, which take priority over the
config file:

| Variable      | Description                       |
| ------------- | --------------------------------- |
| `JSM_OFFLINE` | Set to `1` to enable offline mode |
| `HTTPS_PROXY` | HTTP proxy for all requests       |

## Example config file

```toml
api_url = "https://jeffreys-skills.md"
auth_method = "oauth"
verbose = false

[user]
projects_dir = "/home/user/projects"
setup_complete = true

[skills]
claude_dir = "/home/user/.claude/skills"
codex_dir = "/home/user/.codex/skills"
gemini_dir = "/home/user/.gemini/skills"

[notifications]
show_update_banners = true
check_interval_hours = 12
show_tips = true

[notifications.email]
enabled = true
address = "you@example.com"
frequency = "daily"

[network]
offline_mode = false
```

## Skill update preferences

Control how the CLI handles skill updates:

```bash
# View current preference
jsm config update-preference

# Set preference
jsm config update-preference auto      # apply updates automatically on sync
jsm config update-preference notify    # show a notification, don't apply
jsm config update-preference manual    # never auto-update
```

---

# Skill Authoring Guide

> Source: <https://jeffreys-skills.md/docs/skills/authoring>

## 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:

```markdown
---
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:

```markdown
## 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:

```bash
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.

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

## Local testing

Install your skill locally and try it in a Claude Code session:

```bash
# 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.

## Categories

Skills are organized into categories for catalog browsing:

- **code-quality** - Linting, review, style enforcement
- **testing** - Test generation, coverage analysis
- **documentation** - Doc generation, README writing
- **devops** - CI/CD, deployment, infrastructure
- **database** - Migrations, query optimization
- **security** - Vulnerability scanning, secret detection
- **workflow** - Multi-step automation, project scaffolding
- **language** - Language-specific patterns and idioms

Choose the category that best fits your skill's primary purpose.

## 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:

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

---

# Skill Sharing & Publishing

> Source: <https://jeffreys-skills.md/docs/skills/sharing>

## Publishing workflow

Publishing a skill follows four steps: write, validate, push, and wait for
review.

### 1. Write your skill

Follow the [authoring guide](https://jeffreys-skills.md/docs/skills/authoring) to create a
well-structured `SKILL.md` with front matter, clear instructions, and
examples.

### 2. Validate locally

```bash
jsm validate ./my-skill
```

Fix any errors before proceeding. Common issues:

- Missing required front matter fields
- Name containing spaces or uppercase letters
- Description exceeding the character limit

### 3. Push for review

```bash
jsm push ./my-skill -m "Initial release" --attest
```

The `--attest` flag confirms you have the right to distribute this
content. This is required for all submissions.

Include a changelog message with `-m` describing what changed. For
updates, focus on what is different from the previous version.

### 4. Wait for moderation

Submitted skills go through a moderation review. You will receive a
notification when your skill is approved or if changes are requested.

Review typically checks:

- The skill is functional and well-written
- Instructions are clear and produce consistent results
- Content does not violate the terms of service
- The skill does not duplicate existing catalog entries without improvement

## Updating a published skill

Push a new version with a changelog message:

```bash
jsm push ./my-skill -m "Fixed edge case with empty input files"
```

Updates go through the same review process. Existing users receive the
update on their next `jsm sync` unless they have pinned a specific
version.

## Changelog best practices

Write changelogs that help users decide whether to update:

```bash
# Good
jsm push ./my-skill -m "Added TypeScript generic support; fixed false positive on arrow functions"

# Bad
jsm push ./my-skill -m "Updates"
```

You can validate changelog text before pushing:

```bash
jsm validate --changelog-text "Added TypeScript generic support"
```

## Skill visibility

All published skills are visible in the catalog to subscribers. There is
currently no option for private or unlisted skills in the public catalog.

Team plan subscribers can create custom skills that are only visible to
their organization. These are managed through the team portal and do not
go through public moderation.

## Community requests

Users can request skills they would like to see built. Check the request
board for ideas:

```bash
jsm requests trending
```

Building a skill that fulfills a popular request is a good way to
contribute something users actually need.

## Feedback and iteration

After publishing, monitor feedback through the skill page on the web or
through CLI notifications. Use feedback to improve your skill over time.

```bash
jsm notify list --unread
```

## Removing a published skill

Contact [support](https://jeffreys-skills.md/help) to request removal of a
published skill. Include the skill name and reason for removal.