A FIELD GUIDE TO THE / COMMAND

Skills
& how to wield them.

A Skill is a folder Claude Code hot-loads on demand, a tiny briefing that says when to apply a procedure and how to execute it. It turns Claude from a clever autocomplete into a specialist that shows up with the right tools already in hand.

WHAT IT IS A folder · 1 markdown + assets

HOW IT FIRES Description field → auto-trigger

WHERE IT LIVES ~/.claude/skills/ or a plugin

WHY BOTHER Repeatable wins, one keystroke

01 / ANATOMY

It's not just markdown. It's a briefcase.

Every skill is a directory. The only required file is SKILL.md, a short document with YAML frontmatter on top and the body of instructions below.

The frontmatter's description is the entire trigger mechanism. Claude scans skill descriptions at session start; when your message matches one, the skill gets loaded in full. Write the description like a casting call, who should show up, when.

The folder can carry scripts, templates, reference images, JSON fixtures , anything Claude might need. Think of a skill as a mission briefing Claude opens on arrival.

~/.claude/skills/seo-audit/SKILL.md MD

---
name: seo-audit
description: Use when the user wants to audit
  a page or site for SEO, meta tags, headings,
  core web vitals, internal links. Do NOT use
  for pure copy editing.
---

# SEO Audit

## When to use
Any ask that smells like "why isn't this ranking",
"audit /pricing", or "check meta tags".

## Procedure
1. Read the target URL with WebFetch.
2. Run scripts/lighthouse.mjs against it.
3. Emit a markdown report using
   templates/report.md as scaffold.
4. Highlight the top 3 wins by traffic impact.

## Gotchas
- Never trust rendered-after-JS text as SSR content.
- Canonical tags beat redirects, check both.

THE DESCRIPTION IS EVERYTHING

If it doesn't fire, your description is too vague or too narrow. Write it as "use when ___ ; do not use for ___".

SHIP SCRIPTS WITH THE SKILL

Drop scripts/, templates/, or fixtures/ beside SKILL.md. Claude can read and run them.

RIGID vs FLEXIBLE

Some skills should be followed exactly (TDD, deploy checklists). Others are principles to adapt. Say which in the doc.

02 / INVOCATION FLOW

From your message to the specialist in the room.

You type.

Natural prompt, or an explicit /skill-name.

Claude scans.

Every skill's description is matched against your intent.

Skill hot-loads.

The full SKILL.md plus any referenced assets enter context.

Procedure runs.

Claude follows the briefing, steps, scripts, gotchas, exactly.

Result, announced.

Good skills announce "using [skill]", then ship the work.

03 / PLAYGROUND

Try one. Actually try one.

COMMAND PALETTE

Click a skill to simulate the invocation, or type a command below.

claude · session 0x01 · /Users/dotcomjack LIVE

// boot sequence ........ ok // loading skills ........ 53 skills indexed $ Click a skill on the left to simulate an invocation. Or type below, try /brainstorming, /frontend-design, /diagnose

04 / USE CASES FOR THE EMPIRE

Skills tailored to the products you're already building.

05 / BUILD YOUR FIRST SKILL IN 4 MINUTES

A folder, a file, a victory lap.

Pick any repetitive task you've done twice this month. That's a skill waiting to be born.

Create the folder. mkdir -p ~/.claude/skills/ship-daily
Drop a SKILL.md with YAML frontmatter: name + description.
Write the description as a trigger, "Use when…" "Do not use for…".
Body = the briefing. Steps, gotchas, acceptance criteria.
Add assets beside it. scripts/, templates/, fixtures.
Test it cold. New session. Fuzzy prompt. Did it fire?
Iterate on the description every time it misfires. That's the whole game.

TEMPLATE · copy & adapt

---
name: ship-daily
description: Use when Jack says
  "ship it", "push to prod", or "let's deploy".
  Runs the full pre-flight checklist before any
  deploy to Render. Do not use for local dev.
---

# Ship Daily

## When to use
Any deploy-ish phrasing. Always run, even if
Jack is in a hurry. Especially then.

## Procedure
1. git status clean?
2. Run npm test + npm run typecheck.
3. GET /env-vars from Render first, merge, PUT.
4. Tag the release. Push. Watch the deploy log.
5. Smoke-test the live URL in claude-in-chrome.
6. Report the SHA + URL back.

## Gotchas
- Render PUT /env-vars REPLACES all vars.
  GET first. Always.
- Never DELETE + re-INSERT to regenerate.

06 / DISTRIBUTION

One folder is a habit. A marketplace is a team.

A skill in your home directory helps exactly one person. The moment it works, the question stops being "does this save me time" and becomes "why is everyone else still doing it by hand."

Wrap it in a plugin. A plugin is a folder with a skills/ directory inside it. Every skill folder you already wrote moves in unchanged.
List it in a marketplace. A marketplace.json names the catalog and points at each plugin, either a local path or a git repo.
Point people at it. claude plugin marketplace add <repo>, then claude plugin install <plugin>@<marketplace>.
Pick the scope deliberately. user is you, project is committed and shared with the team, local is gitignored. Scope is the difference between a personal shortcut and a team standard.

One thing that trips people up: a skill inside a plugin gets namespaced by the plugin name, while a skill in ~/.claude/skills/ is named by its folder. Same file, different command, depending on where it lives.

07 / DISPATCHES FROM X

What the builders are actually saying.

Thariq @trq212

Lessons from building Claude Code: we use skills for signup flow drivers, checkout verifiers, tmux CLI drivers, anything we'd do twice.

VIEW ON X →

elvis @omarsar0

Combining Remotion with claude-in-chrome for motion video. Minimal prompting. The workflow is addictive.

VIEW ON X →

kepano @kepano

Starting a set of Claude Skills for Obsidian, helping Claude Code edit .md, .base, and .canvas files.

VIEW ON X →

Ryan Singer @rjs

First time sharing the shaping skills I built for Claude. The workflow mirrors the human flow very closely.

VIEW ON X →

Aakash Gupta @aakashgupta

Skills don't auto-invoke reliably. You write "use when" and half the time it's ignored. Carl Vellotti fixed it with hooks, scripts that fire on events.

VIEW ON X →

Startup Ideas Pod @startupideaspod

/last-30-days replaced my whole research workflow. Reddit + X + web, last 30 days, synthesized. One command.

VIEW ON X →