Create Claude Code Skills and Slash Commands for Repeatable Work

Quick answer

A Claude Code skill is a directory containing SKILL.md with metadata and instructions, plus optional references, scripts, or assets. Skills load reusable knowledge on demand, while CLAUDE.md holds always-relevant rules. See Anthropic's current skills guide.

Minimal skill

.claude/skills/release-check/
└── SKILL.md

---
name: release-check
description: Verify a release candidate, generate release notes, and report blockers. Use when preparing or reviewing a release.
---

# Release check

1. Read the repository release instructions and current version.
2. Compare changes with the previous tag.
3. Run the documented build, tests, and package checks.
4. Identify breaking changes, migrations, and security-sensitive updates.
5. Draft release notes from verified changes only.
6. Report commands, results, blockers, and rollback considerations.

Never publish, tag, or push unless the user explicitly requests it.

The description is routing logic. State both what the skill does and when it should activate.

Progressive disclosure

Keep the main file procedural. Put detailed material in referenced files:

release-check/
├── SKILL.md
├── references/
│   ├── mobile.md
│   └── database.md
└── scripts/
    └── verify-package.sh

Tell Claude exactly when to read each reference. This prevents every invocation from loading irrelevant material.

Design skills around outcomes

Good skills produce an artifact or decision:

• /incident-triage: evidence timeline, leading hypothesis, next discriminator.
• /api-review: contract compatibility and concrete breaking scenarios.
• /migration-plan: reversible steps, validation, rollback, ownership.
• /release-check: verification matrix and release notes.

Avoid a skill that merely says “be an expert.” It has no workflow and no completion test.

Safe script usage

Scripts are useful for deterministic checks. They should be readable, parameterized, fail loudly, avoid hidden external writes, and never embed credentials. Document prerequisites and expected output. A skill must not turn an opaque script into an approval bypass.

Test activation and behavior

Run three evaluations:

1. Positive: “Prepare version 3.2 for release.” The skill should activate.
2. Negative: “Explain semantic versioning.” It should not hijack a general question.
3. Adversarial: a release task with failing tests. It must report a blocker rather than draft a success claim.

Then inspect context cost. If the skill loads thousands of unused words, split references or narrow the description.

Skill vs hook vs subagent

• Skill: reusable instructions or knowledge.
• Hook: deterministic action triggered by an event.
• Subagent: isolated worker with its own context.
• MCP: connection to external tools/data.
• Plugin: distributable bundle of these features.

Version and govern team skills

Treat a shared skill as production code. Give it an owner, review changes, pin any executable dependencies, and record behavior-changing releases. When a repository command or policy changes, update the skill and its evaluation fixtures in the same pull request. A stale workflow can be more dangerous than no workflow because it executes with borrowed authority.

Run a periodic inventory of skill descriptions, tool access, scripts, references, and actual usage. Remove duplicates and narrow descriptions that trigger too often. Check that disable/manual-invocation controls match the intended context and security model. If a skill can publish, deploy, delete, message, or change external state, split assessment from mutation and require explicit authorization for the latter.

Build a useful completion artifact

A mature skill returns a stable, reviewable format rather than free-form enthusiasm. For a migration skill, that might be assumptions, forward steps, validation queries, rollback boundary, ownership, observability, and unresolved decisions. The format lets humans compare runs and lets automated evaluation assert that critical fields are present.

FAQ

Are skills the same as old custom slash commands?

Skills are the current general mechanism for reusable, invocable workflows; existing command patterns can be migrated into skills.

Can a skill run automatically?

Claude can select a skill when its description matches the task, and users can invoke eligible skills directly. Write precise descriptions and test both behaviors.

Should every team workflow become a skill?

No. Create a skill when the workflow repeats and benefits from consistent instructions. Keep one-off task detail in the prompt.