Claude Code Skills Primer — Build Your Own Commands with SKILL.md

An overview of Claude Code "skills." A skill is a folder with instructions in a SKILL.md, and it becomes a homemade command callable as /skill-name. The older "custom slash commands" (.claude/commands/*.md) were merged into skills (the old format still works).

What is a skill?

• Write instructions in a SKILL.md and it can be invoked by you as /name or loaded automatically by Claude when a related task comes up
• The difference from CLAUDE.md is load timing. CLAUDE.md enters the context in full every session, while a skill keeps only its description resident and loads its body on use. Long procedures are cheaper as skills
• Rule of thumb: "facts and conventions" go in CLAUDE.md, "procedures and checklists" go in skills. Pasting the same instructions into chat twice is the signal to make a skill

Where skills live

• On name collisions, personal beats project. Bundled skills (/code-review etc.) can also be overridden by a same-named skill of yours
• In a monorepo, subdirectory .claude/skills/ folders are auto-discovered too (they get directory-qualified names like apps/web:deploy)
• Adding or editing files takes effect immediately, no session restart

Writing SKILL.md

---
name: deploy
description: Deploy the app to production. Use when asked to deploy or release
disable-model-invocation: true
---

Deployment steps:

1. Run the tests
2. Build
3. Push to the deployment target

All frontmatter is optional (though you should write description — Claude uses it to decide on automatic invocation). The main fields:

Who can invoke what

Arguments and dynamic context

• $ARGUMENTS = all invocation arguments. $0 $1 reference them individually; with arguments: [issue, branch] in frontmatter you get named ones like $issue
• Writing !`command` in the body means the command runs before Claude reads the skill and its output replaces the placeholder — dynamic context injection
  • Example: embed !`git diff HEAD` and the skill always starts with the latest diff already in its body
• ${CLAUDE_SKILL_DIR} references the skill's own directory, ${CLAUDE_PROJECT_DIR} the project root

Companion files

A skill is a folder, so files other than SKILL.md can live there too.

my-skill/
├── SKILL.md        ← the core (required; keep under ~500 lines)
├── reference.md    ← detailed material (read only when needed)
└── scripts/
    └── helper.js   ← a script Claude executes

Reference them from SKILL.md ("see reference.md for details") and Claude reads them only when necessary. The thinner the main body, the better the token efficiency.

Real examples from this repo

This monorepo keeps the following under .claude/skills/, all operated as "invoked by me" (the disable-model-invocation style):

• /commit — commit message conventions (Conventional Commits + Japanese summaries) and the push procedure
• /blog-article — the procedure for generating app-introduction articles in 6 languages (screenshot commands included)
• /x-announce — demo GIF capture and post drafting for X announcements (with a character-count script bundled)

Turning "the procedure I explained every time" into a skill reduces the request to a single /blog-article. Bundling scripts is the killer feature: fixed processing like GIF encoding and character-count validation is frozen into .js files inside the skill.

Summary

• A skill = a homemade command that exists by placing a SKILL.md. Its body loads only on use, so it is cheaper than CLAUDE.md
• Side-effecting procedures get disable-model-invocation: true to stay you-only
• The practical power moves: !`command` dynamic injection and bundled helper scripts
• Details in the official docs