Skills: Repeatable Process On Demand

The best Claude Code workflows are not clever prompts. They are reusable processes.

Here is a pattern that shows up constantly:

A developer asks Claude Code to fix a bug. Claude jumps to a fix. The fix does not work. The developer pastes the error. Claude tries another fix. Five turns later, everyone is tired and the bug is still there.

The problem is rarely the model alone. The problem is process.

Skills solve that.

What a Skill Is

A skill is a reusable capability packaged as instructions in a SKILL.md file, often with supporting files like scripts, templates, examples, or reference docs.

Claude Code can use a skill when it is relevant, or you can invoke one directly with /skill-name.

Create a skill when you keep pasting the same playbook into chat:

  • Debug this systematically.
  • Review this PR against our standards.
  • Run our release checklist.
  • Generate migration tests.
  • Produce the weekly engineering report.

If the process matters, it belongs in a skill.

Why Skills Beat Ad-Hoc Prompts

An ad-hoc prompt depends on what you remember to type today.

A skill captures the best version of the workflow once and makes it available every time.

That matters because many engineering tasks are procedural:

  • Reproduce before fixing.
  • Read examples before adding a new pattern.
  • Write the failing test before implementation.
  • Check security before shipping auth changes.
  • Verify generated artifacts before delivering them.

When those steps live in a skill, Claude sees the process at the moment it needs it.

Where Skills Live

Claude Code supports skills at several scopes:

  • Personal skills: ~/.claude/skills/<skill-name>/SKILL.md
  • Project skills: .claude/skills/<skill-name>/SKILL.md
  • Plugin skills: bundled with a Claude Code plugin
  • Enterprise-managed skills: distributed by an organization

A minimal skill looks like this:

---
name: release-check
description: Run the release readiness checklist before a production deploy.
disable-model-invocation: true
---

Run the release checklist:

1. Confirm the current branch and diff.
2. Run unit tests.
3. Run integration tests.
4. Check pending migrations.
5. Confirm rollback steps.
6. Summarize blockers before any deploy command.

The description matters. Claude uses it to decide when the skill applies.

Skills Can Be Manual or Automatic

By default, a skill can be invoked by you and discovered by Claude.

For workflows with side effects, make the skill manual-only:

disable-model-invocation: true

Use this for deploys, commits, account changes, or anything where you do not want Claude deciding on its own that it is time to act.

You can also hide a skill from the slash menu with:

user-invocable: false

That is useful for background knowledge skills that Claude should apply when relevant, but that are not meaningful commands for a user to run directly.

What Belongs in a Skill

Good skill content is procedural and specific.

Include:

  • When to use it.
  • What to inspect first.
  • The required sequence.
  • What not to do.
  • Verification steps.
  • Expected output format.

Avoid:

  • Vague advice.
  • Giant reference dumps.
  • Project facts that belong in CLAUDE.md.
  • One-off task details.

If a skill gets long, move detailed material into supporting files and link to them from SKILL.md. Claude Code can load those files when needed instead of stuffing every detail into context up front.

Supporting Files Make Skills Powerful

A skill directory can contain more than SKILL.md:

.claude/skills/api-migration/
  SKILL.md
  examples.md
  compatibility-matrix.md
  scripts/
    scan-imports.sh
    validate-migration.sh

This is the real advantage over a one-file prompt. A skill can carry the process, examples, helper scripts, and validation logic together.

Use supporting files for:

  • Long examples
  • Reference docs
  • Checklists
  • Reusable scripts
  • Templates

Keep SKILL.md as the map. Put the depth in files Claude can open only when needed.

Pre-Approve Tools Carefully

Skills can use allowed-tools to grant tool permissions while the skill is active.

Example:

allowed-tools: Bash(git status *) Bash(git diff *)

This reduces permission friction, but it does not restrict all other tools. It grants permission for listed tools; deny rules still belong in Claude Code permissions.

Use tool pre-approval sparingly. It is excellent for read-only workflows and repetitive checks. Be more conservative with commands that write, deploy, delete, or push.

Skills vs CLAUDE.md

Use CLAUDE.md for persistent context that should be present in every session:

  • Build commands
  • Code style conventions
  • Repo layout
  • Durable project rules

Use skills for procedures:

  • Debug workflow
  • PR review workflow
  • Release workflow
  • Migration workflow
  • Incident response workflow

If a section of CLAUDE.md starts looking like a checklist, it probably wants to become a skill.

A Practical Debug Skill

A good debug skill might require Claude to:

1. Restate expected vs actual behavior. 2. Identify the smallest reproduction. 3. Run or ask for the failing command. 4. Locate the failure boundary. 5. Form one hypothesis at a time. 6. Test the hypothesis before editing. 7. Make the smallest fix. 8. Re-run the failing check. 9. Summarize root cause and prevention.

That sequence is boring in the best way. It prevents the random-walk debugging that burns entire afternoons.

The Skill Habit

Ask this after every repeated workflow:

Did I just paste a process I have pasted before?

If yes, write a skill.

The payoff compounds. Every skill is a small piece of engineering judgment you never have to retype again.

Sources

Part 4 of a seven-part series on using Claude Code efficiently.