Skills & Slash Commands

The problem skills solve

Some knowledge is needed sometimes: how to cut a release, your PDF-form-filling procedure, the steps to triage a GitHub issue. Putting it in CLAUDE.md loads it into every conversation forever — the bloat problem from the memory lesson. Re-explaining it each time it's needed wastes your time and produces inconsistent results.

A skill is the middle path: packaged expertise that costs almost nothing until the moment it's relevant, then loads fully.

Anatomy of a skill

A skill is a folder in .claude/skills/ containing a SKILL.md file — YAML frontmatter (name and description) followed by markdown instructions:

---
name: fix-issue
description: Fix a GitHub issue end to end - fetch, implement,
  test, and open a PR. Use when given an issue number to resolve.
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS:

1. Run: gh issue view $ARGUMENTS - read the full description.
2. Search the codebase for the relevant files.
3. Implement the fix; address the root cause, not the symptom.
4. Run the affected tests, then lint.
5. Commit with a message referencing the issue and open a PR.

Skills trigger two ways: Claude applies one automatically when the task matches its description, or you invoke it explicitly as a slash command — /fix-issue 1234 — where $ARGUMENTS receives whatever you typed after the name.

Progressive disclosure: why skills scale

The core design idea is that skill content loads in stages, each stage only when needed:

1. At startup: only each skill's name and description — roughly 30-50 tokens per skill.
2. When relevant: the full SKILL.md body.
3. When needed: bundled extra files (reference.md, forms.md) and scripts.

This is why you can accumulate dozens of skills without taxing every conversation. Compare with CLAUDE.md, which is fully loaded always. The rule from the memory lesson completes here: always-needed context in CLAUDE.md, sometimes-needed expertise in skills.

Bundle scripts for mechanical work

A skill folder can include executable scripts, and this matters more than it sounds. For operations that must be exactly right every time — extracting PDF form fields, transforming a data file — a bundled Python script beats asking the model to regenerate equivalent code each session. Code is deterministic; token generation is not. The skill's instructions simply say "run scripts/extract_fields.py", and reliability stops depending on generation quality.

Manual-only invocation

By default Claude may invoke a skill whenever it judges it relevant. For workflows with side effects — deploying, opening PRs, sending anything — that's wrong: you want them to fire only when you say so. Set disable-model-invocation: true in the frontmatter, and the skill becomes a pure slash command: never auto-triggered, always available as /name args.

The decision rule: informational skills (how our API pagination works) can auto-trigger; side-effecting workflows (release, deploy, PR) should be manual-only.

Authoring skills that actually work

Write skills evaluation-first. Don't write a skill from imagination. Run Claude on representative tasks, watch where it struggles or goes wrong, and capture the fix as a skill. A useful trick: after a failure, ask Claude to self-reflect on what context it was missing — the answer is often the skill's first draft.

Name and description are the trigger. Claude matches tasks against descriptions, so a vague description ("helps with issues") mis-triggers and a precise one ("fix a GitHub issue end to end; use when given an issue number") fires correctly. After deploying, monitor real usage: is it firing when it shouldn't? Failing to fire when it should?

Separate mutually exclusive contexts. One skill covering two unrelated workflows loads irrelevant instructions half the time. Split it.

An open standard — with the usual caveat

Agent Skills launched as an open standard in October 2025 and has been adopted across the industry — OpenAI, Google, GitHub, and Cursor tooling all support the format, so skills you write are portable beyond Claude Code. The flip side: third-party skills are instructions plus executable scripts that run with your permissions. Audit them like any executable dependency you'd add to a project — because that's exactly what they are.

Skill, CLAUDE.md, or hook?

If you catch yourself explaining the same workflow to Claude a third time, that's the signal: it should have been a skill two explanations ago.